# Delivery Hero — Restaurant Integration API (POS)

> Kaynak: https://developers.deliveryhero.com/documentation/pos.html#introduction
>
> Bu dosya, yukarıdaki bağlantıdaki dokümantasyonun önemli içeriğinin yerel kopyasıdır.

---

## Introduction

Through seamless POS Integration, vendors and POS providers reach a new level of
intercommunication. Vendors can process orders through their POS System using
Delivery Hero's integration solution.

This documentation contains all information to start your POS Integration with
Delivery Hero.

## 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 adapter 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 runs on a device provided by the Delivery Hero Platform.

## Integration Process

1. Request Credentials
2. Develop your Plugin
3. Provide the Plugin URL to your local representative (must support HTTPS using a
   valid SSL certificate)
4. Test orders from a test vendor (local representative will share test vendor details)
5. Rollout

## Request Credentials

You must request credentials to connect with Integration Middleware and start
receiving orders.

- To request credentials, provide a valid **Public PGP Key**.
- After approval, your local representative shares your Credentials, **encrypted with
  the PGP key** provided in the request form.

Credentials are composed of:

- **Username**
- **Password**
- **Secret**

## Order Integration Flows

Delivery Hero offers order integration through two flows:

### Indirect Flow

Vendor is equipped with a Delivery Hero Vendor App to manage (accept/reject) incoming
orders on a tablet. The Integration Middleware forwards **only accepted orders** to
the POS System.

Flow (example vendor `BONJOUR`):

1. Customer places an order at a `BONJOUR` restaurant on a DH platform (e.g. Foodpanda).
2. Foodpanda pushes the order to the DH `BONJOUR` Vendor App (on a DH-provided device).
3. An employee at the vendor location accepts the order on the Vendor App.
4. Order is pushed to Integration Middleware, which forwards it to the `BONJOUR` plugin.
5. Plugin dispatches the order to the POS System of `BONJOUR`.

> **Note:** Orders reach the plugin only if accepted on the Vendor App first. Rejected
> or unaccepted orders are never forwarded to the POS System.

### Direct Flow

Vendor has no Vendor App and uses only its POS system to process DH orders. Each POS
Client communicates with DH resources **only through a plugin**.

Flow (example vendor `BONJOUR`):

1. Customer places an order at a `BONJOUR` vendor on a DH platform (e.g. Foodpanda).
2. Foodpanda pushes the order to Integration Middleware.
3. Integration Middleware forwards the order to the `BONJOUR` plugin.
4. Plugin dispatches the order to the `BONJOUR` POS System.
5. An employee at the vendor location must accept or reject the order on the POS software.

> **Note:** Direct Integrations are allowed case by case. Contact your local point of
> contact to agree on using Direct Flow.

#### Requirements (Direct Flow)

Plugin and POS System must provide the same service level as a DH Vendor App:

- Manually accept and reject orders on the POS System at the vendor location.
- Handle order cancellations after an order was accepted on the POS System.
- Mark that vendor is closed/busy for X amount of time (optional).
- Indicate a delay of order delivery time (optional).
- Send back delivery time to DH when an order is accepted (programmable or manual),
  including a unique order identifier on the Vendor side.
- Provide a reject reason when an order is rejected (per the available reject reason list).
- Notify DH (manual push or algorithm) when the order is ready to be picked up by the driver.
- Send "unreachable" status for a vendor that is not reachable from the POS System.
- Send "reachable" status again when the vendor is back online.
- Use the DH Vendor App as a fallback if order transmission between Middleware and
  plugin has issues.

## Build the Plugin

- You must build a plugin to receive orders from Delivery Hero.
- Your plugin translates incoming orders into a language your POS system understands.
- Technical specification of all plugin-scope endpoints/actions: see `API_DOC.md`
  (POS Plugin API).

### Send Order Updates

- The Integration Middleware is used by chains/POS providers to accept or reject orders.
- Technical specification of Middleware-scope endpoints/actions: see `API_DOC.md`
  (POS Middleware API).

### Update Availability

- Integration Middleware API allows Vendors to state if they are open or closed.
- If closed, the vendor is marked offline on the DH platform and customers cannot order.

## Supported Platforms (Integration Middleware)

### Asia/Pacific

- Foodpanda (Bangladesh, Cambodia, Hong Kong, Japan, Laos, Malaysia, Myanmar,
  Pakistan, Philippines, Singapore, Taiwan, Thailand)

### Middle East / North Africa

- Hungerstation (Saudi Arabia)
- Otlob (Egypt)
- Talabat (United Arab Emirates, Kuwait, Bahrain, Oman, Qatar, Jordan)

### Europe

- Damejidlo (Czech Republic)
- eFood (Greece)
- Foodora (Sweden, Finland, Norway)
- Foodpanda (Bulgaria, Romania)
- Hungry (Denmark)
- Mjam (Austria)
- Netpincer (Hungary)
- Pauza (Croatia)

### Latin America

- PedidosYa (Argentina, Bolivia, Chile, Panama, Paraguay, Uruguay, Dominican Republic,
  Venezuela, Honduras, El Salvador, Nicaragua, Peru, Ecuador, Costa Rica, Guatemala)

## Post-production Agreement

- Plugin maintainer must inform DH about upcoming system maintenance by email at least
  24 hours in advance (strongly advised for Indirect flow, **compulsory for Direct flow**).
- Plugin maintainer must provide contact details for DH to escalate technical issues
  (crucial for monitoring and reliable order dispatching).
- DH may disable the integration whenever there is a technical issue with the plugin and
  the provided contact is not responding; re-activated once fixed.
- Some features or the whole integration may be disabled if implementation contract
  articles are not fulfilled. Common missing implementation points:
    - Working cancellation endpoint on plugin side.
    - Rejecting an order without providing a proper reject reason (`order_rejected`).
    - Accepting an order with wrongly formatted date time (`order_accepted`).
    - Providing a secured plugin endpoint that cannot be validated by a curl command.

## Get Order Details

- Integration Middleware provides an **Order Report Service** to query order details for
  orders placed less than 24 hours ago.
- Not meant for order processing; only to request additional information for specific
  orders. Currently canceled and accepted orders are supported.

## Update Menu (Catalog Import API)

- Manual catalog updates are time-consuming, resource-heavy, and error-prone.
- The **Catalog Import API** lets POS Vendors push catalog changes automatically to the
  platforms (replacement of the legacy **Menu Import API**).
- New implementations for the legacy Menu Import API are **not allowed**; vendors already
  on it should migrate once the Catalog Import API is stable.
- Weigh benefits vs. implementation/maintenance overhead if catalog changes are infrequent.