Introduction to Delivery Hero’s Integration APIs
Delivery Hero’s POS Middleware APIs enable partners to programmatically manage orders, menus, and stores on Delivery Hero’s delivery platforms.
Overview
To provide a seamless integration experience, available API endpoints are categorized into two categories:
Integration Middleware API means endpoints to be called by pos plugins (maintained by Delivery Hero)
Plugin API means endpoints to be implemented by pos partners to receive orders and updates from platforms (maintained by POS partners)
Order Management
Store Management
Order Report Service
Getting started
Prerequisites
Before beginning the development, please ensure:
Completed Non-disclosure agreement. Don’t have an agreement? Please reach out to your PedidosYa contact or submit the request here
Received confirmation from PedidosYa contact to begin the development
Process Overview
Request access to Delivery Hero’s Integration APIs
Set up a test integration
Begin development
Perform end-to-end testing with your PedidosYa contact
Set up your production integration
Set up and launch pilot vendor(s)
Continue setting up and launching vendors
Maintain integration and adopt new API features
Access and Integration Configuration
Getting access
To get access to Integration APIs, you will need a credential (username and password).
Step 1: Submit a credential request
Generate a PGP key pair: For security purposes, we will need your PGP public key to encrypt the credential before sending it to you via email. You can download the tool for PGP key generation here and generate a key pair.
Fill in the form: Submit the request by filling in the aggregator credential request form here.
Step 2: Let your PedidosYa contact know and approve your request
After submitting the request, let your PedidosYa contact know, so they can check and approve the request.
Step 3: Receive credential via email
You will receive the credential via email once your PedidosYa contact approves your request. Please also check your Spam folder, just in case the email appears there instead of your inbox.
Step 4: Decrypt credential message
Use your PGP private key to decrypt the credential.
Step 5: Get an access token
Use Login API to get an access token required to use other API endpoints.
Setting up Integration
Note: Staging environments must be used for development purposes.
Step 1: Understand integration, chains, vendors, and their relationship
Definition
Vendor is a single restaurant location who is operating on PedidosYa.
Chain is a restaurant chain, consisting of one or more vendors who usually share the same restaurant name, but are located in different locations.
Integration is defined as a plugin built by you to programmatically manage orders, menus, and stores on PedidosYa. The plugin contains a base URL used to receive notifications including order dispatch, order status update, etc.
Relationships and constraints
An integration consists of one or more chains.
A chain consists of one or more vendors.
Vendors can only be under one unique chain and integration.
Step 2: Provide following information to PedidosYa contact for integration activation
Integration
| Definition | Example | |
|---|---|---|
Integration Name | Name of your integration. Naming convention: company name and country | Perfect Integration Singapore |
Integration Code | Unique key for your integration. Naming convention: company-name-countrycode | perfect-integration-sg |
Base URL | A base URL of your plugin which is used to receive notifications including order dispatch, order status update, etc. Note: company name and country | https://api.perfect.integration.com/foodpanda-integration/ |
Plugin username | Username of your credential | perfect-integration-sg-username |
Chain(s)
| Definition | Example | |
|---|---|---|
Chain Name | Name of a restaurant chain. Naming convention: chain name and country | Yummy Singapore |
Chain Code | Unique key for restaurant chain Naming convention: chain-name-countrycode | yummy-sg |
Vendor(s)
Need a vendor for integration development and testing? You can request a test vendor from PedidosYa contact
| Definition | Example | |
|---|---|---|
Vendor Code | An identifier of the vendor. You can request the vendor code from your restaurant contact. | vndr |
Country | Country the vendor belongs to | Singapore |
Remote ID | A unique identifier of the vendor on your plugin. | 123456 |
Integration flow | Order integration flow: Direct or Indirect | Direct |
IP Address Whitelist
In order to receive orders from Integration Middleware, POS plugin needs to whitelist the following IP addresses.
| Region / Environment | Public IP Addresses |
|---|---|
Latin America | 54.161.200.26 54.174.130.155 18.204.190.239 |
Europe | 63.32.162.210 34.255.237.245 63.32.145.112 |
Middle East + Turkey | 63.32.225.161 18.202.96.85 52.208.41.152 |
Asia Pacific | 3.0.217.166 3.1.134.42 3.1.56.76 |
Staging environment | 34.246.34.27 18.202.142.208 54.72.10.41 |
Order Management
Overview
Use Order Management API to manage incoming orders from PedidosYa. Available functionalities are listed below:
Understanding Order Integration Flow
There are two options a vendor can choose to manage incoming orders from PedidosYa.
First Option: Indirect Integration
Vendor is equipped with a PedidosYa vendor device to manage incoming orders.
The diagram illustrates indirect order integration. It describes how an order is transmitted and processed by the vendor BONJOUR.
Customer places an order at a vendor belonging to vendor BONJOUR on Delivery Hero platform (i.e. PedidosYa).
PedidosYa pushes the incoming order to Delivery Hero’s vendor application, used by vendor BONJOUR
Employee at BONJOUR accepts the incoming order on Delivery Hero’s vendor application.
Note: Auto-accept functionality is possible. Please reach out to PedidosYa contact for details.
Accepted order is pushed to Integration Middleware which forwards order detail to plugin, communicated with BONJOUR’s POS system.
Note: Only orders accepted from Delivery Hero’s vendor application are forwarded to Plugin. Rejected and unaccepted orders are not forwarded to Plugin.
Plugin forwards the accepted order to BONJOUR’s POS system. The order can then be printed out or displayed in the kitchen.
Second Option: Direct Integration
Vendor is not equipped with a PedidosYa vendor device. Instead, the vendor uses their own POS system to process incoming orders from PedidosYa.
The diagram illustrates direct order integration. It describes how an order is transmitted and processed by the vendor BONJOUR.
Customer places an order at a vendor belonging to vendor BONJOUR on Delivery Hero platform (i.e. PedidosYa).
PedidosYa pushes the incoming order to integration middleware which forwards the order to plugin, communicated with BONJOUR’s POS system.
Plugin forwards the incoming order to BONJOUR’s POS system.
Employee at BONJOUR accepts the incoming order with BONJOUR’s POS system. The order can then be printed out or displayed in the kitchen.
Note: Auto-accept functionality can be implemented on Plugin, enabling the order to automatically shows on vendor’s POS system
Comparison between Indirect and Direct Order Integration
| Indirect Integration | Direct Integration | |
|---|---|---|
Order Management | Vendor manages the incoming order via Delivery Hero’s vendor app. Once an order is accepted on the app, it will be forwarded to the vendor's POS system. | Vendor manages the incoming order via its own POS’s system. |
Auto-Acceptance | With Delivery Hero’s vendor device, auto-acceptance of incoming orders can be turned on. | Auto-acceptance of incoming orders can be implemented on the plugin. |
Plugin Development Effort | Minimum development effort. Required endpoints for order processing:
Note: In case the order is canceled, the vendor will receive a notification via Delivery Hero’s vendor application. Optionally: Webhook Order Status Update can be implemented to receive notification of canceled orders. | Higher development effort. Required endpoints for order processing:
|
Delivery Hero’s vendor application as a fallback | In case there is an outage on the plugin, the vendor can continue to accept and process the orders via Delivery Hero’s vendor application. | In case there is an outage and thus the order cannot be received by the plugin, it will automatically be canceled after retries. Note: Read more about retry logic here. |
Store Management
Overview
Use Store Management API to manage the availability of stores on PedidosYa. Available functionalities are listed below:
Order Report Service
Overview
Use Order Report Service to retrieve the completed orders. Available functionalities are listed below:
Terminology
POS Clients: Chains or POS providers seeking to receive orders coming from Delivery Hero directly on their POS System.
Vendors: Physical location where the food is prepared.
POS System: Point-of-sale software on POS Clients side which compiles orders and transactions (online and offline) for a certain number of vendors.
Integration Middleware: Delivery Hero order transmission system, in charge of forwarding orders placed on Delivery Hero platforms to the Vendor POS System.
Plugin: Adapter to be created by the POS Clients if they want to do POS Integrations with Delivery Hero. This adaptor serves to allow communication between - Delivery Hero Integration Middleware and Vendor POS System.
Delivery Hero Vendor App: Delivery Hero application for vendors where orders placed on a Delivery Hero platform can be processed (accepted or rejected). This application is running on a device provided by Delivery Hero Platform.
Platform Vendor ID: an identifier of a restaurant on Delivery Hero Platform (i.e. PedidosYa). Also known as vendor code.
Remote ID: a unique identifier of the vendor on your plugin.
Frequently Asked Questions
Q: Why is an SSL certificate required?
A: An SSL certificate of Plugin’s web server is required in order to ensure secure communication between Integration Middleware and Plugin.
Q: Which IP Addresses Plugin needs to whitelist to receive orders from Integration Middleware?
A: IP Addresses can be found on this section.
Q: Is base URL with port number (e.g. https://pos.anydomain.com:3154) allowed?
A: Yes.
Q: How to map product ID on POS plugin / system (i.e. remoteCode) to product ID on PedidosYa?
A: Mapping can be achieved by
PUT
Submit Catalog. If Plugin does not implement this endpoint, please reach out to your PedidosYa contact for manual product mapping.Q: What is the image requirement on PUT Submit Catalog?
A: The image requirement is described here.
Post Production Agreement
Plugin maintainers should inform Delivery Hero about their upcoming system maintenance by sending an email ([email protected]) at least 24 hours in advance. This is strongly advised for Indirect flow and compulsory for Direct flow.
Plugin maintainer should provide contact details which will be used by Delivery Hero to escalate technical issues with the plugin. This is crucial for monitoring and reliable order dispatching.
The integration might get disabled by Delivery Hero whenever there is a technical issue with the plugin and provided contact is not responding. The integration will be reactivated once the issue is fixed by plugin maintainers.
Some features of an integration or even the whole integration might get disabled whenever certain articles of the implementation contract are not fulfilled.
Few common examples of missing implementation points:
Working cancellation endpoint on plugin side.
WebhookOrder Status Update is required to be implemented by vendors who are operating on direct integration to receive notification of canceled orders.Rejecting an order while not providing a proper reject reason.
Click order_rejected on the body schema of
POSTUpdate Order Status to see all the possible reasons.Accepting an order with wrongly formatted datetime.
Click order_accepted on the body schema of
POSTUpdate Order Status to see the formatted datetime required.Providing a secured plugin endpoint which cannot be validated by curl command. More about the plugin’s security.