openapi: 3.0.3 info: title: Open Delivery API version: 'v1.7.1' license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0 contact: url: https://www.opendelivery.org.br x-author: Guilherme Munhoz Camargo x-logo: url: https://gui-camargo.github.io/OD/logo-open-delivery_small.png altText: Open Delivery logo description: |- # ► --- OPEN DELIVERY --- ◄ # └► Introduction **Open Delivery** proposes to solve the challenge of organizing the flow of information between merchants and **Ordering Applications**, establishing a single communication standard for all, through a set of REST APIs. Thus, menus and orders are standardized and customer requests are received in a single place, in an organized and efficient way, allowing the merchant to work with more partners in the delivery environment. # └► Table Of Contents The documentation is separated as follows: **[General and Common Information](#section/-GENERAL-INFO-)** This is information that is valid for all versions that exist so far. - **[How to Start](#section/How-to-Start-(Setup-Guide))** - **[Open Delivery API Evolution](#section/Open-Delivery-API-Evolution)** - **[General Guidelines](#section/General-Guidelines)** - **[Error Handling](#section/Error-Handling)** **API Reference** - **[Security](#tag/securitySection)** - **[Order](#tag/ordersSection)** - **[Merchant](#tag/merchantSection)** - **[Logistics](#tag/logisticsSection)** - **[Configurations](#tag/versionsSection)** # └► Changelog Latest Changes: ### Version [v1.7.1] - Aug 03, 2026 This version is a patch release with the following change: #### ORDERS changes - [GET /orders/{orderId}](#operation/ordersDetails) - Added new optional field `billingAddress` to the `takeout` object within the Order schema. This is the customer's billing address, added to comply with fiscal regulation (Ajuste SINIEF nº 9/2026) that requires billing address information for TAKEOUT order types to enable NFC-e issuance. -------------------------------------- ### Version [v1.7.0] - Jan 05, 2026 This version is a minor release, with the following changes: #### ORDERS changes - [GET /orders/{orderId}](#operation/ordersDetails) - Added new enum value `MIN_ORDER_FEE` to `otherFees.type` in endpoint `GET /v1/orders/{orderId}` to support minimum order fee charges. This is a complementary fee applied to orders that do not meet the minimum order value requirement. #### MERCHANT changes - Added endpoint `GET /v1/merchant/{id}/status` to retrieve merchant status, service hours, and orderingAppMerchantId. - [PUT /merchantOnboarding](#operation/putMerchantOnboarding) - Added `orderingAppMerchantId` field to the response body to provide the internal merchant identifier from the Ordering Application. #### OTHERS changes - Bug fixes and general corrections in the documentation texts and links. -------------------------------------- > To see previous versions changes, access the full [CHANGELOG](https://abrasel-nacional.github.io/opendelivery/CHANGELOG). # └► Issues and Suggestions In case of doubts, suggestions, improvements, problems or any information regarding the documentation presented here, access the project's Github repo and open a new issue. > https://github.com/Abrasel-Nacional/opendelivery/issues # └► Sandbox You can test the endpoints described in this documentation through the Open Delivery Sandbox Portal, available at > https://developer.opendelivery.com.br In the portal you can register your application to receive your access credentials. The sandbox environment also has some specific functions that simulate the actions of the `Ordering Application` that are not described here in this documentation. # └► Developer Tools This section has some tools to help you implement the Open Delivery API. **Disclaimer**: The tools listed below are tools made available by partners of the Open Delivery project and are the sole responsibility of their authors. The Open Delivery does not provide support for these tools. **SCHEMA VALIDATORS** > [Open Delivery - API Schema Validator (by Programmers IT)](https://programmersit.github.io/opendelivery-api-schema-validator/) > Tool for comparing a JSON file with Open Delivery schemas. **MERCHANT RELATED TOOLS** > [Open Delivery - Menu Generator (by Programmers IT)](https://programmersit.github.io/opendelivery-menu-generator/) > Tool for graphical visualization of the different fields and entities that compose the Merchant object. # └► Versions This section has links to all versions of Open Delivery: - **RELEASE** Contains the standards already published: **MERCHANT** | **ORDERS** | **LOGISTICS** - [2.0.0-rc.X (Release Candidate*)](https://abrasel-nacional.github.io/opendelivery/versions/rc/) - **v1.7.0 - (LATEST RELEASE)** - [v1.5.0](https://abrasel-nacional.github.io/opendelivery/versions/1.6.0/) - [v1.5.0](https://abrasel-nacional.github.io/opendelivery/versions/1.5.0/) - [v1.4.0](https://abrasel-nacional.github.io/opendelivery/versions/1.4.0/) - [v1.3.0](https://abrasel-nacional.github.io/opendelivery/versions/1.3.0/) - [v1.2.1](https://abrasel-nacional.github.io/opendelivery/versions/1.2.1/) - [v1.2.0](https://abrasel-nacional.github.io/opendelivery/versions/1.2.0/) - [v1.1.1](https://abrasel-nacional.github.io/opendelivery/versions/1.1.1/) - [v1.1.0](https://abrasel-nacional.github.io/opendelivery/versions/1.1.0/) - [v1.0.1](https://abrasel-nacional.github.io/opendelivery/versions/1.0.1/) - [v1.0.0](https://abrasel-nacional.github.io/opendelivery/versions/1.0.0/) > *Release Candidate versions contains the evolutions and improvements being discussed at the moment and that will be part of the release version in the future. - **BETA** Contains the standards still in tests: **FINANCIAL RECONCILIATION** | **CONTRACTS** - [BETA VERSION](https://abrasel-nacional.github.io/opendelivery/versions/beta/) # # ► --- GENERAL INFO --- ◄ # └► How to Start (Setup Guide) The Open Delivery API proposes the implementation of a single communication standard between the various parts that make up the delivery environment. This documentation contains all the definitions needed for interested systems and platforms to implement it. Open Delivery does not have a server or baseURL. It is up to each company that implements the standard to use its infrastructure to host the endpoints. You can use the **[Sandbox Enviroment](#section/Sandbox)** to test your requests and responses, but there is no Production Enviroment. Once your system or platform is compliant to the standard, you will be able to integrate with other companies also compliant to the standard. This section seeks to summarize the Open Delivery documentation as a whole, helping the different parts of the integrations to understand what needs to be developed and parameterized. First, it is recommended to read all the documentation to understand the different processes and flows of the integrations. After reading and understanding the documentation as a whole, companies interested in implementing the standard in their platforms and systems can use this guide to assist in the implementation. ## Parties Involved - **ORDERING APPLICATION**: It is the platform where the final consumer will choose his items and place the order. It is responsible for reading the merchant data exposed by the SOFTWARE SERVICE and sending the orders to the SOFTWARE SERVICE as well. - **SOFTWARE SERVICE**: It is the merchant management platform. It is responsible for exposing the merchant data (registration data, service data, and menus) and receiving the orders from the ORDERING APPLICATION. > There may also be applications that will perform a hub function, connecting the ORDERING APPLICATION to the SOFTWARE SERVICE. In this context, these intermediate applications, can play the role of both the ORDERING APPLICATION (when communicating with a SOFTWARE SERVICE) as well as the SOFTWARE SERVICE (when communicating with the ORDERING APPLICATION). - **LOGISTIC SERVICE**: It is the platform responsible for receiving calls for new deliveries from SOFTWARE SERVICE or ORDERING APPLICATION, and sending the tracking of the deliveries. ## Development Since Open Delivery is not the host of the APIs, it is up to the companies interested in using the standard to develop the Open Delivery standard APIs in their systems and platforms using this documentation as a guideline. Listed below are the different Routes that each party needs to implement and make available in their systems: | |ORDERING APPLICATION|SOFTWARE SERVICE|LOGISTICS SERVICE| |-|:------------------:|:--------------:|:---------------:| |**[AUTHENTICATION](#tag/authentication)**|||| |[POST /oauth/token](#operation/getToken)|X||X| |--------------------------------|||| |**[MERCHANT](#tag/merchantSection)**|||| |[GET /merchant](#operation/getMerchant)||X|| |[POST /merchantUpdate](#operation/menuUpdated)|X||| |[GET /merchantStatus](#tag/merchantStatus)|X||| |[PUT /merchantOnboarding](#operation/putMerchantOnboarding)|X||| |--------------------------------|||| |**[ORDER](#tag/ordersSection)**|||| |[GET /events:polling ](#operation/pollingEvents)|X||| |[POST /events/acknowledgment](#operation/pollingAcknowledgment)|X||| |[POST /orderUpdate (WEBHOOK)](#operation/newEvent)||X|| ||||| |[GET /orders/{orderId}](#operation/ordersDetails)|X||| |[PATCH /orders/{orderId}/details](#operation/patchOrderDetails)|X||| |[POST /orders/{orderId}/confirm](#operation/confirmOrder)|X||| |[POST /orders/{orderId}/preparing](#operation/orderPreparing)|X||| |[POST /orders/{orderId}/readyForPickup](#operation/orderReady)|X||| |[POST /orders/{orderId}/pickedUp](#operation/orderPickedUp)|X||| |[POST /orders/{orderId}/dispatch](#operation/dispatchOrder)|X||| |[POST /orders/{orderId}/delivered](#operation/orderDelivered)|X||| |[POST /v1/orders/{orderId}/validateCode](#operation/orderValidateDelivery)|X||| ||||| |[POST /orders/{orderId}/requestCancellation](#operation/requestCancellation)|X||| |[POST /orders/{orderId}/acceptCancellation](#operation/cancellationAccepted)|X||| |[POST /orders/{orderId}/denyCancellation](#operation/cancellationDenied)|X||| ||||| |[POST /orders/{orderId}/tracking](#operation/orderTracking)|X||| |--------------------------------|||| |**[LOGISTICS](#tag/logisticsSection)**|||| |[POST /logistics/delivery](#operation/logisticsNewDelivery)|||X| |[POST /logistics/readyForPickup/{orderId}](#operation/logisticsReadyForPickup)|||X| |[POST /logistics/orderPicked/{orderId}](#operation/logisticsPicked)|||X| |[POST /logistics/finishDelivery/{orderId}](#operation/logisticsFinish)|||X| |[POST /logistics/handleProblem/{orderId}](#operation/logisticsProblem)|||X| |[POST /logistics/cancel/{orderId}](#operation/logisticsCancel)|||X| |[GET /logistics/delivery/{orderId}](#operation/logisticDetails)|||X| |[POST /logistics/availability](#tag/logisticPrice)|||X| |[POST /deliveryUpdate (WEBHOOK)](#operation/newLogisticEvent) |X|X|| |[POST /logistics/confirmationCode (WEBHOOK)](#operation/logistictsDeliveryCode) |X|X|| ## Parametrizations > **IMPORTANT: Before reading this section, it is recommended the reading of the complete documentation, for a better understanding of the different required parameterizations.** Once the endpoints are implemented, the parties interested in integrating via the Open Delivery standard should provide some parameters for the other party to correctly connect to its routes. Below is a list of information that each party must provide to the other party for the integrations to occur, i.e., you should consider that the information below will be created as parameters on the system that will call the endpoints. ### Orders / Merchant API - **PARAMETERS IN THE SOFTWARE SERVICE (ORDERING APPLICATION --> SOFTWARE SERVICE)** - **{baseURL}** : The {baseURL} is the parameter that indicates the base address, i.e. the constant part of the address, where the routes will be called. The **Ordering Application** can provide up to 2 different base URLs: - {baseURL} for authentication: where the token route will be hosted. - {baseURL} for the other routes. The **Ordering Application** can use only one {baseURL} if it wishes. - **clientId** and **clientSecret**: The **Ordering Application** is responsible for providing the credentials for authentication to be performed through the authentication endpoint. > IMPORTANT: As described in the authentication section of the documentation, credentials must be generated BY MERCHANT and not by **Software Service**, that is, even if several MERCHANTS use the same **Software Service**, each of the MERCHANT will have a unique clientId and clientSecret. - **AppId**: It is the unique ID of the **Ordering Application**. It must be generated by the **Ordering Application** itself, and once generated, it must be informed to all the **Software Services** that it will integrate. Since the **AppId** is a unique key of the **Ordering Application**, you must not create one **AppId** per **Software Service**, but use the same key for all of them. > The companies that play the role of hub, intermediating the integrations between the **Ordering Application** and the **Software Service**, must also generate their own **AppId**, different from the **Ordering Application**'s AppId. - **PARAMETERS IN ORDERING APPLICATION (SOFTWARE SERVICE --> ORDERING APPLICATION)** - **[GET /merchant](#tag/merchantEndpoints) endpoint URL:** The **Ordering Application** must be provided with the URL to access the `GET /merchant` route to obtain the merchant's information. > IMPORTANT: Each merchant that the **Software Service** works with must have a unique URL. - **apiKey**: If the GET /merchant endpoint is implemented using authentication, it is necessary that the **Software Service** provides the apiKey referring to the entered merchant. - **Order Event Webhook**: If both parties are going to work with sending order events via webhook, it is necessary to provide the URL of the webhook. Default webhook route: `POST {baseURL}/newEvent` ### Logistics API - **PARAMETERS IN THE SOFTWARE SERVICE/ORDERING APPLICATION (LOGISTIC SERVICE --> SOFTWARE SERVICE/ORDERING APPLICATION)** - **{baseURL}** : The {baseURL} is the parameter that indicates which is the base address, i.e. the constant part of the address, where the routes will be called. The **Logistic Service** can provide up to 2 different base URLs: - {baseURL} for authentication: where the token route will be hosted. - {baseURL} for the other routes. The **Logistic Service** will be able to use only one {baseURL} if it wishes. - **clientId** and **clientSecret**: The **Logistic Service** is responsible for providing the credentials for authentication to be performed through the authentication endpoint. > IMPORTANT: As described in the authentication section of the documentation, the credentials must be generated BY MERCHANT and not by **Software Service**/**Ordering Application**, that is, even if several MERCHANTS use the same **Software Service**/**Ordering Application**, each of the MERCHANT will have a unique clientId and clientSecret. - **AppId**: It is a unique identification of the **Logistic Service**. It must be generated by the **Logistic Service** itself and once generated, it must be informed to all the **Software Service** / **Ordering Application** to which it will integrate. As the **AppId** is a unique key of the **Logistic Service**, it must not be created an **AppId** per **Software Service** / **Ordering Application**, but the same key must be informed for all. - **PARAMETERS IN THE LOGISTIC SERVICE (SOFTWARE SERVICE/ORDERING APPLICATION --> LOGISTIC SERVICE)** - **Tracking Event Webhook**: It is necessary to inform the URL of the webhook to receive the tracking and event updates of the delivery order. Default webhook route: `POST {baseURL}/deliveryEvent` - **MerchantId**: It is a unique ID of the MERCHANT. Similar to the **AppId** but for Merchant. It must be generated by the **Software Service** and once generated, it must be informed to all **Logistic Services** it will integrate with. Since the **MerchantId** is a unique key, a **MerchantId** must not be created per **Logistic Service**, but the same key must be informed for all. The **Ordering Application** must send the **MerchantId** received previously through its integration with the **Software Service** or if it does not have it, it can inform any id that it can use to identify the merchant. # └► Open Delivery API Evolution The **Open Delivery** API seeks to respect [SemVer](https://semver.org/). In this sense, compatible changes should not generate a new major version. The API version is composed of 4 elements: major, minor, patch and release candidate. The version v[x] in the URL path is the major element of the API version. The evolution of the version is as follows: - **Major**: incompatible, contract-breaking changes (v1.0.0 → v2.0.0) - **Minor**: compatible, non-breaking changes (v1.1.0 → v1.2.0) - **Patch**: bugfixes, clarifications to specifications, no functional changes (v1.1.1 → v1.1.2) - **Release candidate**: pre-release versions of any future patch, minor or major (v1.0.0-rc.1 → v1.0.0-rc.22) Non-breaking changes and clarifications to specifications may occur at any time. Customers should be prepared to handle these changes without breaking. The following changes are expected and considered backward compatible: - Addition of new features to the **Open Delivery** API; - Addition of new optional parameters; - Addition of new fields in **Open Delivery** API responses; - Change of fields sorting; - Addition of new elements in enumerations. # └► General Guidelines - **Date-Time, Date and Time values**: For properties that require a Date-Time, Date or Time value, use the formats specified in date-time, date and time formats (following the [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) specifications) > **ALL DATES MUST BE SENT USING UTC AS DEFAULT.** > (This way it is simpler for the receiving agent to convert to local time.) For example: **2017-05-01T06:30:00Z** for date-time (As defined by date-time - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5))\ **2017-05-01** for date (As defined by full-date - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5))\ **08:08:00Z** for time (As defined by full-time - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5)) - **IDs**: Use an id property to identify all unique entities within an entity type. An id is a unique identifier of the entity of that type, but across entities, IDs can overlap. - **Null** values: Do not use the value null in place of objects. If an object is optional, you must omit it from your feed. - **{baseURL}** : Since Open Delivery is not the host of the APIs, it is up to the companies interested in using the standard to provide the {baseURL}. Companies can provide up to two {baseURL}: - {baseURL} for authentication: where the **[Get Access Token](#operation/getToken)** route will be hosted. - {baseURL} for all other routes. > It is also possible to use the same {baseURL} for all routes. - **Sending arrays as request parameters:** To send an array parameter on a request for any endpoint, use the following format: - For `QUERY` parameters: ``` ?param=X¶m=Y¶m=Z ``` - For `HEADER` parameters: ``` param: X param: Y param: Z ``` - **Image Files:** For properties that refer to **IMAGES**, two fields are available: `URL` and `CRC-32` It is expected that the images referenced in the URL are downloaded from the server that is making the request, because the URL may no longer be valid after a period of time. The CRC-32 field must be used to check if the image has changed since the last time it was received, allowing to verify if a new download is necessary or not. # └► Error Handling The API returns HTTP status codes to indicate success or failure of requests. `2xx` codes indicate success. `4xx` codes indicate failure caused by the information sent by the client or the current state of the entities. `5xx` codes codes indicate service problems on the API side. **General** This section gathers errors that could be returned by any endpoints listed in the API. `BadRequest` * __Meaning__: Invalid request. * __HTTP Status Code__: [400 Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1). `Forbidden` * __Meaning__: Authenticated client request that violates some authorization rule. * __HTTP Status Code__: [403 Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3). `NotFound` * __Meaning__: Entity not found. * __HTTP Status Code__: [404 Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4). `InternalServerError` * __Meaning__: Unexpected condition when processing requisition. * __HTTP Status Code__: [500 Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1). `ServiceUnavailable` * __Meaning__: Service is not currently available. Requested service may be under maintenance or outside the operating window. * __HTTP Status Code__: [503 Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4). `GatewayTimeout` * __Meaning__: Indicates that the service took longer than expected to return. * __HTTP Status Code__: [504 Gateway Timeout](https://tools.ietf.org/html/rfc7231#section-6.6.5). # # ► --- API REFERENCE --- ◄ ############################################################# tags: - name: '' description: ' ' x-displayName: '' x-traitTag: true # Versions - name: configSection description: ' ' x-displayName: '└─■ CONFIGURATIONS' x-traitTag: true - name: versionsEndpoint x-displayName: '└───● Versions Listing and Configs' description: |- Because Open Delivery does not have its own servers and relies on the implementation of the endpoints by the platforms of the companies using the standard, it can happen that two platforms are using different versions of the Open Delivery API. This section includes endpoints to get the current version that each platform is using. # Authentication - name: securitySection description: ' ' x-displayName: '└─■ SECURITY' x-traitTag: true - name: authentication x-displayName: '└───● Authentication' description: |- **Open Delivery** suports two types of authentication methods: **OAuth 2** and **apiKey**. # Merchant Tags - name: merchantSection description: ' ' x-displayName: '└─■ MERCHANT' x-traitTag: true - name: merchantOverview x-displayName: '└───● Merchant Overview' description: |- The Merchant entity will be the entity used by the **Ordering Application** to fetch all the data from a merchant and display it to the user. It is the responsibility of the merchant **Software Service** to provide the endpoint and the responsibility of the **Ordering Application** to fetch the information. ## Merchant API Usage The merchant must 'choose' a **Software Service**, which will be responsible for exposing its data on the **[GET /v1/merchant](#operation/getMerchant)** endpoint. This endpoint will be used by the ordering system to get the updated merchant infos (BasicInfos, Services and Menus).
The **Ordering Application** can check for merchant updates in the following ways: 1. Make a new request on the **[GET /v1/merchant](#operation/getMerchant)** endpoint whenever the TTL expires; 2. The **Ordering Application** can optionally provide a **[webhook](#operation/menuUpdated)** , where the merchant **Software Service** can send a merchant update notification; 3. If the **Software Service** **[refuses](#operation/cancelDenied)** an order for any reason, upon receiving the refusal, it is recommended that the **Ordering Application** make a new request on the **[GET /v1/merchant](#operation/getMerchant)** endpoint. - name: merchantStructure x-displayName: └───● Merchant Structure description: |- The structure of the Merchant model consists of the following top-level properties: - **BasicInfo**: Information about the merchant. - **Services entities**: Timing, location, and conditions of the merchant service. - **Menu entities**: Details of the merchnat menus. The following diagram shows how Basic Info, Service, and Menu properties represent a single merchant:
The following schema lists the properties for the `Merchant` model: # BasicInfo A merchant `BasicInfo` defines properties such as the merchant name, location address, website, description, telephone number, for a merchant that the merchant **Software Service** serves. Typically, this data is static. The following schema lists the properties for the `BasicInfo` type: # Service The `Service` defines the capabilities of a delivery organization in a geographic region. A `Service` defines properties such as the service type (`DELIVERY` or `TAKEOUT`), hours available, and area served. Each Service must be linked to a `Menu`, through the `menuId` property. `Service` is expected to change.
The following schema lists the properties for the `Service` type: # Menu A `Menu` is a set of linked properties such as categories, items, offers and availability. In order to be displayed by the **Ordering Application**, a `Menu` needs to be linked to a `Service` through the `menuId` property.
Data in a `Menu` entity is expected to change. The following schema lists the properties for the `Menu` type: ## Category A `Category` is the propertie in which the merchant has to organize its `ItemsOffers` in order to make it easier for the user to find what he wants to buy. Categories have statuses and accepts `Availability` entities. The following schema lists the properties for the `Category` type: ## Item A `Item` propertie is the menu entity that carries all the general item information, like: name, description, external code, image, nutricional information, and EAN (European Article Number). The `Item` can be offered in a `Menu` as a main item or an option. And, for the same store, it can even be reused in different `Menus`. The following schema lists the properties for the `Item` type: ## ItemOffer The `ItemOffer` can be considered the offering of a item, and it is used to set the item price and `Availability`. The `ItemOffer` is a `Item` related to the `Category`. The following schema lists the properties for the `ItemOffer` type: ## OptionGroup and Option The `OptionGroup` is the entity used to group customizations of a product, for example: "Choose your beverage:" An `OptionGroup` can be shared by several items. The `OptionGroup` has its own statuses, and can be activated or desactivated when needed. `Options` are the complements of a OptionGroup. It can be defined as: "A `Item` related to a `OptionGroup`". It is possible to set the `Option` price to 0.00 regardless of whether it is mandatory or optional. The following schema lists the properties for the `OptionGroup` type: ## Availability The `Availability` entity defines specific times and days to control the availability of `Categories` and `Item offerings` within the `Menu`. It is also possible to set special times for holidays. The following schema lists the properties for the `Availability` type: - name: merchantEndpoints x-displayName: '└───● Merchant Endpoint' description: |- This section details the `GET /v1/merchant` endpoint. This endpoint should be implemented by the `Software Service` and its URL should be informed to the `Ordering Application`. The endpoint is designed so that **each merchant has its own URL**. The specification recommends that the endpoint ends with the `/merchant` route, but this is **not mandatory**. The `Software Service` can implement the URL in any way it sees fit, as long as it contains information from **only one** merchant. - name: merchantStatus x-displayName: '└───● Onboarding and Status' description: |- This section contains routes for registering and updating the Merchant endpoint information, as well as the read status of this endpoint. - name: merchantUpdate x-displayName: '└───● Merchant Update' description: |- ### Merchant Update Notification **[Webhook](#operation/menuUpdated)** is sent to notify the **Ordering Application** that an new update has happened on the merchant information. The **Ordering Application** that implements this webhook, should return an HTTP 200 response code with an empty response body to acknowledge receipt of the webhook event. If the merchant **Software Service** does not receive a 200 acknowledgement response, than the webhook event will be resent based on the **Software Service** policies. # Orders Tags - name: ordersSection description: ' ' x-displayName: '└─■ ORDERS' x-traitTag: true - name: ordersOverview x-displayName: └───● Order Overview description: |- This overview summarizes the **Open Delivery** Ordering flow and how it interacts with merchant **Software Service** and **Ordering Application**. ### Order Events





### Understanding the Order Flow
The order flow has the following Macro steps: ### Order Event Reception Through Order Events, the '**Ordering Application**' communicates to the '**Software Service**' the existence of a new order, as well as the other events of the order lifecycle. **Open Delivery** provides two ways for merchant **Software Service** to be aware of new events: - **[Polling](#tag/ordersPolling)**: Receiving events through polling provided by the '**Ordering Application**' is the common way **Open Delivery Order Events** works. - **[Webhook](#tag/ordersWebhook)**: Optionally it is recommended the implementation of a **webhook** by the merchant **Software Service** for the **Ordering Applications** to send new events directly, ensuring a much faster communication. > It is recommended that the merchant **Software Service** contacts the **Ordering Application** to know which of these methods are avaliable. ### Order Details Once the new order event is received, it is necessary to get the **[order details](#tag/ordersDetails)**, such as items purchased, delivery addresses, and payment methods. ### Events Updates After getting the order details, the merchant needs to notify the '**Ordering Application**' of the order progress. Through the **Open Delivery** API it is possible to: - **[Confirm](#operation/confirmOrder)** receipt of order; - Notify that an order is **[ready for pickup](#operation/orderReady)**; - Notify that an order has been **[dispatched](#operation/dispatchOrder)**. - Optionally you can notify that the order has been **[delivered](#operation/orderDelivered)**. Whenever a merchant triggers one of these actions, the '**Ordering Application**' will send a new event to the mechart **Software Service**, acknowledging the new order status within the '**Ordering Application**'. > For `TAKEOUT` orders, it is possible to optionally assign a **pickup area** that will be informed through an event to the merchant. > This must be provided by the **Ordering Application** interface. ### Order Cancellation **Open Delivery** provides API's to send **[cancellation](#tag/ordersCancellation)** requests from either system. These requests can be accepted or denied depending on the rules that the company has. x-traitTag: true - name: ordersPolling x-displayName: └───● Polling description: |- Receiving events via Polling works as follows:
### Query new order events In order to receive new order events, the merchant **Software Service** must make requests on the polling endpoint regularly at a certain time interval, determined by the '**Ordering Application**'. Whenever there is a new event the response will send the response code 200 with the list of events. If there are no new events, the response will send the response code 204. > It is important that the **Software Service** performs the requests within the timeframe determined by the **Ordering Application**, as blocking and penalties may occur depending on the application's rules. **Availability of new events in polling:** The **Ordering Application** may have specific rules about the maximum time new events are available in polling before they are removed. > Always check with the **Ordering Application** what the rules are for using the polling service. **Duplicate Events** Eventually the **Ordering Application** may return the same event more than once, for example the `CREATED` event, including old orders. For this reason it is important that the **Software Application** handles the uniqueness of requests and events through id and the date. Therefore, when receiving an event, the **Software Service** must check the event id and validate that this event (id) has not been processed before. If this event has already been received previously, it must be discarded. > **Please note**: merchant **Software Services** should only accept a new order or update the status of an order after validating that the event has not been processed before. It is also possible for the **Software Service** to make a request for the same event more than once (for example, requesting the `POST /v1/orders/{orderId}/confirm` endpoint repeatedly). In these cases the **Ordering Application** can handle this situation in two different ways: - If the processing of the requests is done synchronously, then the **Ordering Application** should return **`HTTP 422`**, indicating that that event has been received before. - If the processing is done asynchronously, then it is recommended that the **Ordering Application** polls the corresponding event again, because for some reason the **Software Service** could not read that event before. ### Acknowledgment Events When receiving new events via **Polling**, the **Software Service** should always send acknowledgement so that the **Ordering Application** does not send that same event again; >**Important recommendations**: > > - Merchants **Software Service** should make an acknowledgment request for each polling request with results. > - If it receives events that are not used by the itself, it needs to send the acknowledgment of these events anyway so that it is not receiving them every polling again. > - **Open Delivery** recommends that this be the default treatment for all events not yet mapped in the **Software Service** application. > - **Software Services** only needs to send acknowledgment of the event once. **Acknowledgment NOT apply for WEBHOOKS.** - name: ordersWebhook x-displayName: └───● Webhook description: |- Receiving events via Webhook works as follows:
### Order Event Notification Webhook is sent to notify the merchant **Software Service** that an new order event has happened on the **Ordering Application**. The merchant **Software Service** that implements this webhook, should return an HTTP `200` response code with an empty response body to acknowledge receipt of the webhook event. If the **Ordering Application** does not receive a `200` acknowledgement response, than the webhook event will be resent based on the **Ordering Application** policies. ### Webhook Headers **Open Delivery** will include security headers for all requests made to the merchant **Software Service** webhook URL. **Header Description** | Header | Description | | ----------------- | ----------- | | X-App-Id | An Unique Identificator of the **Ordering Application** | | X-App-MerchantId | An Unique Identificator of the **Merchant** receiving the order | | X-App-Signature | SHA256 hash of the request body, using the client secret as the key | **Webhook Security** Webhook messages are signed so that the merchant **Software Service** can verify that the sender is a valid **Ordering Application**. Webhooks requests contain an X-App-Signature header. The value of this field is a lowercased hexadecimal HMAC signature of the webhook HTTP request body, using the client secret as a key and SHA256 as the hash function. - name: ordersDetails x-displayName: └───● Order Details description: |- Before confirming or canceling an order, it is necessary to get the order details so that the merchant **Software Service** user can check if he will be able to prepare and deliver this order, such as checking if he has all the necessary items and if he is available to make the delivery to the informed address. Through the GET /orders/{id} endpoint the merchant **Software Service** can get all the details of an order. This endpoint returns the code 200 and the content of the request. If an invalid request id or the id of an expired order is entered (depending on the **Ordering Application** policy) the endpoint returns 404. - name: ordersStatus x-displayName: └───● Order Event Updates description: |- Following the order lifecycle, the merchant **Software Service** needs to notify the **Ordering Application** of the upcoming order status. After acknowledging receipt of a new order event (either via polling or webhook) is expected that the **Software Service** explicitly **POST [/orders/{orderId}/confirm](#operation/confirmOrder)** or **POST [/orders/{orderId}/requestCancellation](#operation/requestCancellation)** within a time window set by the **Ordering Application**. Otherwise the order can time out and auto-cancel and the merchant can suffer a penalty based on the **Ordering Application** policy. Order acceptances should be posted as quickly as possible to minimize consumer cancellations. When the order is ready, it is expected that a request will be sent to **[/orders/{orderId}/readyForPickup](#operation/orderReady)** When the order goes out for Delivery, it is expected that a request will be sent to **[/orders/{orderId}/dispatch](#operation/dispatchOrder)**. > When sending requests to these endpoints, is expected that the **Ordering Application** notifies the consumer of the progress of the order. - name: ordersCancellation x-displayName: └───● Order Cancellation description: |- An order can be canceled for several reasons and the initiative to cancel an order can come from the merchant, the customer, or the **Ordering Application**. It may also happen that the delivery person requests the cancellation in some scenarios, such as when the customer is not found at the delivery address. > **Cancellation Rules** > > It is expected that both the **Ordering Application** and merchant **Software Service** have their own order cancellation policies and inform their users. A cancellation request will always be an asynchronous processing, where one party makes a cancellation request and the other accepts or refuses it." A cancellation request must always contain: - **reason**: Open text field indicating the reason for the cancellation. - **code**: An enumerator containing a cancellation reason. - **mode**: Field indicating whether the cancellation occurred Automatically or Manually. The cancellation can be requested by: ### **Software Service** (Merchant):
If the merchant wants to cancel an order, it must make a **POST [/orders/{orderId}/requestCancellation](#operation/requestCancellation)** request. > **Penalties** > > Avoid order cancellations! Excessive cancellations can result in some penalties (depending on the **Ordering Application**'s** policy) such as having the merchant temporarily closed on the platform. **Cancellation Validation** The Cancellation request does not guarantee that the order is cancelled. When sending a request [/orders/{orderId}/requestCancellation](#operation/requestCancellation), the **Ordering Application** will send the code 202 (accepted) in response. This does not yet mean that the request has been cancelled. It means that the request has been accepted and will be processed by the **Ordering Application** cancellation service. As a result of this request, the merchant **Software Service** may receive at the next polling (or via webhook) one of the following events: - CANCELLATION_REQUEST_DENIED - CANCELLED The order should only be Canceled when the CANCELLED event is generated. > Cancellation rules may vary depending on the timing of the order (before or after confirmation). In some situations it is possible that the **Ordering Application** cancellation service will consult with the consumer on whether or not the consumer accepts the cancellation of the order. ``` Cancellation codes: - SYSTEMIC_ISSUES - DUPLICATE_APPLICATION - UNAVAILABLE_ITEM - RESTAURANT_WITHOUT_DELIVERY_PERSON - OUTDATED_MENU - ORDER_OUTSIDE_THE_DELIVERY_AREA - BLOCKED_CUSTOMER - OUTSIDE_DELIVERY_HOURS - INTERNAL_DIFFICULTIES_OF_THE_RESTAURANT - RISK_AREA - DELIVERY_PROBLEM ``` > **Important**: It is recommended that the **Ordering Application** makes a new request on the [GET /v1/merchant](#operation/getMerchant) endpoint whenever a merchant makes a Cancellation request. ### **Ordering Application** Cancellation by **Ordering Application** can happen by: ``` code: CONSUMER_CANCELLATION_REQUESTED ``` The consumer can request the cancellation of an order. Depending on the cancellation rules applied, this option may not be enabled for all merchants. It may also only be allowed at certain times, such as before the order is confirmed. ``` code: OTHER_CANCELLATION_REASON ``` Ordering Aplications may cancel the order for reasons other than via customer. **Mandatory Cancellation** In most situations, the **Ordering Application** may send the order cancellation without giving the **Software Service** the opportunity to accept or deny this cancellation. This is a valid scenario within the standard. In these cases, a `CANCELLED` event will be sent directly to POLLING or WEBHOOK and the **Software Service** must cancel the order. **Cancellation Handshake** In situations where a cancellation handshake is possible, the flow will proceed as follows:
When the request occurs the merchant **Software Service** will receive an ORDER_CANCELLATION_REQUEST event in polling (or via webhook) and must manifest itself through the following endpoints: **[/orders/{orderId}/acceptCancellation](#operation/cancellationAccepted)** **[/orders/{orderId}/denyCancellation](#operation/cancellationDenied)** This request will be processed by the **Ordering Application**'s** cancellation service (asynchronously) and the merchant **Software Service** will receive in the next polling (or webhook) the following event(s): CANCELLATION_DENIED or CANCELLED - name: ordersTracking x-displayName: └───● Order Delivery Info description: |- This section deals with event updates related to the delivery of the order. The order delivery can be the responsibility of either the `Ordering Application` or the `Software Service`. The endpoints in this section are intended for the system responsible for delivery to send updated information to the other party. > **The events handled in these endpoints work in a complementary and parallel way to the order events described in the [Order Updates](#tag/ordersStatus) section.** # Logistics Tags - name: logisticsSection x-displayName: └─■ LOGISTICS x-traitTag: true description: |- This section covers the API referring to the operations with `**Logistic Services**`. - name: logisticOverview x-displayName: └───● Logistic Overview description: |- Open Delivery provides a set of standards so that both merchants through their **Software Services** and **Ordering Applications** can request a new delivery to a logistics operator and track this delivery. ## Logistics API Usage Open Delivery's Logistic API aims to standardize the communication between a **requester** - which can be either a **Software Service** or an **Ordering Application** - and a company's software that provides **Logistic Services** (called here **Logistic Service**). > A **Logistic Service** can be either a company that specializes in delivery services or an **Ordering Application** that also provides delivery services. > The Open Delivery logistics API only handles communications between the merchant software (or **Ordering Application**) and the software of the logistics operator. Communications and interfaces with the deliverers at the end are not covered in this documentation, leaving it up to the logistics companies to perform this interaction.
The endpoints provided here, cover the following functionalities: ### Delivery Order It covers the calling of a new delivery, as well as auxiliary endpoints for reporting the pickup of an order, the completion of the delivery, as well as problem handling and cancellations. ### Delivery Tracking Webhook to be available at the **requester's** side of the call, in order to receive all order event updates, as well as delivery information updates. ### Delivery Availability and Price Endpoint with the function of simulating a new delivery, with the purpose of checking if it is possible to make the delivery as well as its prices and times. " - name: logisticOrder x-displayName: └───● Delivery Order description: |- ### Events This overview summarizes the **Open Delivery** delivery ordering flow and how it interacts with the requester (merchant **Software Services** or **Ordering Applications**) and the **Logistic Services**.
> The `PICKUP_ONGOING`, `DELIVERY_ONGOING` and `RETURNING_TO_MERCHANT` events are events that occur while the delivery person is on the move, so these events can be sent repeatedly in order to update the delivery person's location. The interval at which these events are sent is defined by each **Logistic Service**. > It is important to emphasize that the entire event flow is per Order and even though a delivery may have combined orders (see section below), for all operations in the flow, the id to be used is the `orderId` (initially informed by the requester at the /logistics/delivery endpoint). ### Combining Orders The Open Delivery logistics API offers the option of combining more than one order into a single delivery. This can be done on both the **Software Service** (or **Ordering Application**) and the **Logistic Service** sides. To combine orders its necessary that at least one delivery is currently in progress. When requesting for a new delivery, you need to inform the `orderId` of the ongoing deliveries in the `combinedOrdersIds` field of the new request.
> This combination will be subject to acceptance by the **Logistic Service**. The **Logistic Service** may also perform order combination in its software, using its algorithms and processes (provided that the `canCombine` field is entered as `TRUE` in the delivery request). > For this combination no action is required from the **requester**. Regardless of the case, the **Logistic Service** must inform in the event webhook the combined orders of the same merchant, through the `combinedOrdersIds` field. > Since all event flow is per Order, then in the case of deliveries that have combined orders, an event message must be sent to each of the orders separately. ### Order Rejection and retries for the same order If a new delivery order is rejected by the **Logistic Service**, regardless of the reason, the **Software Service** / **Ordering Application** can make a new attempt for the same order (same `orderId` and same `orderDisplayId`). The **Logistic Service** must receive this retry only if the last sent event for this order was the `REJECTED` event. If any other event has already been sent, then the **Logistic Service** will return a duplicate orderId error. > The number of retries possible for the same order is defined by each **Logistic Service**. - name: logisticsWebhook x-displayName: └───● Webhooks description: |- Receiving delivery events via Webhook works as follows:
### Webhook Headers **Open Delivery** will include security headers for all requests made to the merchant **Software Service** webhook URL. **Header Description** | Header | Description | | ----------------- | ----------- | | X-App-Id | An Unique Identificator of the **Logistic Service** | | X-App-MerchantId | An Unique Identificator of the **Merchant** receiving the order event | | X-App-Signature | SHA256 hash of the request body, using the client secret as the key | **Webhook Security** Webhook messages are signed so that the merchant **Software Service** (or the **Ordering Application**) can verify that the sender is a valid **Logistic Service**. Webhooks requests contain an X-App-Signature header. The value of this field is a lowercased hexadecimal HMAC signature of the webhook HTTP request body, using the client secret as a key and SHA256 as the hash function. - name: logisticPrice x-displayName: └───● Delivery Availability and Pricing description: |- Endpoint used to check the availability of a **`Logistic Service`** to make a delivery with addresses and times already defined, as well as to obtain the price for this delivery. This endpoint only simulates the acceptance of a new delivery request, using the information available at the time of the call. > The call to this endpoint does not generate any commitment to **Logistic Service** and should only be used as an estimate of the delivery values. To make a real delivery request, call this endpoint. - name: logisticDetails x-displayName: └───● Delivery Details and History description: |- Endpoint used to get detailed and history information for a specific delivery order. > This endpoint should not be used as a way to get delivery tracking. This is already covered in the events webhook. The purpose of this route is to receive sporadic calls to get missing information or the complete history of events and problems. Misuse of this endpoint can result in blockages by **Logistic Service**. x-tagGroups: - name: '' tags: - securitySection - authentication - name: '_______________________________________' tags: - ordersSection - name: '└──◌ Overview' tags: - ordersOverview - name: └──◌ Events tags: - ordersPolling - ordersWebhook - name: └──◌ Details tags: - ordersDetails - name: └──◌ Actions tags: - ordersStatus - ordersCancellation - ordersTracking - name: '_______________________________________' tags: - merchantSection - name: '└──◌ Overview and Structure' tags: - merchantOverview - merchantStructure - name: '└──◌ api' tags: - merchantEndpoints - name: '└──◌ Updates and Status' tags: - merchantUpdate - merchantStatus - name: "_______________________________________" tags: - logisticsSection - name: └──◌ Logistics API tags: - logisticOverview - logisticOrder - logisticsWebhook - logisticDetails - logisticPrice - name: '_______________________________________' tags: - configSection - versionsEndpoint - name: '_______________________________________' tags: - footer ############################################################# servers: - url: https://api.server.test paths: # Versions /v1/versions/orderingApp: get: operationId: 'getOrderingAppVersions' security: [] tags: - 'versionsEndpoint' summary: 'Get Current Ordering Application API Version' description: |- Requests the current version of the endpoints hosted on the **ORDERING APPLICATION** side.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '200': description: 'Successful returns Ordering Application API version.' content: 'application/json': schema: $ref: '#/components/schemas/VersionOrderingApp' '400': $ref: '#/components/responses/BadRequest' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/versions/merchant: get: operationId: 'getMerchantVersions' security: [] tags: - 'versionsEndpoint' summary: 'Get Current Merchant API Version' description: |- Requests the version of the endpoints hosted on the **SOFTWARE SERVICE** side, related to the MERCHANTS.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '200': description: 'Successful returns Merchant API version.' content: 'application/json': schema: $ref: '#/components/schemas/VersionMerchant' '400': $ref: '#/components/responses/BadRequest' '503': $ref: '#/components/responses/ServiceUnavailable' # Authentication /oauth/token: post: operationId: 'getToken' security: [] tags: - 'authentication' summary: 'Get Access Token' description: |- Requests new access token for accessing **Ordering Application** API resources.

HOST: **ORDERING APPLICATION** DIRECTION:
requestBody: $ref: '#/components/requestBodies/Token' responses: '200': description: 'Successful returns token request.' content: 'application/json': schema: $ref: '#/components/schemas/TokenResponse' '401': $ref: '#/components/responses/Unauthorized' '503': $ref: '#/components/responses/ServiceUnavailable' # Merchant /v1/merchant: get: tags: - 'merchantEndpoints' operationId: 'getMerchant' summary: 'Get information of a Merchant' security: - {} - apiKey: [] description: |- Endpoint to get all data of a specific merchant, such as basic info, menus, and services. > This endpoint can optionally require an **apiKey** for authentication. > Check with the **Software Service** that hosts the endpoint whether authentication is required or not. > If the Ordering Application has the [PUT /merchantOnboarding](#operation/putMerchantOnboarding) endpoint implemented, the Software Service can pass the endpoint data through this operation.

HOST: **SOFTWARE SERVICE** DIRECTION:
responses: '200': description: 'Successful returns Merchant information.' content: 'application/json': schema: $ref: '#/components/schemas/Merchant' examples: menuExample: $ref: '#/components/examples/merchantExample' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/merchantStatus: get: parameters: - in: 'query' name: 'merchantId' required: true schema: type: 'string' description: |- Unique Identifier. Identifies the merchant in the different systems that the merchant will communicate. This id must be generated by the merchant's **`Software Service`**. > To avoid duplicates between different merchants it is recommended that the software creates the merchantId using: > `Merchant Document + UUID` > If this is not possible, it is recommended to at least use a UUID. minLength: 36 maxLength: 100 example: '22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824' tags: - 'merchantUpdate' operationId: 'getMerchantStatus' summary: 'Check Merchant Update Processing Result' security: - OAuth2: [od.all] description: |- Returns the result of the merchant update processing, whether triggered by a direct GET /merchant request or by receiving a merchant update via webhook. Use this endpoint to verify the status and outcome of the last merchant update attempt, including success, failure, or processing state.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '200': description: 'Returns the status and result of the last merchant update processing (GET /merchant or webhook).' content: 'application/json': schema: $ref: '#/components/schemas/MerchantStatus' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/merchantOnboarding: put: tags: - 'merchantStatus' operationId: 'putMerchantOnboarding' summary: 'Register / Update Merchant endpoint info.' security: - OAuth2: [od.all] description: |- Register and update the **Merchant** endpoint [GET /v1/merchant](#operation/getMerchant) information in the **Ordering Application**.

HOST: **ORDERING APPLICATION** DIRECTION:
parameters: - in: 'query' name: 'merchantId' required: true schema: type: string description: 'The Id of the Merchant for whom you want to complete or change registration info.' requestBody: required: true content: 'application/json': schema: $ref: '#/components/schemas/MerchantAPIInfo' responses: '201': description: 'Resource has been created.' content: 'application/json': schema: $ref: '#/components/schemas/MerchantAPIInfo' '204': description: 'Request has been processed. Return has no content.' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/merchant/{id}/status: get: tags: - 'merchantStatus' operationId: 'getMerchantAvailability' security: - OAuth2: [od.all] summary: 'Get Merchant Status and Service Hours' description: |- Returns the merchant status, service hours (serviceHours), and sourceAppId.

HOST: **SOFTWARE SERVICE** DIRECTION:
parameters: - in: path name: id required: true schema: type: string description: 'Merchant Id.' responses: '200': description: 'Successfully returns Merchant status, services and sourceAppId.' content: application/json: schema: type: object properties: status: type: string description: 'Merchant status.' enum: [AVAILABLE, UNAVAILABLE] services: type: array description: 'Array de serviços do merchant.' items: type: object properties: id: type: string description: 'Service id.' serviceType: type: string description: 'Tipo do serviço.' serviceHours: type: array description: 'Array de horários de serviço.' items: type: 'object' title: 'Service Hours' properties: weekHours: type: array description: 'A list of the day(s) of the week and time periods for which the service is valid.' items: type: 'object' allOf: - $ref: '#/components/schemas/Hours' holidayHours: type: array description: 'Map of holiday dates, each with optional `timePeriods`. If a date does not have a time period specified, the restaurant will be closed for that date.' items: type: 'object' allOf: - $ref: '#/components/schemas/HolidayHours' orderingAppMerchantId: type: string description: 'Internal merchantId of the merchant in the **Ordering Application**' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '503': $ref: '#/components/responses/ServiceUnavailable' # Orders '/v1/events:polling': get: operationId: pollingEvents parameters: - name: 'x-polling-merchants' in: 'header' required: false schema: type: array description: |- Subset of merchants to fetch events from. Must either be omitted or non-empty. > At this time, this field will only return data from the authenticated merchant, since authentication occurs per merchant and not per application. This field may be used in future versions. items: type: 'string' description: |- Unique Identifier. Identifies the merchant in the different systems that the merchant will communicate. This id must be generated by the merchant's **`Software Service`**. > To avoid duplicates between different merchants it is recommended that the software creates the merchantId using: > `Merchant Document + UUID` > If this is not possible, it is recommended to at least use a UUID. minLength: 36 maxLength: 100 example: '22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824' maxItems: 100 - name: 'eventType' in: 'query' schema: type: array description: |- Desired event types. All other events not selected by group will be automatically acknowledged and omitted from the response. Must either be omitted or non-empty. **Event Types definitions:** > `CREATED` : Order created.\ > `CONFIRMED` : Order confirmed.\ > `PREPARATION_REQUESTED` : Informs the **Software Service** that they can start prepare the order.\ > `PREPARING` : Preparation of the order has started\ > `READY_FOR_PICKUP`: Order ready for pickup by the customer or delivery person.\ > `DISPATCHED` : Order went out for delivery.\ > `PICKUP_AREA_ASSIGNED` : Informs the **Software Service** the designated area to pick up the order.\ > `PICKED_UP` : Order has been picked up by customer.\ > `DELIVERED` : Order has been delivered to customer.\ > `CONCLUDED` : Order completed.\ > `CANCELLATION_REQUESTED` : Sent by the **Software Service** to the **Ordering Application**.\ > `CANCELLATION_REQUEST_DENIED` : It must be sent from the **Ordering Application** to the **Software Service**.\ > `CANCELLED` : When the order is actually cancelled.\ > `ORDER_CANCELLATION_REQUEST`: It must be sent from the **Ordering Application** to the **Software Service**. > `CANCELLED_DENIED`: When the cancellation request from the **Ordering Application** is denied by the **Software Service**. items: type: 'string' description: 'The event type. **[Click here](#operation/pollingEvents)** for definitions of each type.' enum: - 'CREATED' - 'CONFIRMED' - 'PREPARING' - 'DISPATCHED' - 'READY_FOR_PICKUP' - 'PICKUP_AREA_ASSIGNED' - 'PICKED_UP' - 'DELIVERED' - 'CONCLUDED' - 'CANCELLATION_REQUESTED' - 'CANCELLATION_REQUEST_DENIED' - 'CANCELLED' - 'ORDER_CANCELLATION_REQUEST' - 'CANCELLED_DENIED' maxItems: 15 tags: - 'ordersPolling' summary: 'Get New Events' security: - OAuth2: [od.all] description: |- Polls events for any orders from merchants associated with the authenticated user. Each event received from this endpoint must be properly acknowledged, otherwise it will continue to be returned on further requests.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '200': description: 'Successful returns list of polled events .' content: 'application/json': schema: type: array items: $ref: '#/components/schemas/Event' maxItems: 1000 '204': description: 'No content.' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/events/acknowledgment: post: requestBody: $ref: '#/components/requestBodies/AckEvents' tags: - 'ordersPolling' operationId: pollingAcknowledgment summary: 'Acknowledge Events' security: - OAuth2: [od.all] description: |- Acknowledge a set of events, dismissing them from future polling calls.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/orders/{orderId}: get: parameters: - name: 'orderId' required: true in: 'path' schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' tags: - 'ordersDetails' operationId: ordersDetails summary: 'Get Order Details' security: - OAuth2: [od.all] description: |- Endpoint to consult the details of an order.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '200': description: 'Order returning success.' content: 'application/json': schema: $ref: '#/components/schemas/Order' # examples: # orderExample: # $ref: "#/components/examples/orderExample" '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/orders/{orderId}/confirm: post: parameters: - name: orderId in: 'path' required: true schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' requestBody: content: 'application/json': schema: $ref: '#/components/schemas/OrderConfirmed' tags: - 'ordersStatus' operationId: confirmOrder summary: 'Confirm' security: - OAuth2: [od.all] description: |- Informs the **Ordering Application** that the order has been accpeted and preparation will start soon. > It is expected to receive a `CONFIRMED` event after this action.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/orders/{orderId}/preparing: post: parameters: - name: orderId in: 'path' required: true schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' tags: - 'ordersStatus' operationId: 'orderPreparing' summary: 'Preparing (Optional)' security: - OAuth2: [od.all] description: |- Informs the **Ordering Application** that the preparation of the order has already begun. > It is expected to receive a `PREPARING` event after this action. Important: This endpoint is not mandatory and should be sent only if the **Ordering Application** is able to receive this request and when the Order `service.serviceType` = `TAKEOUT`. > To check whether or not it is required to call this endpoint, check the `sendPreparing` field in the endpoint: [GET /orders/{orderId}](#operation/ordersDetails)

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/orders/{orderId}/readyForPickup: post: parameters: - name: orderId in: 'path' required: true schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' tags: - 'ordersStatus' summary: 'Ready For Pickup' operationId: 'orderReady' security: - OAuth2: [od.all] description: |- Informs the **Ordering Application** that the order is ready for pickup. > It is expected to receive a `READY_FOR_PICKUP` event after this action.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/orders/{orderId}/pickedUp: post: parameters: - name: orderId in: 'path' required: true schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' tags: - 'ordersStatus' operationId: 'orderPickedUp' summary: 'Picked Up (Optional)' security: - OAuth2: [od.all] description: |- Informs the **Ordering Application** that the order has been picked up. > It is expected to receive a `PICKED_UP` event after this action. Important: This endpoint is not mandatory and should be sent only if the **Ordering Application** is able to receive this request and when the Order `service.serviceType` = `TAKEOUT`. > To check whether or not it is required to call this endpoint, check the `sendPickedUp` field in the endpoint: [GET /orders/{orderId}](#operation/ordersDetails)

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/orders/{orderId}/dispatch: post: parameters: - name: orderId in: 'path' required: true schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' requestBody: content: 'application/json': schema: $ref: '#/components/schemas/OrderDispatched' tags: - 'ordersStatus' operationId: 'dispatchOrder' summary: 'Dispatch' security: - OAuth2: [od.all] description: |- Informs the **Ordering Application** that the order has been dispatched. > It is expected to receive a `DISPATCHED` event after this action.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/orders/{orderId}/delivered: post: parameters: - name: orderId in: 'path' required: true schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' tags: - 'ordersStatus' operationId: 'orderDelivered' summary: 'Delivered (Optional)' security: - OAuth2: [od.all] description: |- Informs the **Ordering Application** that the order has been delivered. > It is expected to receive a `DELIVERED` event after this action. Important: This endpoint is not mandatory and should be sent only if the **Ordering Application** is able to receive this request and only in cases where the order logistics service is provided by the Merchant and not the Marketplace. > To check whether or not it is required to call this endpoint, check the `sendDelivered` field in the endpoint: [GET /orders/{orderId}](#operation/ordersDetails)

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/orders/{orderId}/validateCode: post: parameters: - name: orderId in: 'path' required: true schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' - name: deliveryCode in: 'query' required: true schema: type: string description: 'The Delivery Coonfirmation Code to be validated.' tags: - 'ordersTracking' operationId: 'orderValidateDelivery' summary: 'Validate Delivery Code' security: - OAuth2: [od.all] description: |- This endpoint aims to validate a delivery code provided by the consumer, so that the delivery person knows whether the order is being delivered to the correct person or not. Unlike the other endpoints, this path should be handled **SYNCHRONOUSLY** and will not generate new events in Polling or Webhook. The endpoint should return: - HTTP `200` response code if the Delivery Code is **valid**. - HTTP `400` responde code if the Delivery Code is **invalid**. In this case you must inform the cause in the `title` propertie.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: "200": description: Confirmation Code is correct. You can proceed with the delivery. content: "application/json": schema: $ref: "#/components/schemas/DeliveryConfirmationCode" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/orders/{orderId}/tracking: post: parameters: - name: orderId in: 'path' required: true schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' requestBody: content: 'application/json': schema: $ref: '#/components/schemas/OrderTracking' tags: - 'ordersTracking' operationId: 'orderTracking' summary: 'Send Delivery Updates' security: - OAuth2: [od.all] description: |- Sends information about the delivery in progress. This endpoint should be used when the delivery is the responsibility of the `Merchant`, so the `Software Service` should send the delivery updates to the `Ordering Application`. > To check whether or not it is required to call this endpoint, check the `sendTracking` field in the endpoint: [GET /orders/{orderId}](#operation/ordersDetails)

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/orders/{orderId}/details: patch: parameters: - name: orderId in: path required: true schema: type: string format: uuid description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' tags: - 'ordersDetails' operationId: 'patchOrderDetails' summary: 'Update Order Details' security: - OAuth2: [od.all] description: |- This is an **OPTIONAL** endpoint that may be used to update order properties that do not affect the order status.

HOST: **ORDERING APPLICATION** DIRECTION:
requestBody: required: true content: application/json: schema: type: object properties: preparationStartDateTime: type: string format: date-time description: 'The new preparation time for the order.' responses: "200": description: Preparation time updated successfully. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/orders/{orderId}/requestCancellation: post: parameters: - name: orderId in: 'path' required: true schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' requestBody: $ref: '#/components/requestBodies/CancelRequest' tags: - 'ordersCancellation' operationId: 'requestCancellation' summary: 'Request order cancellation' security: - OAuth2: [od.all] description: |- Request order cancellation to the **Ordering Application**. > It is expected to receive a `CANCELLATION_REQUESTED` event after this action.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntityOrderCancellation' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/orders/{orderId}/acceptCancellation: post: parameters: - name: orderId in: 'path' required: true schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' tags: - 'ordersCancellation' operationId: 'cancellationAccepted' summary: 'Accept order cancellation' security: - OAuth2: [od.all] description: |- Informs the **Ordering Application** that the cancellation request has been accepted and the order can be Cancelled. > It is expected to receive a `CANCELLED` event after this action.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '200': description: Status 200 available for compatibility reasons. Please use status 204 instead. '204': description: Order cancellation has been confirmed. No response content. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '503': $ref: '#/components/responses/ServiceUnavailable' /v1/orders/{orderId}/denyCancellation: post: parameters: - name: orderId in: 'path' required: true schema: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' requestBody: $ref: '#/components/requestBodies/CancelDenied' tags: - 'ordersCancellation' operationId: 'cancellationDenied' summary: 'Deny order cancellation' security: - OAuth2: [od.all] description: |- Informs the **Ordering Application** that the cancellation request has been denied and the order cannot be Cancelled. > It is expected to receive a `CANCELLATION_DENIED` event after this action.

HOST: **ORDERING APPLICATION** DIRECTION:
responses: '200': description: Status 200 available for compatibility reasons. Please use status 204 instead. '204': description: Order cancellation has been denied. No response content. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '503': $ref: '#/components/responses/ServiceUnavailable' # Logistics /v1/logistics/availability: post: operationId: logisticsAvailability security: - {} requestBody: content: "application/json": schema: $ref: "#/components/schemas/DeliveryAvailabilityPrice" tags: - "logisticPrice" summary: "Check delivery availability and prices" description: |- Simulates a new delivery solicitation to know prices and delivery times. responses: "200": description: "Successfully returns delivery availability and price." content: "application/json": schema: $ref: "#/components/schemas/DeliveryAvailabilityPriceResponse" "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/logistics/delivery: post: operationId: "logisticsNewDelivery" security: - OAuth2: [od.all] requestBody: $ref: "#/components/requestBodies/DeliveryOrder" tags: - "logisticOrder" summary: "Request new delivery" description: "Starts the process of calling a new delivery for an order." responses: "202": description: "Request has been accepted for processing." content: "application/json": schema: $ref: "#/components/schemas/DeliveryOrderResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: '#/components/responses/Unauthorized' "403": $ref: "#/components/responses/AccessDenied" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/UnprocessableEntity" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/logistics/delivery/{orderId}: get: operationId: logisticDetails security: - OAuth2: [od.all] parameters: - name: orderId in: "path" required: true schema: type: string format: "uuid" description: "The orderId generated by the **`Ordering Application`**." example: "52122852-6626-11ed-9022-0242ac120002" tags: - "logisticDetails" summary: "Get delivery details" description: |- Gets detailed information about the delivery order. > Since the same `orderId` may have more than one return (considering that it may have been rejected a few times before being accepted), then the response should return only the last attempt processed by the **Logistics Service**, be it an acceptance or a rejection. responses: "200": description: "Successfully returns the delivery order details." content: "application/json": schema: $ref: "#/components/schemas/DeliveryOrderDetails" "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/logistics/readyForPickup/{orderId}: post: operationId: "logisticsReadyForPickup" security: - OAuth2: [od.all] parameters: - name: orderId in: "path" required: true schema: type: string format: "uuid" description: "The orderId generated by the **`Ordering Application`**." example: "52122852-6626-11ed-9022-0242ac120002" tags: - "logisticOrder" summary: "Inform Ready for Pickup" description: |- Inform the **Logistic Service** that the order is ready for pickup. > **This is a OPTIONAL endpoint and should only be requested if the `notifyReadyForPickup` field has been set to `true` when sending the delivery request via the [POST /logistics/delivery](#operation/logisticsNewDelivery) endpoint.** responses: "200": description: "Order is ready for pickup." "400": $ref: "#/components/responses/BadRequest" "401": $ref: '#/components/responses/Unauthorized' "403": $ref: "#/components/responses/AccessDenied" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/UnprocessableEntity" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/logistics/orderPicked/{orderId}: post: operationId: "logisticsPicked" security: - OAuth2: [od.all] parameters: - name: orderId in: "path" required: true schema: type: string format: "uuid" description: "The orderId generated by the **`Ordering Application`**." example: "52122852-6626-11ed-9022-0242ac120002" requestBody: content: "application/json": schema: $ref: "#/components/schemas/DeliveryOrderPicked" tags: - "logisticOrder" summary: "Inform Order Pickup" description: |- Inform the **Logistic Service** that the order was picked by delivery person at Merchant > **This is a OPTIONAL endpoint and should only be requested if the `notifyPickup` field has been set to `true` when sending the delivery request via the [POST /logistics/delivery](#operation/logisticsNewDelivery) endpoint.** responses: "200": description: "Order pickup has been confirmed." "400": $ref: "#/components/responses/BadRequest" "401": $ref: '#/components/responses/Unauthorized' "403": $ref: "#/components/responses/AccessDenied" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/UnprocessableEntity" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/logistics/orderPicked/{orderId}: post: operationId: "logisticsPicked" security: - OAuth2: [od.all] parameters: - name: orderId in: "path" required: true schema: type: string format: "uuid" description: "The orderId generated by the **`Ordering Application`**." example: "52122852-6626-11ed-9022-0242ac120002" requestBody: content: "application/json": schema: $ref: "#/components/schemas/DeliveryOrderPicked" tags: - "logisticOrder" summary: "Inform order pickup" description: "Inform the **Logistic Service** that the order was picked by delivery person at Merchant" responses: "200": description: "Order pickup has been confirmed." "400": $ref: "#/components/responses/BadRequest" "401": $ref: '#/components/responses/Unauthorized' "403": $ref: "#/components/responses/AccessDenied" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/UnprocessableEntity" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/logistics/finishDelivery/{orderId}: post: operationId: "logisticsFinish" security: - OAuth2: [od.all] parameters: - name: orderId in: "path" required: true schema: type: string format: "uuid" description: "The orderId generated by the **`Ordering Application`**." example: "52122852-6626-11ed-9022-0242ac120002" requestBody: content: "application/json": schema: $ref: "#/components/schemas/DeliveryOrderFinish" tags: - "logisticOrder" summary: "Finish Delivery" description: |- Indicates the completion of a delivery order. > **This is a OPTIONAL endpoint andshould only be requested if the `notifyConclusion` field has been set to `true` when sending the delivery request via the [POST /logistics/delivery](#operation/logisticsNewDelivery) endpoint.** responses: "200": description: "Delivery completion has been confirmed. " "400": $ref: "#/components/responses/BadRequest" "401": $ref: '#/components/responses/Unauthorized' "403": $ref: "#/components/responses/AccessDenied" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/UnprocessableEntity" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/logistics/handleProblem/{orderId}: post: operationId: "logisticsProblem" security: - OAuth2: [od.all] parameters: - name: orderId in: "path" required: true schema: type: string format: "uuid" description: "The orderId generated by the **`Ordering Application`**." example: "52122852-6626-11ed-9022-0242ac120002" requestBody: $ref: "#/components/requestBodies/DeliveryHandleProblem" tags: - "logisticOrder" summary: "Handle problem" description: |- Handle problems that may occur during the delivery. > Problems can occur at any time during a delivery in progress. It is important that the **Logistic Service** always informs the **Software Service** (or **Ordering Application**) of a problem (via webhook), even if the problem does not require any action by the merchant to solve it. > Since there are other ways to solve delivery problems, such as via telephone or messaging applications, the implementation of this endpoint is optional, and the **Logistic Service** will inform the **Software Service** (or **Ordering Application**) of the need to use it.
responses: "200": description: "The problem has been addressed." "400": $ref: "#/components/responses/BadRequest" "401": $ref: '#/components/responses/Unauthorized' "403": $ref: "#/components/responses/AccessDenied" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/UnprocessableEntity" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/logistics/cancel/{orderId}: post: operationId: "logisticsCancel" security: - OAuth2: [od.all] parameters: - name: orderId in: "path" required: true schema: type: string format: "uuid" description: "The orderId generated by the **`Ordering Application`**." example: "52122852-6626-11ed-9022-0242ac120002" requestBody: $ref: "#/components/requestBodies/DeliveryCancel" tags: - "logisticOrder" summary: "Cancel delivery" description: |- Requests cancellation of a order delivery in progress > The **Software Service** (or **Ordering Application**) may request to cancel the delivery of an order at any time. Depending on **Logistic Service** policies, additional fees may apply. > If the order being cancelled is in a combined delivery, when cancelling, the order informed will be unlinked from the delivery, not interrupting the progress of the other orders in the same delivery.
responses: "202": description: "Cancel request has been accepted for processing." content: "application/json": schema: $ref: "#/components/schemas/DeliveryCancelResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: '#/components/responses/Unauthorized' "403": $ref: "#/components/responses/AccessDenied" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/UnprocessableEntity" "503": $ref: "#/components/responses/ServiceUnavailable" x-webhooks: # Merchant /v1/menuUpdated: post: summary: New Merchant Update Notification description: |- > **POST /v1/merchantUpdate** Information about a update in the systems. This endpoint can be used in the following ways: **1 - Sent with an empty body:** This will force **Ordering Application** to make a new request to the **[GET /v1/merchant](#operation/getMerchant)** endpoint to update all the **merchant** information. **2 - Sent with only the `merchantStatus` field:** This will force the opening or closing of the **merchant** within the **Ordering Application**, without forcing a new **[GET /v1/merchant](#operation/getMerchant)** call. **3 - Sent only with the `entityType` and `updatedObjects` fields:** This will force the **Ordering Application** to update only the sent objects, without forcing a new **[GET /v1/merchant](#operation/getMerchant)** call. > When the `entityType` field is populated, the `updatedObjects` field cannot be empty. **4 - Sent the `merchantStatus`, `entityType` and `updatedObjects` fields:** This will force scenarios 2 and 3 to happen simultaneously.

HOST: **ORDERING APPLICATION** DIRECTION:
operationId: menuUpdated tags: - merchantUpdate security: - OAuth2: [od.all] requestBody: content: application/json: schema: $ref: '#/components/schemas/MerchantUpdate' responses: '200': description: Status 200 available for compatibility reasons. Please use status 204 instead. '204': description: Data was received successfully. No response content. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '503': $ref: '#/components/responses/ServiceUnavailable' # Order /v1/newEvent: post: operationId: newEvent security: - {} parameters: - in: 'header' name: 'X-App-Id' required: true schema: type: 'string' format: 'uuid' description: 'An unique Identificator of the `**Ordering Applications**`. The same ID must be sent to all `**Software Service**s` that implements this webhook.' - in: 'header' name: 'X-App-MerchantId' required: true schema: $ref: '#/components/schemas/Merchant/properties/id' description: 'An unique Identificator of the Merchant ' - in: 'header' name: 'X-App-Signature' required: true schema: type: 'string' format: 'SHA256' description: 'SHA256 hash of the request body, using the client secret as the key' summary: New Order Event Notification description: |- > **POST /v1/newEvent** Information about a new event in the systems

HOST: **SOFTWARE SERVICE** DIRECTION:
tags: - ordersWebhook requestBody: content: application/json: schema: $ref: '#/components/schemas/Event' responses: '200': description: Status 200 available for compatibility reasons. Please use status 204 instead. '204': description: Data was received successfully. No response content. '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' '503': $ref: '#/components/responses/ServiceUnavailable' # Logistic /v1/newLogisticEvent: post: operationId: newLogisticEvent security: - {} parameters: - in: "header" name: "X-App-Id" required: true schema: type: "string" format: "UUID" description: "An unique Identificator of the **`Logistic Service`**. The same ID must be sent to all `**Software Service**s` and `**Ordering Applications**` that implements this webhook." - in: "header" name: "X-App-MerchantId" required: true schema: $ref: "#/components/schemas/Merchant/properties/id" description: "An unique Identificator of the Merchant " - in: "header" name: "X-App-Signature" required: true schema: type: "string" format: "SHA256" description: "SHA256 hash of the request body, using the client secret as the key" summary: Tracking Event Webhook description: |- ### Delivery Order Event Notification Webhook is sent to notify the merchant **Software Service** (or the **Ordering Application**) that an new order event has happened on the **Logistic Service**. The host that implements this webhook, should return an HTTP `200` response code with an empty response body to acknowledge receipt of the webhook event. If the **Logistic Service** does not receive a `200` acknowledgement response, than the webhook event will be resent based on the **Logistic Service** policies. tags: - logisticsWebhook requestBody: $ref: "#/components/requestBodies/DeliveryEvent" responses: "204": description: Data was received successfully. No response content. "400": $ref: "#/components/responses/BadRequest" "403": $ref: "#/components/responses/AccessDenied" "404": $ref: "#/components/responses/NotFound" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/confirmationCode: post: operationId: logistictsDeliveryCode security: - {} parameters: - in: "header" name: "X-App-Id" required: true schema: type: "string" format: "UUID" description: "An unique Identificator of the **`Logistic Service`**. The same ID must be sent to all `**Software Service**s` and `**Ordering Applications**` that implements this webhook." - in: "header" name: "X-App-MerchantId" required: true schema: $ref: "#/components/schemas/Merchant/properties/id" description: "An unique Identificator of the Merchant " - in: "header" name: "X-App-Signature" required: true schema: type: "string" format: "SHA256" description: "SHA256 hash of the request body, using the client secret as the key" summary: Delivery Code Webhook description: |- ### Delivery Confirmation Code Notification Webhook is sent to notify the merchant **Software Service** (or the **Ordering Application**) of the Delivery Code, informed by the customer. With this code, the **Software Service** (or the **Ordering Application**) needs to access the Ordering Application confirmation process and return if the code is valid or not. The host that implements this webhook, should return: - HTTP `200` response code if the Delivery Code is **valid**. - HTTP `400` responde code if the Delivery Code is **invalid**. In this case you must inform the cause in the `title` propertie. tags: - logisticsWebhook requestBody: content: "application/json": schema: $ref: "#/components/schemas/DeliveryConfirmationCode" responses: "200": description: Confirmation Code is correct. You can proceed with the delivery. content: "application/json": schema: $ref: "#/components/schemas/DeliveryConfirmationCode" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "503": $ref: "#/components/responses/ServiceUnavailable" ############################################################# components: securitySchemes: OAuth2: type: oauth2 description: "OAuth2 should be the standard authentication method between parties. - For the **ORDERS** and **MERCHANT** endpoints, the **Ordering Application** is responsible for credentials and token generation. - For the **LOGISTICS** endpoints, the **Logistics Service** will be responsible for managing these infos. > Webhooks are an exception and have their own authentication method, not using OAuth. As of the time of this release only one scope will be used for all endpoints: `od.all`. ### Generating a Client Credentials Token To generate a client credentials token, the merchant **Software Service** must retrieve the **clientId** and **clientSecret** from a **Ordering Application** or **Logistics Service** company and access the [/oauth/token](#operation/getToken) endpoint. > The **Ordering Application** or **Logistics Service** MUST provide one `clientId` and `clientSecret` credentials for each individual merchant it will work with, even if these merchants use the same **Software Service**. ### Usage The **accessToken** field will contain the token used to authenticate against the **Open Delivery** APIs. Once you’ve obtained this token, you can provide it in the “Authorization” header of requests you make to endpoints that require client credentials scopes. The **expiresIn** field indicates the lifetime of the access token, provided in seconds. This should be cached and re-used across requests until (or shortly before) expiration, not re-generated per request. ``` curl \n -H 'authorization: Bearer ' \n https://{baseURL}/v1/events:polling ``` > Refresh Token is not available at this version." flows: clientCredentials: tokenUrl: oauth/token scopes: od.all: 'Access to all **Open Delivery** APIs' apiKey: type: apiKey description: "The apiKey is a key that should be generated by the endpoint's host and passed to its clients. Each client of the endpoint can have its own key. The creation and content of the key is of responsibility of the endpoint's host. > As of the time of this release, only the **[GET /v1/merchant](#operation/getMerchant)** endpoint can require authentication via apiKey." in: header name: X-API-KEY requestBodies: Token: required: true content: 'application/x-www-form-urlencoded': schema: $ref: '#/components/schemas/TokenRequest' examples: newToken: $ref: '#/components/examples/tokenExample' AckEvents: required: true content: 'application/json': schema: type: 'array' items: $ref: '#/components/schemas/AckEvents' maxItems: 100 CancelRequest: required: true content: 'application/json': schema: $ref: '#/components/schemas/RequestCancelled' CancelDenied: description: 'Request for order cancellation has been denied.' required: true content: 'application/json': schema: $ref: '#/components/schemas/RequestDenied' DeliveryOrder: description: "Request for a new delivery order" required: true content: "application/json": schema: $ref: "#/components/schemas/DeliveryOrder" # examples: # newOrder: # $ref: "#/components/examples/orderDeliveryExample" DeliveryEvent: description: "New event" required: true content: "application/json": schema: $ref: "#/components/schemas/DeliveryOrderEvent" # examples: # newEvent: # $ref: "#/components/examples/orderDeliveryEventExample" DeliveryHandleProblem: description: "New event" required: true content: "application/json": schema: $ref: "#/components/schemas/DeliveryHandleProblem" # examples: # newEvent: # $ref: "#/components/examples/orderDeliveryEventExample" DeliveryCancel: description: "New event" required: true content: "application/json": schema: $ref: "#/components/schemas/DeliveryCancel" responses: Accepted: description: 'Request has been accepted for processing.' BadRequest: description: 'Bad Request' content: application/problem+json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: 'Request lacks valid authentication credentials for the target resource' content: application/problem+json: schema: $ref: '#/components/schemas/Error' NotFound: description: 'The requested resource was not found.' content: application/problem+json: schema: $ref: '#/components/schemas/Error' AccessDenied: description: 'Authenticated participant request that violates some authorization rule.' content: application/problem+json: schema: $ref: '#/components/schemas/Error' UnprocessableEntity: description: 'Server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. (Check if the instruction has not been sent before.)' content: application/problem+json: schema: $ref: '#/components/schemas/Error' UnprocessableEntityOrderCancellation: description: 'Server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. (Check if the instruction has not been sent before.)' content: application/problem+json: schema: $ref: '#/components/schemas/CancellationError' ServiceUnavailable: description: 'Service is not currently available. Requested service may be under maintenance or outside the operating window.' content: application/problem+json: schema: $ref: '#/components/schemas/Error' schemas: # Versions VersionOrderingApp: type: 'object' properties: merchant: type: 'object' description: "Information regarding the **Merchant's** standard endpoints." properties: version: type: 'string' description: |- Current version for MERCHANT endpoints. Existing MERCHANT routes: > - "POST /v1/merchantUpdate" > - "GET /v1/merchantStatus" enum: - '1.0.0' - '1.0.1' - '1.1.0' - '1.1.1' - '1.2.0' - '1.2.1' - '1.3.0' - '1.3.1' - '1.4.0' - '1.5.0' - '1.6.0' order: type: 'object' description: "Information regarding the **Order's** standard endpoints." properties: version: type: 'string' description: |- Current version for ORDER endpoints. Existing ORDER routes: > - "GET /v1/events:polling" > - "POST /v1/events/acknowledgment" > - "GET /v1/orders/{orderId}" > - "POST /v1/orders/{orderId}/confirm" > - "POST /v1/orders/{orderId}/preparing" > - "POST /v1/orders/{orderId}/readyForPickup" > - "POST /v1/orders/{orderId}/pickedUp" > - "POST /v1/orders/{orderId}/dispatch" > - "POST /v1/orders/{orderId}/delivered" > - "POST /v1/orders/{orderId}/requestCancellation" > - "POST /v1/orders/{orderId}/acceptCancellation" > - "POST /v1/orders/{orderId}/denyCancellation" enum: - '1.0.0' - '1.0.1' - '1.1.0' - '1.1.1' - '1.2.0' - '1.2.1' - '1.3.0' - '1.3.1' - '1.4.0' - '1.5.0' - '1.6.0' availableEventsMethods: type: array description: 'Lists which methods for obtaining new order events the **Software Service** can use with this **Ordering Application**.' items: type: 'string' enum: - 'POLLING' - 'WEBHOOK' VersionMerchant: type: 'object' properties: merchantEndpoint: type: 'string' description: |- Current version for the `GET /v1/merchant` endpoint. enum: - '1.0.0' - '1.0.1' - '1.1.0' - '1.1.1' - '1.2.0' - '1.2.1' ordersWebhook: type: 'string' description: |- Current version for the `/v1/orderUpdate` webhook. enum: - '1.0.0' - '1.0.1' - '1.1.0' - '1.1.1' - '1.2.0' - '1.2.1' # Authentication TokenRequest: type: 'object' title: 'TokenRequest' required: ['client_id', 'client_secret', 'grant_type'] properties: client_id: type: 'string' description: 'Client identifier provided by the **Ordering Application**.' client_secret: type: 'string' description: 'Client Secret provided by the **Ordering Application**.' grant_type: type: 'string' description: 'The OAuth grant type. Currently, the only supported grant type is `client_credentials`.' enum: - 'client_credentials' TokenResponse: type: 'object' title: 'TokenResponse' required: ['access_token', 'token_type'] properties: access_token: type: 'string' description: 'A code representing the access token.' token_type: type: 'string' description: 'The token type. Currently, the only supported type is `bearer`' enum: - 'bearer' expires_in: type: 'number' format: 'double' description: 'The token expiration time in seconds' #Merchant Merchant: type: 'object' title: 'MenuEntity' required: [ 'lastUpdate', 'TTL', id, 'status', 'basicInfo', 'services', 'items', 'menus', 'categories', 'itemOffers', ] properties: lastUpdate: type: 'string' format: 'date-time' description: "The last modified date and time in ISO timestamp format but with type String. \n\nThis should be used in conjuction of the TTL field to update the information on the ordering aplication. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." example: '2021-05-27T20:45:10.332Z' TTL: type: 'integer' description: "Time to Live (in seconds). \nMin: 500 Max: 86400. \nA new request must be done when the TTL expires." example: 500 id: type: 'string' description: |- Unique Identifier. Identifies the merchant in the different systems that the merchant will communicate. This id must be generated by the merchant's **`Software Service`**. > To avoid duplicates between different merchants it is recommended that the software creates the merchantId using: > `Merchant Document + UUID` > If this is not possible, it is recommended to at least use a UUID. minLength: 36 maxLength: 100 example: '22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824' status: type: 'string' description: "Indicates if the Merchant is Avaliable or Unavaliable. Only use this type when you must close (disable) the merchant due to an unexpected event and you don't know when the service will be re-established (e.g. do not use for holidays)." enum: - AVAILABLE - UNAVAILABLE example: 'AVAILABLE' basicInfo: type: 'object' description: 'A required entity to implement. Describes basic info of a merchant.' allOf: - $ref: '#/components/schemas/BasicInfo' services: type: 'array' description: 'A required entity to implement. Describes food ordering services details for a merchant.' items: $ref: '#/components/schemas/Service' menus: type: 'array' description: 'A required entity to implement. Describes an array of menus.' items: $ref: '#/components/schemas/Menu' categories: type: 'array' description: 'A required entity to implement. Describes an array of sections in the menu where `ItemOffers` will be showed.' items: type: 'object' $ref: '#/components/schemas/Category' itemOffers: type: 'array' description: 'A required entity to implement. Describes an array of offers for the `Items`.' items: type: 'object' $ref: '#/components/schemas/ItemOffer' items: type: 'array' description: 'A required entity to implement. Describes an array of items. To be used with an `ItemOffer` or an `Option`.' items: $ref: '#/components/schemas/Item' optionGroups: type: 'array' description: 'An optional entity to implement. Describes additional options of an `ItemOffer`.' items: $ref: '#/components/schemas/OptionGroup' availabilities: type: 'array' description: 'An optional entity to implement. Describes the time period during which a `Category` or an `ItemOffer` entity is served.' items: type: 'object' allOf: - $ref: '#/components/schemas/Availability' UpdateMerchant: type: 'object' required: [ 'id', 'status', 'basicInfo', 'services', 'items', 'menus', 'categories', 'itemOffers', ] properties: id: type: 'string' description: |- Unique Identifier. Identifies the merchant in the different systems that the merchant will communicate. This id must be generated by the merchant's **`Software Service`**. > To avoid duplicates between different merchants it is recommended that the software creates the merchantId using: > `Merchant Document + UUID` > If this is not possible, it is recommended to at least use a UUID. minLength: 36 maxLength: 100 status: type: 'string' description: "Indicates if the Merchant is Avaliable or Unavaliable. Only use this type when you must close (disable) the merchant due to an unexpected event and you don't know when the service will be re-established (e.g. do not use for holidays)." enum: - AVAILABLE - UNAVAILABLE example: 'AVAILABLE' basicInfo: type: 'object' description: 'A required entity to implement. Describes basic info of a merchant.' allOf: - $ref: '#/components/schemas/BasicInfo' services: type: 'array' description: 'A required entity to implement. Describes food ordering services details for a merchant.' items: $ref: '#/components/schemas/Service' menus: type: 'array' description: 'A required entity to implement. Describes an array of menus.' items: $ref: '#/components/schemas/Menu' categories: type: 'array' description: 'A required entity to implement. Describes an array of sections in the menu where `ItemOffers` will be showed.' items: type: 'object' $ref: '#/components/schemas/Category' itemOffers: type: 'array' description: 'A required entity to implement. Describes an array of offers for the `Items`.' items: type: 'object' $ref: '#/components/schemas/ItemOffer' items: type: 'array' description: 'A required entity to implement. Describes an array of items. To be used with an `ItemOffer` or an `Option`.' items: $ref: '#/components/schemas/Item' optionGroups: type: 'array' description: 'An optional entity to implement. Describes additional options of an `ItemOffer`.' items: $ref: '#/components/schemas/OptionGroup' availabilities: type: 'array' description: 'An optional entity to implement. Describes the time period during which a `Category` or an `ItemOffer` entity is served.' items: type: 'object' allOf: - $ref: '#/components/schemas/Availability' MerchantDescription: type: 'object' title: 'MenuEntity' required: [ 'lastUpdate', 'TTL', id, 'status', 'basicInfo', 'services', 'items', 'menus', 'categories', 'itemOffers', ] properties: lastUpdate: type: 'string' format: 'date-time' description: "The last modified date and time. \n\nThis should be used in conjuction of the TTL field to update the information on the ordering aplication. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." TTL: type: 'integer' description: "Time to Live (in seconds). \nMin: 500 Max: 86400. \nA new request must be done when the TTL expires." id: type: 'string' format: 'uuid' description: "Unique Identifier. Must be formatted with `Merchant Document + UUID` \n\n This id must be generated by the company responsible for the merchant's menu and have to be informed in the Order object by the ***Ordering Application***." status: type: 'string' description: "Indicates if the entity is Avaliable or Unavaliable. Only use this type when you must disable the entity due to an unexpected event and you don't know when the service will be re-established (e.g. do not use for holidays)." enum: - AVAILABLE - UNAVAILABLE basicInfo: type: 'object' description: "See: **[BasicInfo](#section/BasicInfo)** \n\n A required entity to implement. Describes basic info of a merchant." services: type: 'array' description: "See: **[Service](#section/Service)** \n\n A required entity to implement. Describes food ordering services details for a merchant." items: type: 'object' menus: type: 'array' description: "See: **[Menu](#section/Menu)** \n\n A required entity to implement. Describes an array of menus." items: type: 'object' items: type: 'array' description: "See: **[Item](#section/Menu/Item)** \n\n A required entity to implement. Describes an array of items. To be used with an `ItemOffer` or an `OptionGroups`." items: type: 'object' categories: type: 'array' description: "See: **[Category](#section/Menu/Category)** \n\n A required entity to implement. Describes an array of sections in the menu where `ItemOffers` will be showed." items: type: 'object' itemOffers: type: 'array' description: "See: **[ItemOffers](#section/Menu/ItemOffer)** \n\n A required entity to implement. Describes an array of offers for the `Items`." items: type: 'object' optionGroups: type: 'array' description: "See: **[Options](#section/Menu/OptionGroup-and-Option)** \n\n An optional entity to implement. Describes additional options of an `ItemOffer`." items: type: 'object' availabilities: type: 'array' description: "See: **[Availability](#section/Menu/Availability)** \n\n An optional entity to implement. Describes the time period during which a `Category` or an `ItemOffer` entity is served." items: type: 'object' BasicInfo: type: 'object' title: 'BasicInfo' required: [ 'name', 'document', 'corporateName', 'description', 'averagePreparationTime', 'minOrderValue', 'merchantType', 'merchantCategories', 'address', 'contactEmails', 'contactPhones', 'logoImage', ] properties: name: type: 'string' description: 'Merchant Public Name' maxLength: 500 example: 'Pizza Plaza' document: type: 'string' description: 'Merchant Document' pattern: "^\\d{14}$" example: '22815773000169' corporateName: type: 'string' description: 'Merchant Corporate Name' maxLength: 500 example: 'Food Company' description: type: 'string' description: 'Merchant Description' example: 'Food company specializing in pizzas.' averageTicket: type: 'number' format: 'decimal' description: 'Average Ticket. Can be used to show the price range of items available at the merchant. It is not mandatory, but recommended to be used.' example: 90 averagePreparationTime: type: 'number' format: 'double' description: 'Average amount of time preparing an order takes, in minutes.' example: 20 minOrderValue: type: 'object' description: 'Minimum order value that the merchant accepts.' allOf: - $ref: '#/components/schemas/Price' merchantType: type: 'string' description: 'Merchant Type. Currently, only `RESTAURANT` is accepted.' enum: - 'RESTAURANT' example: 'RESTAURANT' merchantCategories: type: 'array' description: 'Merchant Categories' items: type: 'string' enum: - 'BURGERS' - 'PIZZA' - 'FAST_FOOD' - 'HOT_DOG' - 'JAPANESE' - 'DESSERTS' - 'AMERICAN' - 'ICE_CREAM' - 'BBQ' - 'SANDWICH' - 'MEXICAN' - 'BRAZILIAN' - 'PASTRY' - 'ARABIAN' - 'COMFORT_FOOD' - 'VEGETARIAN' - 'VEGAN' - 'BAKERY' - 'HEALTHY' - 'ITALIAN' - 'CHINESE' - 'JUICE_SMOOTHIES' - 'SEAFOOD' - 'CAFE' - 'SALADS' - 'COFFEE_TEA' - 'PASTA' - 'BREAKFAST_BRUNCH' - 'LATIN_AMERICAN' - 'CONVENIENCE' - 'PUB' - 'HAWAIIAN' - 'EUROPEAN' - 'FAMILY_MEALS' - 'FRENCH' - 'INDIAN' - 'PORTUGUESE' - 'SPANISH' - 'GOURMET' - 'KIDS_FRIENDLY' - 'SOUTH_AMERICAN' - 'SPECIALTY_FOODS' - 'ARGENTINIAN' - 'PREMIUM' - 'AFFORDABLE_MEALS' example: ['PIZZA', 'FAMILY_MEALS', 'PREMIUM'] address: type: 'object' description: 'Merchant Address' allOf: - $ref: '#/components/schemas/Address' contactEmails: type: 'array' description: 'Merchant Contact Emails' items: type: 'string' example: ['food@company.com'] contactPhones: type: 'object' description: 'Merchant Contact Phones' allOf: - $ref: '#/components/schemas/ContactPhones' logoImage: type: 'object' description: 'Image to be used as the merchant logo' allOf: - $ref: '#/components/schemas/Image' bannerImage: type: 'object' description: 'Image to be used as the merchant banner (the banner display depends on the client application interface)' allOf: - $ref: '#/components/schemas/Image' createdAt: type: 'string' format: date-time description: "Merchant creation date and time. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." acceptedCards: type: array description: 'Indicates which card brands are accepted by the merchant.' items: type: string enum: - 'VISA' - 'MASTERCARD' - 'DINERS' - 'AMEX' - 'HIPERCARD' - 'ELO' - 'AURA' - 'DISCOVER' - 'VR_BENEFICIOS' - 'SODEXO' - 'TICKET' - 'GOOD_CARD' - 'BANESCARD' - 'SOROCARD' - 'POLICARD' - 'VALECARD' - 'AGICARD' - 'JCB' - 'CREDSYSTEM' - 'CABAL' - 'GREEN_CARD' - 'VEROCHEQUE' - 'AVISTA' - 'OTHER' Service: type: 'object' title: 'Service' required: [id, 'status', 'serviceType', 'menuId', 'serviceHours'] properties: id: type: 'string' format: 'uuid' description: 'Unique Identifier' example: 'f078e8e2-3044-4eec-b4a8-8359810de123' status: type: 'string' description: "Indicates if the entity is Avaliable or Unavaliable. Only use this type when you must disable the entity due to an unexpected event and you don't know when the service will be re-established (e.g. do not use for holidays)." enum: - AVAILABLE - UNAVAILABLE example: 'AVAILABLE' serviceType: type: 'string' description: |- The type of service being offered: `DELIVERY` - for orders that will be delivered to the customer's address. `TAKEOUT` - orders that will be picked up at the establishment by the customer `INDOOR` - orders that will be consumed inside the establishment. enum: - DELIVERY - TAKEOUT - INDOOR example: 'DELIVERY' serviceTiming: type: 'object' title: 'Service Timing' description: 'Information regarding the accepted service times.' properties: timing: type: 'array' description: |- Indicates the timings that the service accepts: `INSTANT`: for orders that must be prepared immediately. `SCHEDULED`: for orders scheduled for a specific date and time. `ONDEMAND`: for orders that will only be delivered when the consumer indicates that they are going to pick it up. Please inform all accepted types in the field. If not informed, defaults to the `INSTANT` option. items: type: 'string' enum: - INSTANT - SCHEDULED - ONDEMAND default: ['INSTANT'] example: ['INSTANT', 'SCHEDULED'] schedule: type: 'object' description: "Information regarding the time windows for scheduling. \n\n This only applies to the `SCHEDULED` service timing." required: [scheduleTimeWindow, scheduleStartWindow, scheduleEndWindow] properties: scheduleTimeWindow: type: string description: |- Time window where scheduling will be possible. > Example: If `15_MINUTES` is chosen, then the available scheduling times will be displayed every 15 minutes (e.g. 9:15, 9:30, 9:45, 10:00). enum: - 15_MINUTES - 30_MINUTES - 45_MINUTES - 60_MINUTES - 90_MINUTES - 120_MINUTES scheduleStartWindow: type: string description: |- Informs how long after the merchant has opened (considering the `serviceHours` entity) the first schedule time will be displayed. > Example: Service starts at 9:00 and the option `45_MINUTES` was entered, then the first available time for scheduling will be 9:45. enum: - 15_MINUTES - 30_MINUTES - 45_MINUTES - 60_MINUTES - 90_MINUTES - 120_MINUTES scheduleEndWindow: type: string description: |- Informs how long before the merchant closes (considering the `serviceHours` entity) the last schedule time will be displayed. > Example: Service ends at 23:00 and the option `60_MINUTES` was entered, then the last available time for scheduling will be 22:00. enum: - 15_MINUTES - 30_MINUTES - 45_MINUTES - 60_MINUTES - 90_MINUTES - 120_MINUTES servicePriority: type: array description: |- Indicates to the **Ordering Application** whether the merchant works with different order preparation and delivery priorities. Must enter up to how many priority levels the merchant serves. If not entered, it means that the merchant does not have any specific configuration for working with priority, and may or may not be able to do so. **Note:** this field only makes sense for **Ordering Applications** that work with different delivery priorities. items: type: 'string' enum: - 'PRIORITY1' - 'PRIORITY2' - 'PRIORITY3' - 'PRIORITY4' - 'PRIORITY5' example: ['PRIORITY1', 'PRIORITY2'] menuId: description: 'The id value of the `Menu` entity correlated to this `Service` entity.' type: string format: uuid example: 'f627ccdc-6789-456f-a782-148538d5035b' targetAppId: type: 'string' format: uuid description: 'This field is for situations in which the merchant needs to send different menus for the same `serviceType` to different **Ordering Applications** (this can occur when there is an integration software between the merchant software and the **Ordering Application**). In this case this field must be filled in with the `AppId` of the **OrderingApplication** which will receive this `service` info.' serviceArea: type: 'object' description: 'A conditional entity to implement (required if the Service entity associated has serviceType set to `DELIVERY`). Describes the geographical region in which food can be delivered.' allOf: - $ref: '#/components/schemas/ServiceArea' serviceHours: type: 'object' description: 'A required entity to implement. Describes the time window which users can place orders.' allOf: - $ref: '#/components/schemas/ServiceHours' ServiceArea: type: 'object' title: 'Service Area' required: [id] properties: id: type: 'string' format: 'uuid' description: 'A unique identifier of the service area.' example: '01339e6d-520b-429e-bc7c-dcfd2df42278' polygon: type: 'array' description: "If the `polygon` is chosen to be used, `geoRadius` is not required.\n\n\n\nA polygon or multipolygon expressed as a series of three or more space delimited points." items: allOf: - $ref: '#/components/schemas/Polygon' geoRadius: type: 'object' description: 'If the `geoRadius` is chosen to be used, `polygon` is not required. Indicates the approximate radius (in meters) of the CIRCLE area.' allOf: - $ref: '#/components/schemas/GeoRadius' exclusionAreaPolygon: type: 'array' description: "This object will act as a complement, indicating specific polygons within the previously mapped delivery area, where NO deliveries will be made. \n This field can be filled in regardless of whether `polygon` or `geoRadius` is used." items: allOf: - $ref: '#/components/schemas/ExclusionPolygon' Polygon: type: 'object' title: 'Polygon' required: [geoCoordinates] properties: geoCoordinates: type: 'array' description: "Coordinates of each point of the polygon. It is recommended that the first and last points be the same, but it is not required.\n\n\n\nEach point in a polygon or multipolygon is defined by a latitude point followed by a longitude point. You also must specify the points in a counter-clockwise direction." items: type: 'object' title: 'geoCoordinate' required: ['latitude', 'longitude'] properties: latitude: type: 'number' format: 'float' description: "Indicates the latitude coordinate of the polygon point.\n\n\n\nLatitude in degrees. Values are restricted to the range [[-90, 90]]." example: -23.54809 longitude: type: 'number' format: 'float' description: "Indicates the longitude coordinate of the polygon point.\n\n\n\nLongitude in degrees. Values are restricted to the range [[-180, 180]]." example: -46.63638 price: type: 'object' description: 'Price of the fee for this polygon' allOf: - $ref: '#/components/schemas/Price' example: { value: 5, currency: 'BRL' } estimateDeliveryTime: type: 'integer' description: 'Estimate delivery time for this polygon in minutes' ExclusionPolygon: type: 'object' title: 'Polygon' required: [geoCoordinates] properties: geoCoordinates: type: 'array' description: "Coordinates of each point of the polygon. It is recommended that the first and last points be the same, but it is not required.\n\n\n\nEach point in a polygon or multipolygon is defined by a latitude point followed by a longitude point. You also must specify the points in a counter-clockwise direction." items: type: 'object' title: 'geoCoordinate' required: ['latitude', 'longitude'] properties: latitude: type: 'number' format: 'float' description: "Indicates the latitude coordinate of the polygon point.\n\n\n\nLatitude in degrees. Values are restricted to the range [[-90, 90]]." example: -23.54809 longitude: type: 'number' format: 'float' description: "Indicates the longitude coordinate of the polygon point.\n\n\n\nLongitude in degrees. Values are restricted to the range [[-180, 180]]." example: -46.63638 GeoRadius: type: 'object' title: 'GeoRadius' required: [geoMidpointLatitude, geoMidpointLongitude, radius] properties: geoMidpointLatitude: type: 'number' format: 'float' description: "Indicates the latitude coordinate at the center of the CIRCLE area.\n\n\n\nLatitude in degrees. Values are restricted to the range [[-90, 90]]." example: -23.54809 geoMidpointLongitude: type: 'number' format: 'float' description: "Indicates the longitude coordinate at the center of the CIRCLE area.\n\n\n\nLongitude in degrees. Values are restricted to the range [[-180, 180]]." example: -46.63638 radius: type: 'array' description: 'Informations about each radius of the CIRCLE that the merchant serves.' items: type: 'object' title: 'radius' required: ['size'] properties: size: type: 'integer' description: 'The size of the CIRCLE radius in meters.' price: type: 'object' description: 'Price of the fee for this CIRCLE size.' allOf: - $ref: '#/components/schemas/Price' example: { value: 5, currency: 'BRL' } estimateDeliveryTime: type: 'integer' description: 'Estimate delivery time for this CIRCLE size in minutes.' ItemPrice: type: 'object' title: 'Item Price' required: ['value', 'originalValue', 'currency'] properties: value: type: 'number' format: 'decimal' description: 'The actual price value. 4 decimals places are accepted' example: 50 originalValue: type: 'number' format: 'decimal' description: 'The orginal price value. 4 decimals places are accepted' example: 50 currency: type: 'string' pattern: '^[A-Z]{3}$' description: 'The 3-letter ISO 4217 currency code.' example: 'BRL' ServiceHours: type: 'object' title: 'Service Hours' required: [id, 'weekHours'] properties: id: type: 'string' format: 'uuid' description: 'A unique identifier of the service hours.' example: 'fb093d8c-2ca5-40fb-afcf-472fbdae81cc' weekHours: type: array description: 'A list of the day(s) of the week and time periods for which the service is valid.' items: type: 'object' allOf: - $ref: '#/components/schemas/Hours' holidayHours: type: array description: 'Map of holiday dates, each with optional `timePeriods`. If a date does not have a time period specified, the restaurant will be closed for that date.' items: type: 'object' allOf: - $ref: '#/components/schemas/HolidayHours' Hours: type: 'object' title: 'Hours' required: ['dayOfWeek', 'timePeriods'] properties: dayOfWeek: type: array description: 'Day of the week for which these service hours are valid' items: type: 'string' enum: - 'MONDAY' - 'TUESDAY' - 'WEDNESDAY' - 'THURSDAY' - 'FRIDAY' - 'SATURDAY' - 'SUNDAY' example: [ 'MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY', ] timePeriods: type: 'object' description: "Time window from which users' orders can be placed." allOf: - $ref: '#/components/schemas/TimePeriods' TimePeriods: type: 'object' title: 'Time Periods' required: ['startTime', 'endTime'] properties: startTime: type: string format: time description: "Indicates the specific time of day in ISO format starting from which users' orders can be placed." example: '10:00:00.000Z' endTime: type: string format: time description: "Indicates the specific time of day in ISO format beyond which users' orders cannot be placed." example: '18:00:00.000Z' HolidayHours: type: 'object' title: 'Holiday Hours' required: ['date', 'timePeriods'] properties: date: type: string format: date description: 'date in UTC (RFC3339 format, e.g. 2021-07-04)' example: '2021-07-04' timePeriods: type: 'object' description: 'hours' allOf: - $ref: '#/components/schemas/TimePeriods' Item: type: 'object' title: 'Item' required: [id, 'name', 'description', 'externalCode', 'unit'] properties: id: type: 'string' format: 'uuid' description: 'A unique identifier of the item.' example: '732bd31e-77fc-47ee-88ee-a0437f97b198' name: type: 'string' description: 'Item name' maxLength: 150 example: '1/2 Pepperoni' description: type: 'string' description: 'Item Description' example: 'Pepperoni flavored pizza with LOTS of pepperoni.' externalCode: type: 'string' description: 'Item External Code. (Tipically the merchant **Software Service** item code)' example: '233467' status: type: 'string' description: "Indicates if the entity is Avaliable or Unavaliable. Only use this type when you must disable the entity due to an unexpected event and you don't know when the service will be re-established (e.g. do not use for holidays). Default is `AVAILABLE`." enum: - AVAILABLE - UNAVAILABLE default: 'AVAILABLE' example: 'AVAILABLE' image: type: 'object' description: |- Image of the item. This field should be used when there is only one image for the item without size variations. It must **be considered** only if the `images` array **is empty**. If `images` **contains any value**, this field must **be ignored** even if it is filled. allOf: - $ref: '#/components/schemas/Image' images: type: 'array' maxItems: 2 items: allOf: - $ref: '#/components/schemas/ImageWithType' description: |- Array of images of the item. This field should be used when you need size variations for the images. If this array **contains any value**, it must **be considered** and the `image` field must be ignored. If this array is **empty**, the `image` field must be considered. nutritionalInfo: type: 'object' description: 'Nutrition information for the dish.' allOf: - $ref: '#/components/schemas/NutritionalInfo' serving: type: 'integer' description: 'Field to show the number of people the portion serves.' example: 2 unit: type: 'string' description: | Item's Unit of Measurement. Possible values: - `UN` - Unit - `KG` - Kilogram - `L` - Liter - `OZ` - Ounce - `LB` - Pound - `GAL` - Gallon enum: - 'UN' - 'KG' - 'L' - 'OZ' - 'LB' - 'GAL' example: 'KG' ean: type: 'string' description: 'EAN (European Article Number)' example: '7896005202074' NutritionalInfo: type: 'object' title: 'Nutritional Info' required: ['description', 'calories'] properties: description: type: 'string' description: 'Nutrition information in free text. For example "Contains preservatives".' example: 'Contains preservatives' calories: type: 'string' description: 'The number of calories in Cal, kcal, or kJ, using the following format: value Cal or min-max Cal' pattern: "^[0-9]+(\\.[0-9]+)? ?(- ?[0-9]+(\\.[0-9]+)?)? [a-zA-Z]+$" example: '2000 Cal' allergen: type: 'array' description: 'Allergens of this Item' items: type: 'string' enum: - 'ALMONDS' - 'ALPHA_ISOMETHYL_IONONE' - 'ALCOHOL' - 'AMYL_CINNAMAL' - 'ANISE_ALCOHOL' - 'BARLEY' - 'BENZYL_ALCOHOL' - 'BENZYL_BENZOATE' - 'BENZYL_CINNAMATE' - 'BENZYL_SALICYLATE' - 'BRAZIL_NUTS' - 'BUTYLPHENYL_METHYLPROPIONATE' - 'CARROTS' - 'CASHEW_NUTS' - 'CELERY' - 'CEREALS_CONTAINING_GLUTEN' - 'CINNAMAL' - 'CINNAMYL_ALCOHOL' - 'CITRAL' - 'CITRONELLOL' - 'COCOA' - 'CORIANDER' - 'CORN' - 'COUMARIN' - 'CRUSTACEANS' - 'EGGS' - 'EUGENOL' - 'EVERNIA_FURFURACEA' - 'EVERNIA_PRUNASTRI' - 'FARNESOL' - 'FISH' - 'GERANIOL' - 'GLUTEN' - 'HAZELNUTS' - 'HEXYL_CINNAMAL' - 'HYDROXYCITRONELLAL' - 'KAMUT' - 'LACTOSE' - 'LUPINE' - 'MACADAMIA_NUTS' - 'METHYL_2_OCTYNOATE' - 'MILK' - 'MOLLUSCS' - 'MUSTARD' - 'NO_DECLARED_ALLERGENS' - 'OAT' - 'PEANUTS' - 'PEAS' - 'PECAN_NUTS' - 'PISTACHIOS' - 'POD_FRUITS' - 'QUEENSLAND_NUTS' - 'RYE' - 'SESAME_SEEDS' - 'SOYBEANS' - 'SPELT' - 'SULPHUR_DIOXIDE' - 'TREE_NUTS' - 'TREE_NUT_TRACES' - 'WALNUTS' - 'WHEAT' example: 'GLUTEN' additives: type: 'array' description: 'Additives of this Item' items: type: 'string' suitableDiet: type: 'array' description: 'The dish complies with the described dietary restriction' items: type: 'string' enum: - 'DIABETIC' - 'GLUTEN_FREE' - 'HALAL' - 'HINDU' - 'KOSHER' - 'LOW_CALORIE' - 'LOW_FAT' - 'LOW_LACTOSE' - 'LOW_SALT' - 'VEGAN' - 'VEGETARIAN' isAlcoholic: type: 'boolean' description: 'Indicates if an item is alcoholic.' example: false Menu: type: 'object' title: 'Menu' required: [id, 'name', 'externalCode', 'categoryId'] properties: id: type: 'string' format: 'uuid' description: 'A unique identifier of the menu.' example: 'f627ccdc-6789-456f-a782-148538d5035b' name: type: 'string' description: 'Menu name' maxLength: 500 example: 'Pizzas' description: type: 'string' description: 'Menu Description' example: 'Pizza menu' externalCode: type: 'string' description: 'Menu External Code. (Tipically the merchant **Software Service** menu code)' example: '123' disclaimer: type: 'string' description: 'Disclaimer' example: 'Lorem Ipsum is simply dummy text of the printing and typesetting industry.' disclaimerURL: type: 'string' format: 'uri' description: 'Disclaimer URL' categoryId: type: 'array' description: 'A list of the id values of the child `Category` entities that correspond to this `Menu` entity. Default assumes all `Category` entities are available in this menu.' items: type: 'string' format: 'uuid' example: [ '92fad022-2c28-4239-a026-989f5b555cb7', '6bb71850-1d40-49f9-8046-b13e068c0cca', ] Category: type: 'object' title: 'Category' required: [id, 'index', 'name', 'externalCode', 'status'] properties: id: type: 'string' format: 'uuid' description: 'A unique identifier of the category.' example: '92fad022-2c28-4239-a026-989f5b555cb7' index: type: 'integer' description: 'Category display index.' example: 0 name: type: 'string' description: 'Category name.' maxLength: 150 example: 'Salted Pizza' description: type: 'string' description: 'Category description.' example: 'Salted pizza flavors.' image: type: 'object' description: 'Image of the category (the category image display depends on the client application interface)' allOf: - $ref: '#/components/schemas/Image' externalCode: type: 'string' description: 'Category External Code. (Tipically the merchant **Software Service** category code)' example: '13' status: type: 'string' description: "Indicates if the entity is Avaliable or Unavaliable. Only use this type when you must disable the entity due to an unexpected event and you don't know when the service will be re-established (e.g. do not use for holidays)." enum: - AVAILABLE - UNAVAILABLE example: 'AVAILABLE' availabilityId: type: 'array' description: |- The id values of `Availability` entities which provide details on when the category is available. > **If not informed, assumes a `Category` is AVAILABLE at all times.** items: type: 'string' format: 'uuid' description: 'A unique identifier of the availability.' example: '11d063c4-73a7-4f87-a0eb-71636cc02029' example: ['11d063c4-73a7-4f87-a0eb-71636cc02029'] itemOfferId: type: array description: 'A list of the id values of the child `ItemOffer` entities that correspond to this `Category` entity. Default assumes all `ItemOffer` entities are available in this category.' items: type: 'string' format: 'uuid' description: 'A unique identifier of the item offer.' example: 'f080cfb3-5c4a-4eb7-907d-2de3bbb5dfb9' example: ['f080cfb3-5c4a-4eb7-907d-2de3bbb5dfb9'] ItemOffer: type: 'object' title: 'ItemOffer' required: [id, 'itemId', 'index', 'price'] properties: id: type: 'string' format: 'uuid' description: 'A unique identifier of the item offer.' example: 'f080cfb3-5c4a-4eb7-907d-2de3bbb5dfb9' itemId: type: 'string' description: 'The id value of the `Item` entity correlated to this `ItemOffer` entity.' example: '732bd31e-77fc-47ee-88ee-a0437f97b198' index: type: integer description: 'ItemOffer display index.' example: 0 status: type: 'string' description: "Indicates if the entity is Avaliable or Unavaliable. Only use this type when you must disable the entity due to an unexpected event and you don't know when the service will be re-established (e.g. do not use for holidays). Default is `AVAILABLE`." enum: - AVAILABLE - UNAVAILABLE default: 'AVAILABLE' example: 'AVAILABLE' price: type: 'object' description: 'Price of the menu item offer. Original and actual values can be informed, for showing discounts.' allOf: - $ref: '#/components/schemas/ItemPrice' example: { value: 43, originalValue: 43, currency: 'BRL' } availabilityId: type: 'array' description: |- The id values of `Availability` entities which provide details on when the menu item offer is available. > **If not informed, assumes an `ItemOffer` is AVAILABLE at all times.** items: type: 'string' format: 'uuid' description: 'A unique identifier of the availability.' example: '11d063c4-73a7-4f87-a0eb-71636cc02029' example: ['11d063c4-73a7-4f87-a0eb-71636cc02029'] optionGroupsId: type: 'array' description: 'A list of the id values of the child `OptionGroup` entities that correspond to this `ItemOffer` entity.' items: type: 'string' format: 'uuid' description: 'A unique identifier of the option group.' example: 'fe67e551-f42f-499a-8afb-0ed893c71fa3' example: ['fe67e551-f42f-499a-8afb-0ed893c71fa3'] OptionGroup: type: 'object' title: 'Option Group' required: [ id, 'index', 'name', 'externalCode', 'status', 'minPermitted', 'maxPermitted', ] properties: id: type: 'string' format: 'uuid' description: 'A unique identifier of the option group.' example: 'fe67e551-f42f-499a-8afb-0ed893c71fa3' index: type: integer description: 'Option Group display index.' example: 0 name: type: 'string' description: 'Option Group Name.' maxLength: 150 example: 'Choose your salted pizza flavor' description: type: 'string' description: 'Option Group Description.' example: 'Choose your salted pizza flavor.' externalCode: type: 'string' description: 'Option External Code. (Tipically the merchant **Software Service** option group code)' example: '12' status: type: 'string' description: "Indicates if the entity is Avaliable or Unavaliable. Only use this type when you must disable the entity due to an unexpected event and you don't know when the service will be re-established (e.g. do not use for holidays)." enum: - AVAILABLE - UNAVAILABLE example: 'AVAILABLE' minPermitted: type: integer description: 'The minimum number of options which should be selected in the option group.' example: 2 maxPermitted: type: integer description: 'The maximum number of options which should be selected in the option group.' example: 2 priceMethod: type: string description: |- Instructions on how this `optionGroup` should be calculated before being applied to the item. **- SUM**: It will be added to the other optionGroups without any additional rules. **Default** option. **- MAX**: The highest `optionGroup` value between all `optionGroups` with `priceMethod` = `MAX` will be applied to the calculation. **- AVG**: The average between `optionGroup` with `priceMethod` = `AVG` will be applied to the calculation. Example: item base price: $25,00 optionGroup1 - priceMethod = **AVG** - __option 1 = $5,00 (selected)__ - option 2 = $10,00 (not selected) optionGroup2 - priceMethod = **AVG** - option 1 = $7,00 (not selected) - __option 2 = $10,00 (selected)__ optionGroup3 - priceMethod = **MAX** - __option 1 = $15,00 (selected)__ - option 2 = $20,00 (not selected) optionGroup4 - priceMethod = **MAX** - option 1 = $30,00 (not selected) - __option 2 = $35,00 (selected)__ optionGroup5 - priceMethod = **SUM** - option 1 = $2,00 (not selected) - __option 2 = $3,00 (selected)__ - option 3 = $5,00 (not selected) **optionsPrice** = avg(optionGroup1, optionGroup2) + max(optionGroup3, optionGroup4) + optionGroup5 **optionsPrice** = 7,50 + 35,00 + 3,00 **optionPrice** = 45,50 **itemPrice** = 25,00 + 45,50 = 70,50 enum: - SUM - MAX - AVG default: SUM options: type: array description: 'A list of `Option` entities that correspond to this option group' items: type: 'object' description: 'options' allOf: - $ref: '#/components/schemas/Option' Option: type: 'object' title: 'Option' required: [id] properties: id: type: 'string' format: 'uuid' description: 'A unique identifier of the option.' example: 'e5232f14-430c-4a94-8ff6-289d5a16a87a' itemId: type: 'string' description: 'The id value of the `Item` entity correlated to this `Option` entity.' example: '502ecf11-0509-48ed-b63c-6211c48fd9b9' index: type: integer description: 'Option display index.' example: 0 status: type: 'string' description: "Indicates if the entity is Avaliable or Unavaliable. Only use this type when you must disable the entity due to an unexpected event and you don't know when the service will be re-established (e.g. do not use for holidays). Default is `AVAILABLE`." enum: - AVAILABLE - UNAVAILABLE default: AVAILABLE example: 'AVAILABLE' price: type: 'object' description: 'Price of the option. Original and actual values can be informed, for showing discounts.' allOf: - $ref: '#/components/schemas/ItemPrice' maxPermitted: type: integer description: 'The maximum quantity of this option which can be selected in the option group.' example: 1 Availability: type: 'object' title: 'Availability' required: [id, 'hours'] properties: id: type: 'string' format: 'uuid' description: 'A unique identifier of the availability.' example: '11d063c4-73a7-4f87-a0eb-71636cc02029' startDate: type: 'string' description: 'Availability start date. If not informed, the availabilty is already avaliable.' example: '2021-05-27' endDate: type: 'string' description: 'Availability end date. If not informed, the availabilty is always avaliable.' example: '2021-05-30' hours: type: 'array' description: 'Hours' items: allOf: - $ref: '#/components/schemas/Hours' MerchantStatus: type: 'object' title: 'Merchant Status' required: ['lastRead', 'status'] properties: lastRead: type: 'string' format: 'date-time' description: "Date of last attempt to read merchant information. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." status: type: 'string' description: 'Reading attempt status' enum: - SUCCESS - PROCESSING - FAIL moreInfo: type: 'string' description: 'Open field to provide any relevant information to the caller. Eg: Error messages or causes.' MerchantUpdate: type: object discriminator: propertyName: entityType mapping: MERCHANT: '#/components/schemas/FullMerchantUpdate' BASIC_INFO: '#/components/schemas/BasicInfoUpdate' SERVICE: '#/components/schemas/ServiceUpdate' MENU: '#/components/schemas/MenuUpdate' CATEGORY: '#/components/schemas/CategoryUpdate' ITEM: '#/components/schemas/ItemUpdate' ITEM_OFFER: '#/components/schemas/ItemOfferUpdate' OPTION_GROUP: '#/components/schemas/OptionGroupUpdate' OPTION: '#/components/schemas/OptionUpdate' AVAILABILITY: '#/components/schemas/AvailabilityUpdate' properties: merchantStatus: type: 'string' description: "Indicates if the Merchant is Avaliable or Unavaliable. Only use this type when you must close (disable) the merchant due to an unexpected event and you don't know when the service will be re-established (e.g. do not use for holidays)." enum: - AVAILABLE - UNAVAILABLE example: 'AVAILABLE' entityType: type: 'string' description: 'The entity type of the updated object.' FullMerchantUpdate: description: Updated Merchant Object allOf: - $ref: '#/components/schemas/MerchantUpdate' - type: object properties: updatedObjects: description: 'Updated `Merchant` entity objects' type: array items: allOf: - $ref: '#/components/schemas/UpdateMerchant' BasicInfoUpdate: description: Updated Service Object allOf: - $ref: '#/components/schemas/MerchantUpdate' - type: object properties: updatedObjects: description: 'Updated `Service` entity objects' type: array items: allOf: - $ref: '#/components/schemas/BasicInfo' ServiceUpdate: description: Updated Service Object allOf: - $ref: '#/components/schemas/MerchantUpdate' - type: object properties: updatedObjects: description: 'Updated `Service` entity objects' type: array items: allOf: - $ref: '#/components/schemas/Service' MenuUpdate: description: Updated Menu Object allOf: - $ref: '#/components/schemas/MerchantUpdate' - type: object properties: updatedObjects: description: 'Updated `Menu` entity objects' type: array items: allOf: - $ref: '#/components/schemas/Menu' CategoryUpdate: description: Updated `Category` Object allOf: - $ref: '#/components/schemas/MerchantUpdate' - type: object properties: updatedObjects: description: 'Updated `Category` entity objects' type: array items: allOf: - $ref: '#/components/schemas/Category' ItemUpdate: description: Updated `Item` Object allOf: - $ref: '#/components/schemas/MerchantUpdate' - type: object properties: updatedObjects: description: 'Updated `Item` entity objects' type: array items: allOf: - $ref: '#/components/schemas/Item' ItemOfferUpdate: description: Updated `ItemOffer` Object allOf: - $ref: '#/components/schemas/MerchantUpdate' - type: object properties: updatedObjects: description: 'Updated `ItemOffer` entity objects' type: array items: allOf: - $ref: '#/components/schemas/ItemOffer' OptionGroupUpdate: description: Updated `OptionGroup` Object allOf: - $ref: '#/components/schemas/MerchantUpdate' - type: object properties: updatedObjects: description: 'Updated `OptionGroup` entity objects' type: array items: allOf: - $ref: '#/components/schemas/OptionGroup' OptionUpdate: description: Updated `Option` Object allOf: - $ref: '#/components/schemas/MerchantUpdate' - type: object properties: updatedObjects: description: 'Updated `Option` entity objects' type: array items: allOf: - $ref: '#/components/schemas/Option' AvailabilityUpdate: description: Updated `Availability` Object allOf: - $ref: '#/components/schemas/MerchantUpdate' - type: object properties: updatedObjects: description: 'Updated `Availability` entity objects' type: array items: allOf: - $ref: '#/components/schemas/Availability' #Orders AckEvents: type: 'object' title: 'Ack Events' required: [id, 'orderId', 'eventType'] properties: id: type: 'string' format: 'uuid' description: 'A unique identifier of the event.' orderId: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' eventType: type: 'string' description: 'The event type. **[Click here](#operation/pollingEvents)** for definitions of each type.' enum: - 'CREATED' - 'CONFIRMED' - 'PREPARATION_REQUESTED' - 'PREPARING' - 'DISPATCHED' - 'READY_FOR_PICKUP' - 'PICKUP_AREA_ASSIGNED' - 'PICKED_UP' - 'DELIVERED' - 'CONCLUDED' - 'CANCELLATION_REQUESTED' - 'CANCELLATION_REQUEST_DENIED' - 'CANCELLED' - 'ORDER_CANCELLATION_REQUEST' - 'CANCELLED_DENIED' Order: type: 'object' title: 'Order' required: [ id, 'type', 'displayId', 'createdAt', 'orderTiming', 'preparationStartDateTime', 'merchant', 'items', 'total', 'payments' ] properties: id: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' 'type': type: 'string' description: |- `DELIVERY` - for orders that will be delivered to the customer's address. `TAKEOUT` - orders that will be picked up at the establishment by the customer `INDOOR` - orders that will be consumed inside the establishment. enum: - 'DELIVERY' - 'TAKEOUT' - 'INDOOR' displayId: type: 'string' description: 'Order Id shown in the **Ordering Application** interface for the customer.' sourceAppId: type: 'string' format: uuid description: 'This field must be filled in with the AppId of the **Ordering Application** that originated the order. This field is to help the applications that will work as a Hub, intermediating the requests from the **Ordering Application** with the **Software Service**.' salesChannel: type: 'string' description: 'You can indicate through which sales channel this order originated.' virtualBrand: type: 'string' description: 'This field can be used as an alternative id for the merchant, in cases where the same merchant has different identifications or brands (such as dark kitchens). It is important to note that the Ordering Application or Software Hub must know this Id beforehand.' category: type: string description: |- Indicates the order category. > If you find that your order category does not fit any of the listed categories, please open an issue so it can be added. enum: - FOOD - GROCERY - DRUGSTORE - PETSTORE default: FOOD createdAt: type: 'string' format: date-time description: "Order creation date and time. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info.)." lastEvent: type: 'string' description: 'The last valid event polled (whether acknowledged or not) or sent via webhook. **[Click here](#operation/pollingEvents)** for definitions of each type.' enum: - 'CREATED' - 'CONFIRMED' - 'PREPARATION_REQUESTED' - 'PREPARING' - 'DISPATCHED' - 'READY_FOR_PICKUP' - 'PICKUP_AREA_ASSIGNED' - 'PICKED_UP' - 'DELIVERED' - 'CONCLUDED' - 'CANCELLATION_REQUESTED' - 'CANCELLATION_REQUEST_DENIED' - 'CANCELLED' - 'ORDER_CANCELLATION_REQUEST' - 'CANCELLED_DENIED' orderTiming: type: 'string' description: |- Indicates the timing for initiating the order: `INSTANT`: for orders that must be prepared immediately. `SCHEDULED`: for orders scheduled for a specific date and time. It will always be accompanied by the `schedule` object. `ONDEMAND`: for orders that will only be delivered when the consumer indicates that they are going to pick it up. In this case, the **Software Service** will receive a `PREPARATION_REQUESTED` event indicating that the order should be started. enum: - 'INSTANT' - 'SCHEDULED' - 'ONDEMAND' preparationStartDateTime: type: 'string' format: 'date-time' description: "Suggestion for the preparation start time after Order creation. This can be used by the **Ordering Application** to inform the merchant to delay the start of the preparation for any reason. Default is the same time as the order creation time. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." merchant: type: 'object' required: [id, 'name'] description: 'Merchant information.' properties: id: type: 'string' description: |- Unique Identifier. Identifies the merchant in the different systems that the merchant will communicate. This id must be generated by the merchant's **`Software Service`**. > To avoid duplicates between different merchants it is recommended that the software creates the merchantId using: > `Merchant Document + UUID` > If this is not possible, it is recommended to at least use a UUID. minLength: 36 maxLength: 100 example: '22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824' name: type: 'string' description: 'Merchant Public Name' maxLength: 500 example: 'Pizza Plaza' items: type: 'array' description: 'Order items.' items: type: 'object' required: [ id, 'name', 'unit', 'quantity', 'unitPrice', 'totalPrice', 'externalCode', ] properties: id: type: 'string' format: 'uuid' description: 'A unique identifier of the item.' index: type: 'integer' description: "Item's position." name: type: 'string' description: 'Product name' externalCode: type: 'string' description: 'External product code.' unit: type: 'string' description: | Item's Unit of Measurement. Possible values: - `UN` - Unit - `KG` - Kilogram - `L` - Liter - `OZ` - Ounce - `LB` - Pound - `GAL` - Gallon > Use fractional values for quantities smaller than the unit of measure: > Example: 500 grams = 0.5 KG enum: - 'UN' - 'KG' - 'L' - 'OZ' - 'LB' - 'GAL' example: 'KG' ean: type: 'string' description: 'EAN is the barcode standard used on items.' quantity: type: 'number' format: 'decimal' description: |- Amount of items. > Use fractional values for quantities smaller than the unit of measure: > Example: 500 grams = 0.5 KG specialInstructions: type: 'string' description: 'Special instructions about the items.' unitPrice: type: 'object' allOf: - $ref: '#/components/schemas/Price' description: 'Price per unit. This is the price the customer is paying and will be considered for order totals calculations.' originalPrice: type: 'object' allOf: - $ref: '#/components/schemas/Price' description: |- Original price of the product. This price **is for information purposes only** and should be used to inform the price of an item before applying markdowns on the list price. Discounts applied during the order such as coupons and vouchers should not be considered here. These must be reported in the `discounts` object. **THIS PRICE WILL NOT BE CONSIDERED FOR ORDER TOTALS CALCULATIONS.** scalePriceApplied: type: 'boolean' description: "Indicates whether or not the unit price of the item has changed due to a scaled purchase (where the quantity of items purchased changes the value of the item). Default is `false`" default: false optionsPrice: type: 'object' allOf: - $ref: '#/components/schemas/Price' description: 'The sum of the total prices of all options of the item.' subtotalPrice: type: 'object' description: |- This price **is for information purposes only** and should be used to inform the total price for the quantity of items ordered, excluding additional options. **(quantity * unitPrice)** **THIS PRICE WILL NOT BE CONSIDERED FOR ORDER TOTALS CALCULATIONS.** allOf: - $ref: '#/components/schemas/Price' totalPrice: type: 'object' description: Total Price of the item. **(quantity * (unitPrice + optionsPrice))** allOf: - $ref: '#/components/schemas/Price' indoor: type: object description: "Item-related properties for when the order is of type `INDOOR`" properties: productionPoint: type: 'string' description: |- Production point for this specific item. It should be used when the merchant has more than one production point and it is necessary to carry out production at a specific location. Note: The locations must be previously registered in both the **Ordering Application** and the **Software Service**. options: type: 'array' description: 'The optional extras chosen by the consumer, related to this item.' items: type: 'object' required: [ id, 'name', 'externalCode', 'unit', 'quantity', 'unitPrice', 'totalPrice', ] properties: index: type: 'integer' description: "Option's position." id: type: 'string' format: 'uuid' description: 'A unique identifier of the item.' name: type: 'string' description: 'Options name' externalCode: type: 'string' description: 'External product code.' unit: type: 'string' description: | Item's Unit of Measurement. Possible values: - `UN` - Unit - `KG` - Kilogram - `L` - Liter - `OZ` - Ounce - `LB` - Pound - `GAL` - Gallon > Use fractional values for quantities smaller than the unit of measure: > Example: 500 grams = 0.5 KG enum: - 'UN' - 'KG' - 'L' - 'OZ' - 'LB' - 'GAL' example: 'KG' ean: type: 'string' description: 'EAN is the barcode standard used on items.' quantity: type: 'number' format: 'decimal' unitPrice: type: 'object' allOf: - $ref: '#/components/schemas/Price' description: 'Price per unit. This is the price the customer is paying and will be considered for order totals calculations.' originalPrice: type: 'object' allOf: - $ref: '#/components/schemas/Price' description: |- Original price of the option. This price **is for information purposes only** and should be used to inform the price of an option before applying markdowns on the list price. Discounts applied during the order such as coupons and vouchers should not be considered here. These must be reported in the `discounts` object. **THIS PRICE WILL NOT BE CONSIDERED FOR ORDER TOTALS CALCULATIONS.** subtotalPrice: type: 'object' description: |- This price **is for information purposes only** and should be used to inform the total price for the quantity of items ordered, excluding additional options. **(quantity * unitPrice)** **THIS PRICE WILL NOT BE CONSIDERED FOR ORDER TOTALS CALCULATIONS.** allOf: - $ref: '#/components/schemas/Price' totalPrice: type: 'object' description: Total Price of the option. **(quantity * unitPrice)** allOf: - $ref: '#/components/schemas/Price' specialInstructions: type: 'string' description: 'More instructions, if needed.' otherFees: type: 'array' description: 'Other fees that may apply.' items: type: 'object' required: ['name', 'type', 'receivedBy', 'price'] properties: name: type: 'string' description: 'Name related to the other fees.' type: type: 'string' description: |- Type of fee. - `DELIVERY_FEE`: Fee charged for delivering the order to the customer's address. - `SERVICE_FEE`: Fee charged for the service provided by the 'Ordering Application' platform or merchant. - `TIP`: Gratuity amount given to the delivery person or service staff. - `MIN_ORDER_FEE`: Additional fee charged when the order value is below the minimum required amount. enum: - 'DELIVERY_FEE' - 'SERVICE_FEE' - 'TIP' - 'MIN_ORDER_FEE' receivedBy: type: 'string' description: |- Indicates who is the final recipient of the fee amount. Example: For a delivery fee, if the delivery is performed by the merchant but the consumer paid directly to the Ordering Application, this field should be set as 'MERCHANT' and not 'MARKETPLACE'. enum: enum: - 'MARKETPLACE' - 'MERCHANT' - 'LOGISTIC_SERVICES' receiverDocument: type: 'string' description: 'Mandatory for marketplace.' price: type: 'object' description: 'The fee price' allOf: - $ref: '#/components/schemas/Price' observation: type: 'string' description: 'Any extra comments.' discounts: type: 'array' description: |- Any discounts that may apply. **IMPORTANT: A payment method MUST NOT be used as a discount. Discounts are amounts that subtract a portion of the final order value. To avoid duplication, if a value is declared in this object it MUST NOT be declared in the `payments` object.** items: type: 'object' required: ['amount', 'target', 'sponsorshipValues'] properties: amount: type: 'object' description: Amount value of the discount. allOf: - $ref: '#/components/schemas/Price' target: type: 'string' enum: - 'CART' - 'DELIVERY_FEE' - 'ITEM' targetId: type: 'string' description: 'Only mandatory for `target` = `ITEM`.' sponsorshipValues: description: 'Values sponsored by either party. The sum of the amounts listed in this atribute must match the value informed in the `amount` atribute above.' type: 'array' items: type: 'object' required: ['name', 'amount'] properties: name: type: 'string' enum: - 'MARKETPLACE' - 'MERCHANT' - 'CHAIN' amount: type: 'object' description: Discount amount given by the sponsor. allOf: - $ref: '#/components/schemas/Price' discountCode: type: 'string' description: Code related to the discount applied. Here you can enter a coupon used by the user, or an identification code from a marketing campaign, for example. total: type: 'object' required: ['itemsPrice', 'otherFees', 'orderAmount', 'discount'] description: 'Set of fields with the sum of the values previously described in the order.' properties: itemsPrice: type: 'object' description: 'Sum of the total price of the items listed in the `items` attribute.' allOf: - $ref: '#/components/schemas/Price' otherFees: type: 'object' description: "Sum of the total value of other fees listed in the `otherFees` attribute. If there isn't one, use 0." allOf: - $ref: '#/components/schemas/Price' discount: type: 'object' description: "Sum of any discounts that may be listed in the `discounts` attribute. If there isn't one, use 0." allOf: - $ref: '#/components/schemas/Price' orderAmount: type: 'object' description: 'The final value of the order (itemsPrice + otherFees - discounts). ' allOf: - $ref: '#/components/schemas/Price' payments: type: 'object' required: ['prepaid', 'pending', 'methods'] description: |- All the description of the payment, such as methods, pre-payments, change, etc. **IMPORTANT: A discount MUST NOT be used as a payment method. It is important that the sum of all values declared as payment methods is exactly equal to `total.orderAmount`. To avoid duplication, do not declare a payment method as a discount as well.** properties: prepaid: type: 'number' format: 'decimal' description: 'Amount paid in advance.' pending: type: 'number' format: 'decimal' description: 'Amount that is still to be paid.' methods: type: 'array' description: 'The payment method used. Whether it was online, on delivery, credit card, voucher, cash, etc.' items: type: 'object' required: ['value', 'currency', 'type', 'method'] properties: value: type: 'number' format: 'decimal' description: 'Price value. 4 decimals places are accepted' currency: type: 'string' pattern: '^[A-Z]{3}$' description: 'The 3-letter ISO 4217 currency code.' example: 'BRL' type: type: 'string' description: '`PREPAID` if the payment was made through some platform, or `PENDING` if it going to be paid on delivery or in cash, for example.' enum: - 'PREPAID' - 'PENDING' method: type: 'string' enum: - 'CREDIT' - 'DEBIT' - 'MEAL_VOUCHER' - 'FOOD_VOUCHER' - 'DIGITAL_WALLET' - 'PIX' - 'CASH' - 'CREDIT_DEBIT' - 'COUPON' - 'REDEEM' - 'PREPAID_REDEEM' - 'OTHER' brand: type: string description: |- Indicates the brand of the card selected in the `method` field. This field must only be filled in if `method` is `CREDIT`, `DEBIT`, `CREDIT_DEBIT`, `MEAL_VOUCHER` or `FOOD_VOUCHER`. If `OTHER` is chosen, it is recommended that you describe the brand name in the `methodInfo` field. enum: - 'VISA' - 'MASTERCARD' - 'DINERS' - 'AMEX' - 'HIPERCARD' - 'ELO' - 'AURA' - 'DISCOVER' - 'VR_BENEFICIOS' - 'SODEXO' - 'TICKET' - 'GOOD_CARD' - 'BANESCARD' - 'SOROCARD' - 'POLICARD' - 'VALECARD' - 'AGICARD' - 'JCB' - 'CREDSYSTEM' - 'CABAL' - 'GREEN_CARD' - 'VEROCHEQUE' - 'AVISTA' - 'OTHER' methodInfo: type: 'string' description: |- Additional information regarding the payment method. It can be used to indicate some useful information of the chosen payment method, such as the name of the wallet, or an authorization number. This field can be used for any `method` entered, but it is highly recommended to fill it in when the chosen `method` is `OTHER`. transaction: type: object description: "Authorization details and intermediary identification for credit card and/or subsidy transactions" properties: authorizationCode: type: string description: "Credit card and/or subsidy transaction authorization number." acquirerDocument: type: string description: "Document of the Transaction Intermediary (agency, delivery platform, marketplace, and similar) of services and businesses." changeFor: type: 'number' format: 'decimal' description: |- Indicates the total that will be paid in cash by the customer and that should be considered for the calculation of the change (ex. customer will pay a $43 order with a $50 bill. Then 50.00 must be entered.). Only mandatory when `method` is `CASH`. taxInvoice: type: 'object' description: 'Tax Invoice information.' properties: issued: type: 'boolean' description: 'Inform if a tax invoice has already been issued for this order.' default: false taxInvoiceURL: type: 'string' description: 'The address to download the tax invoice issued.' customer: type: 'object' required: [id, 'phone', 'name', 'ordersCountOnMerchant'] description: "Customer related information. \n\n**REQUIRED** if the chosen `type` is `DELIVERY`" properties: id: type: 'string' format: 'uuid' description: 'A unique identifier related to the consumer. If the Ordering Application does not have an Id for the customer, this Id can be generated when creating the order. ' name: type: 'string' description: "Customer's name." documentNumber: description: 'Customer document. This document may be sent for dealing with tax issues.' type: 'string' phone: type: 'object' description: |- Customer's phone. Here you can enter the customer's phone number directly (provided that the customer has given permission for this data to be shared, according to local policies) or another phone number (such as the ordering application's call center phone number) where the merchant can communicate about order issues that affect the customer (such as health issues). **Please note**: The telephone number is considered an identification field and therefore the customer's advance consent is required. required: ['number'] properties: number: type: 'string' extension: type: 'string' email: description: 'Customer email. This document may be sent for dealing with tax issues.' type: 'string' ordersCountOnMerchant: description: 'Total number of orders that the customer already placed within the merchant.' type: 'number' format: 'decimal' schedule: type: 'object' description: "Information for scheduled orders. \n\n**REQUIRED** if `orderTiming` is `SCHEDULED`." required: ['scheduledDateTimeStart', 'scheduledDateTimeEnd'] properties: scheduledDateTimeStart: type: 'string' format: date-time description: "Date and time for when the order is ready. It can be calculated by the **Ordering Application** using the average preparation time of the dishes. Default is the same time as order creation time. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." scheduledDateTimeEnd: type: 'string' format: date-time description: "Date and time for when the order is ready. It can be calculated by the **Ordering Application** using the average preparation time of the dishes. Default is the same time as order creation time. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." orderPriority: type: 'string' description: |- Defines the priority of preparation and delivery of this order in relation to other orders from the same **Ordering Application**. The lower the priority, the faster this order should be fulfilled. **Note:** This field depends on both the Ordering Application and the Merchant being able to support this functionality. enum: - 'PRIORITY1' - 'PRIORITY2' - 'PRIORITY3' - 'PRIORITY4' - 'PRIORITY5' delivery: type: 'object' description: "Information for DELIVERY orders. \n\n**REQUIRED** if the chosen `type` is `DELIVERY`" required: ['deliveredBy', 'deliveryAddress', 'estimatedDeliveryDateTime'] properties: deliveredBy: type: 'string' enum: - 'MERCHANT' - 'MARKETPLACE' deliveryAddress: type: 'object' description: 'The address to which the order will be delivered.' required: [ 'country', 'street', 'formattedAddress', 'number', 'city', 'postalCode', 'coordinates', 'district', 'state', ] properties: country: type: 'string' pattern: '^[A-Z]{2}$' description: 'Two-letter [ISO 3166-1 alpha-2](https://www.iso.org/standard/72482.html) country code.' example: 'BR' state: type: 'string' description: 'State or country subdivision. It is recommended (but not required) that you use the [ISO 3166-2](https://www.iso.org/standard/72483.html) representation. ' example: 'BR-SP' city: type: 'string' description: 'City name.' example: 'São Paulo' district: type: 'string' description: 'Neighborhood or District.' example: 'Moema' street: type: 'string' description: 'Street name.' example: 'Plaza Avenue' number: type: 'string' description: 'Street number.' example: '100' complement: type: 'string' description: 'Address complement.' example: 'BL 02 AP 31' reference: type: 'string' description: 'Address reference.' example: 'Yellow House' formattedAddress: type: 'string' description: 'Full Formated Address Text' example: 'Plaza Avenue, 100, BL 02 AP 31, Moema - São Paulo, SP - Brazil' postalCode: type: 'string' description: 'Postal Code' example: '20111-000' coordinates: type: 'object' required: ['latitude', 'longitude'] properties: latitude: type: 'number' format: 'float' description: "Latitude in degrees. Values are restricted to the range [[-90, 90]]." example: -23.54823 longitude: type: 'number' format: 'float' description: "Longitude in degrees. Values are restricted to the range [[-180, 180]]." example: -46.63632 estimatedDeliveryDateTime: type: 'string' format: date-time description: "Estimated delivery date and time. The same date showed to the customer, in the **Ordering Application** interface. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." deliveryDateTime: type: 'string' format: date-time description: "Delivery date. The date time that the delivery actually took place. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." pickupCode: type: 'string' description: |- It gives the Merchant a code so that the **delivery man** can collect the order. Note: Not to be confused with the customer's delivery code. takeout: type: 'object' description: "Information for TAKEOUT orders. \n\n**REQUIRED** if the chosen `type` is `TAKEOUT`" required: ['mode', 'takeoutDateTime'] properties: mode: type: 'string' enum: - 'DEFAULT' - 'PICKUP_AREA' takeoutDateTime: type: 'string' format: date-time description: "Takeout date and time. It can be calculated by the **Ordering Application** using the average preparation time of the dishes. Default is the same time as order creation time. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." billingAddress: type: 'object' description: "Customer billing address. Required by fiscal regulation (Ajuste SINIEF nº 9/2026) for TAKEOUT orders to enable NFC-e issuance. For DELIVERY orders, the delivery address serves as billing address. This field is NOT required." properties: country: type: 'string' pattern: '^[A-Z]{2}$' description: 'Two-letter ISO 3166-1 alpha-2 country code.' example: 'BR' state: type: 'string' description: 'State or country subdivision.' example: 'BR-SP' city: type: 'string' description: 'City name.' example: 'São Paulo' district: type: 'string' description: 'District or Neighborhood name.' example: 'Moema' street: type: 'string' description: 'Street Name.' example: 'Plaza Avenue' number: type: 'string' description: 'Street Number.' example: '100' postalCode: type: 'string' description: 'Postal Code' example: '20111-000' complement: type: 'string' description: 'Address complement.' example: 'BL 02 AP 31' indoor: type: 'object' description: "Information for INDOOR orders. \n\n**REQUIRED** if the chosen `type` is `INDOOR`" required: ['mode', 'indoorDateTime'] properties: mode: type: 'string' description: |- Indoor mode identifier: - `DEFAULT`: Used for orders placed in the **Ordering Application** to be consumed inside the merchant without a specific location. - `PLACE`: Used for orders placed in the **Ordering Application** to be consumed inside the merchant at a specific location already specified, such as a **table** or a **counter**. - `TAB`: Used for establishments that control orders via **tabs** or **control cards** (can be used in conjunction with the place field). - `TERMINAL`: Used for orders placed through self-services, such as kiosks, totems or tablets. enum: - 'DEFAULT' - 'PLACE' - 'TAB' - 'TERMINAL' indoorDateTime: type: 'string' format: date-time description: "Date and time for when the order is ready. It can be calculated by the **Ordering Application** using the average preparation time of the dishes. Default is the same time as order creation time. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." place: type: 'string' description: 'The place identifier (Required if mode is `PLACE`)' tab: type: 'string' description: 'The tab or control card identifier (Required if mode is `TAB`)' seat: type: 'string' description: 'Optional Identifier of the seat where the customer is located.' waiterCode: type: 'string' description: 'Optional code to identify the waiter responsible for the order.' sendPreparing: type: 'boolean' description: |- This field indicates whether it is necessary for the `Software Service` to make a request to the [POST /v1/orders/{orderId}/preparing](#operation/orderPreparing) endpoint to indicate to the `Ordering Application` that the order is in production. `true`: Indicates that the `Ordering Application` is waiting for a request. `false` or `not informed`: It is not required to make a request. sendDelivered: type: 'boolean' description: |- This field indicates whether it is necessary for the `Software Service` to make a request to the [POST /v1/orders/{orderId}/delivered](#operation/orderDelivered) endpoint to indicate to the `Ordering Application` that the order has been delivered to the client. `true`: Indicates that the `Ordering Application` is waiting for a request. `false` or `not informed`: It is not required to make a request. sendPickedUp: type: 'boolean' description: |- This field indicates whether it is necessary for the `Software Service` to make a request to the [POST /v1/orders/{orderId}/pickedUp](#operation/orderPickedUp) endpoint to indicate to the `Ordering Application` that the order has been picked up by the client. `true`: Indicates that the `Ordering Application` is waiting for a request. `false` or `not informed`: It is not required to make a request. sendTracking: type: 'boolean' description: |- This field indicates whether it is necessary for the `Software Service` to make a request to the [POST /v1/orders/{orderId}/tracking](#operation/orderTracking) endpoint to inform the `Ordering Application` about delivery updates. `true`: Indicates that the `Ordering Application` is waiting for a request. `false` or `not informed`: It is not required to make a request. extraInfo: type: 'string' description: 'Extra information, if necessary.' OrderConfirmed: type: 'object' title: 'Order Confirmed' required: ['createdAt', 'orderExternalCode'] properties: reason: type: 'string' description: 'Free field for more information about the order confirmation, such as which employee accepted the order, for example.' createdAt: type: 'string' format: date-time description: "Order creation date and time. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." orderExternalCode: type: 'string' description: 'External order code, which can be used by merchant or marketplace.' preparationTime: type: 'integer' description: 'Indicates an estimate of the preparation time (in minutes) for the order being confirmed.' RequestCancelled: type: 'object' title: 'Request Cancelattion' required: ['reason', 'code', 'mode'] properties: reason: type: 'string' description: 'Open text field indicating the reason for the cancellation.' code: type: 'string' enum: - SYSTEMIC_ISSUES - DUPLICATE_APPLICATION - UNAVAILABLE_ITEM - RESTAURANT_WITHOUT_DELIVERY_PERSON - OUTDATED_MENU - ORDER_OUTSIDE_THE_DELIVERY_AREA - BLOCKED_CUSTOMER - OUTSIDE_DELIVERY_HOURS - INTERNAL_DIFFICULTIES_OF_THE_RESTAURANT - RISK_AREA - DELIVERY_PROBLEM mode: type: 'string' description: 'Indicates whether the cancellation request was made by an automatic or manual process in the Software Service' enum: - 'AUTO' - 'MANUAL' outOfStockItems: type: 'array' description: "Items that are not in the merchant's inventory." items: format: uuid type: string maxItems: 100 invalidItems: type: 'array' description: "Items that do not exist in the merchant's inventory." items: format: 'uuid' type: string maxItems: 100 RequestDenied: type: 'object' title: 'Request Cancelled' required: ['reason', 'code'] properties: reason: type: 'string' description: 'Open text field indicating the reason for the cancellation.' code: type: 'string' enum: - 'DISH_ALREADY_DONE' - 'OUT_FOR_DELIVERY' Event: type: 'object' title: 'Event' required: ['eventId', 'eventType', 'orderId', 'orderURL', 'createdAt'] discriminator: propertyName: eventType mapping: CREATED: '#/components/schemas/EventMetadata' CONFIRMED: '#/components/schemas/EventMetadataConfirm' PREPARATION_REQUESTED: '#/components/schemas/EventMetadata' PREPARING: '#/components/schemas/EventMetadata' READY_FOR_PICKUP: '#/components/schemas/EventMetadata' DISPATCHED: '#/components/schemas/EventMetadata' PICKUP_AREA_ASSIGNED: '#/components/schemas/EventMetadataPickup' PICKED_UP: '#/components/schemas/EventMetadata' DELIVERED: '#/components/schemas/EventMetadata' CONCLUDED: '#/components/schemas/EventMetadata' ORDER_CANCELLATION_REQUEST: '#/components/schemas/EventMetadataCancel' CANCELLATION_REQUESTED: '#/components/schemas/EventMetadataCancel' CANCELLATION_REQUEST_DENIED: '#/components/schemas/EventMetadataCancel' CANCELLED: '#/components/schemas/EventMetadataCancel' CANCELLED_DENIED: '#/components/schemas/EventMetadataCancel' properties: eventId: type: 'string' format: 'uuid' description: 'A unique identifier of the event.' eventType: type: 'string' description: 'The event type. **[Click here](#operation/pollingEvents)** for definitions of each type.' enum: - 'CREATED' - 'CONFIRMED' - 'PREPARATION_REQUESTED' - 'PREPARING' - 'DISPATCHED' - 'READY_FOR_PICKUP' - 'PICKUP_AREA_ASSIGNED' - 'PICKED_UP' - 'DELIVERED' - 'CONCLUDED' - 'CANCELLATION_REQUESTED' - 'CANCELLATION_REQUEST_DENIED' - 'CANCELLED' - 'ORDER_CANCELLATION_REQUEST' - 'CANCELLED_DENIED' orderId: type: 'string' format: 'uuid' description: 'The unique identifier of the order. The order ID is generated by the **Ordering Application**.' orderURL: type: 'string' format: 'uri' description: 'The URL to get the order details' createdAt: type: 'string' format: date-time description: "Order creation date and time. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." sourceAppId: type: 'string' format: uuid description: 'This field must be filled in with the AppId of the **Ordering Application** that originated the order. This field is to help the applications that will work as a Hub, intermediating the requests from the **Ordering Application** with the **Software Service**.' virtualBrand: type: 'string' description: 'This field can be used as an alternative id for the merchant, in cases where the same merchant has different identifications or brands (such as dark kitchens). It is important to note that the Ordering Application or Software Hub must know this Id beforehand.' EventMetadataCancel: description: Metadata required: ['metadata'] allOf: - $ref: '#/components/schemas/Event' - type: object - properties: metadata: required: ['reason', 'code'] type: object description: 'Information related to the Event Type' properties: reason: type: 'string' description: 'Reason for the cancellation' code: type: 'string' description: 'Cancelation reason code' enum: - SYSTEMIC_ISSUES - DUPLICATE_APPLICATION - UNAVAILABLE_ITEM - RESTAURANT_WITHOUT_DELIVERY_PERSON - OUTDATED_MENU - ORDER_OUTSIDE_THE_DELIVERY_AREA - BLOCKED_CUSTOMER - OUTSIDE_DELIVERY_HOURS - INTERNAL_DIFFICULTIES_OF_THE_RESTAURANT - RISK_AREA - DELIVERY_PROBLEM - CONSUMER_CANCELLATION_REQUESTED - OTHER_CANCELLATION_REASON clientId: type: 'string' description: 'The ID of the client system that generated the action that resulted in this event (to be used with application with multiple stations).' EventMetadata: description: Metadata allOf: - $ref: '#/components/schemas/Event' EventMetadataPickup: description: Metadata allOf: - $ref: '#/components/schemas/Event' - type: object - properties: metadata: type: object description: 'Information related to the Event Type' required: ['pickupArea'] properties: pickupArea: type: 'string' description: 'Information about the pickup area that the merchant needs to deliver the order. Eg: Parking Lot Number' EventMetadataConfirm: description: Metadata required: ['metadata'] allOf: - $ref: '#/components/schemas/Event' - type: object - properties: metadata: type: object description: 'Information related to the Event Type' properties: # expectedPreparationStartTime: Removed field. See Issue (https://github.com/Abrasel-Nacional/Open-Delivery-Beta-Test/issues/7) # type: "string" # format: "date-time" # description: "Expected preparation start time after Order Confirmation. This can be used by the **Ordering Application** to inform the merchant to delay the start of the preparation for any reason." clientId: type: 'string' description: 'The ID of the client system that generated the action that resulted in this event (to be used with application with multiple stations)' OrderDispatched: type: 'object' title: 'Order Dispatched' properties: deliveryTrackingInfo: type: 'object' description: 'Information about the person that was assigned to deliver the order.' allOf: - $ref: '#/components/schemas/DeliveryTrackingInfoDisptach' OrderTracking: type: 'object' title: 'Order Tracking' required: - "deliveryTrackingInfo" properties: deliveryTrackingInfo: type: 'object' description: 'Information about the person that was assigned to deliver the order.' allOf: - $ref: '#/components/schemas/DeliveryTrackingInfo' DeliveryTrackingInfoDisptach: description: Delivery Tracking Info type: object properties: event: description: "The delivery last known event." type: object required: [type, datetime] properties: type: type: string description: "The current delivery event." enum: - DELIVERY_ONGOING - ARRIVED_AT_CUSTOMER - ORDER_DELIVERED - CANCELLED message: type: string description: "Free message. It should be used to provide more detailed information." datetime: type: string format: date-time description: "Date and time when the event ocurred. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." problem: description: 'In the event of a delivery problem, it states the last known reason.' type: object required: [reason, datetime] properties: reason: type: string description: "Problem reason." enum: - DELIVERYPERSON_OCCURRENCE - PAYMENT_PROBLEMS - WRONG_PRODUCT_OR_ITEM - ORDER_DELAYED - ORDER_DAMAGED_OR_VIOLATED - CUSTOMER_DID_NOT_PLACE_ORDER - CUSTOMER_ADDRESS_UNKNOWN - ORDER_MISSING_ITEMS - NOBODY_TO_RECEIVE - DELIVERYPERSON_WAITING_PAYMENT_FOR_ALREADY_PAID_ORDER - ORDER_DELIVERED_WITHOUT_PAYMENT - FRAUD_OR_THEFT message: type: string description: "Free message. It should be used to provide more detailed information." datetime: type: string format: date-time description: "Date and time when the problem ocurred. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." vehicle: description: "The vehicle that will be used for this delivery." type: object required: [type] properties: type: type: "array" description: "Vehicle Type" items: type: string enum: - "MOTORBIKE_BAG" - "MOTORBIKE_BOX" - "CAR" - "BICYCLE" - "SCOOTER" - "VUC" maxItems: 10 licencePlate: type: "string" description: "Licence plate of the vehicle user for the delivery." eta: type: object description: Estimate Times of Pickup and Delivery. properties: deliveryEtaInMinutes: type: integer description: "Delivery Eta in **minutes**. Informs how many minutes it will take the delivery person to arrive at the consumer's address for order delivery." deliveryEtaDatetime: type: string format: date-time description: "Delivery Eta Datetime. Informs the date and time the delivery person is expected to arrive at the consumer's address for order delivery. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." maxDeliveryTime: type: string format: date-time description: "Maximum Date and Time for delivery. This time should not exceed the delivery time limit given in the order request. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." deliveryPerson: type: 'object' description: 'Information about the person taht was assigned to deliver the order.' properties: id: type: string description: "Delivery Person Id given by the `Ordering Application`." name: type: string description: "Delivery Person Name." pictureURL: type: string format: "URI" description: "URL to access the photo of the delivery person. Before entering this field, check that the parties allow data to be shared according to data disclosure laws and rules." externalTrackingURL: type: string format: "URI" description: "External URL, provided by the logistics service to track the delivery on a specific page. Example: Real-time map view, or delivery timeline." DeliveryTrackingInfo: description: Delivery Tracking Info Updates type: object properties: event: description: "The delivery last known event." type: object required: [type, datetime] properties: type: type: string description: "The current delivery event." enum: - PICKUP_ONGOING - ARRIVED_AT_MERCHANT - ORDER_PICKED - DELIVERY_ONGOING - ARRIVED_AT_CUSTOMER - ORDER_DELIVERED - CANCELLED message: type: string description: "Free message. It should be used to provide more detailed information." datetime: type: string format: date-time description: "Date and time when the event ocurred. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." problem: description: 'In the event of a delivery problem, it states the last known reason.' type: object required: [reason, datetime] properties: reason: type: string description: "Problem reason." enum: - DELIVERYPERSON_OCCURRENCE - PAYMENT_PROBLEMS - WRONG_PRODUCT_OR_ITEM - ORDER_DELAYED - ORDER_DAMAGED_OR_VIOLATED - CUSTOMER_DID_NOT_PLACE_ORDER - CUSTOMER_ADDRESS_UNKNOWN - ORDER_MISSING_ITEMS - NOBODY_TO_RECEIVE - DELIVERYPERSON_WAITING_PAYMENT_FOR_ALREADY_PAID_ORDER - ORDER_DELIVERED_WITHOUT_PAYMENT - FRAUD_OR_THEFT message: type: string description: "Free message. It should be used to provide more detailed information." datetime: type: string format: date-time description: "Date and time when the problem ocurred. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." vehicle: description: "The vehicle that will be used for this delivery." type: object required: [type] properties: type: type: "array" description: "Vehicle Type" items: type: string enum: - "MOTORBIKE_BAG" - "MOTORBIKE_BOX" - "CAR" - "BICYCLE" - "SCOOTER" - "VUC" maxItems: 10 licencePlate: type: "string" description: "Licence plate of the vehicle user for the delivery." eta: type: object description: Estimate Times of Pickup and Delivery. properties: pickupEtaInMinutes: type: integer description: "Pickup Eta in **minutes**. Informs how many minutes it will take the delivery person to arrive at the merchant for order pickup." pickupEtaDatetime: type: string format: date-time description: "Pickup Eta Datetime. Informs the date and time the delivery person is expected to arrive at the merchant for order pickup. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." deliveryEtaInMinutes: type: integer description: "Delivery Eta in **minutes**. Informs how many minutes it will take the delivery person to arrive at the consumer's address for order delivery." deliveryEtaDatetime: type: string format: date-time description: "Delivery Eta Datetime. Informs the date and time the delivery person is expected to arrive at the consumer's address for order delivery. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." maxDeliveryTime: type: string format: date-time description: "Maximum Date and Time for delivery. This time should not exceed the delivery time limit given in the order request. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." deliveryPerson: type: 'object' description: 'Information about the person taht was assigned to deliver the order.' properties: id: type: string description: "Delivery Person Id given by the `Ordering Application`." name: type: string description: "Delivery Person Name." pictureURL: type: string format: "URI" description: "URL to access the photo of the delivery person. Before entering this field, check that the parties allow data to be shared according to data disclosure laws and rules." geoLocalization: description: "Geo Localization Info." type: object properties: latitude: type: "number" format: "float" description: "Indicates the latitude coordinate of the actual position of the delivery person.\n\n\n\nLatitude in degrees. Values are restricted to the range [[-90, 90]]." example: -23.54809 longitude: type: "number" format: "float" description: "Indicates the longitude coordinate of the actual position of the delivery person.\n\n\n\nLongitude in degrees. Values are restricted to the range [[-180, 180]]." example: -46.63638 lastAddress: description: The last known address that the delivery person was when the event was sent. type: object required: [distanceToPickup, distanceToDelivery, timestamp] properties: "country": type: "string" pattern: "^[A-Z]{2}$" description: "Two-letter [ISO 3166-1 alpha-2](https://www.iso.org/standard/72482.html) country code." example: "BR" state: type: "string" description: "State or country subdivision. It is recommended (but not required) that you use the [ISO 3166-2](https://www.iso.org/standard/72483.html) representation. " example: "BR-SP" "city": type: "string" description: "City name." example: "São Paulo" "district": type: "string" description: "District or Neighborhood name." example: "Moema" "street": type: "string" description: "Street Name." example: "Plaza Avenue" "postalCode": type: "string" description: "Postal Code." example: "20111-000" distanceToPickup: type: string description: "Distance To Pickup in **meters**." distanceToDelivery: type: string description: "Distance To Delivery in **meters**." timestamp: type: string format: date-time description: "Date and time when this information is valid. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." externalTrackingURL: type: string format: "URI" description: "External URL, provided by the logistics service to track the delivery on a specific page. Example: Real-time map view, or delivery timeline." #Common Address: type: 'object' title: 'Address' required: [ 'country', 'state', 'city', 'district', 'street', 'number', 'postalCode', 'complement', 'latitude', 'longitude', ] properties: 'country': type: 'string' pattern: '^[A-Z]{2}$' description: 'Two-letter [ISO 3166-1 alpha-2](https://www.iso.org/standard/72482.html) country code.' example: 'BR' state: type: 'string' description: 'State or country subdivision. It is recommended (but not required) that you use the [ISO 3166-2](https://www.iso.org/standard/72483.html) representation. ' example: 'BR-SP' 'city': type: 'string' description: 'City name.' example: 'São Paulo' 'district': type: 'string' description: 'District or Neighborhood name.' example: 'Moema' 'street': type: 'string' description: 'Street Name.' example: 'Plaza Avenue' 'number': type: 'string' description: 'Street Number.' example: '100' 'postalCode': type: 'string' description: 'Postal Code' example: '20111-000' 'complement': type: 'string' description: 'Address complement.' example: 'BL 02 AP 31' 'reference': type: 'string' description: 'Address reference.' example: 'Yellow House' 'latitude': type: 'number' format: 'float' description: "Latitude in degrees. Values are restricted to the range [[-90, 90]]." example: -23.54809 'longitude': type: 'number' format: 'float' description: "Longitude in degrees. Values are restricted to the range [[-180, 180]]." example: -46.63638 AddressLogistics: type: 'object' title: 'Address' required: [ 'country', 'state', 'city', 'district', 'street', 'number', 'postalCode', 'complement', ] properties: 'country': type: 'string' pattern: '^[A-Z]{2}$' description: 'Two-letter [ISO 3166-1 alpha-2](https://www.iso.org/standard/72482.html) country code.' example: 'BR' state: type: 'string' description: 'State or country subdivision. It is recommended (but not required) that you use the [ISO 3166-2](https://www.iso.org/standard/72483.html) representation. ' example: 'BR-SP' 'city': type: 'string' description: 'City name.' example: 'São Paulo' 'district': type: 'string' description: 'District or Neighborhood name.' example: 'Moema' 'street': type: 'string' description: 'Street Name.' example: 'Plaza Avenue' 'number': type: 'string' description: 'Street Number.' example: '100' 'postalCode': type: 'string' description: 'Postal Code' example: '20111-000' 'complement': type: 'string' description: 'Address complement.' example: 'BL 02 AP 31' 'reference': type: 'string' description: 'Address reference.' example: 'Yellow House' 'latitude': type: 'number' format: 'float' description: "Latitude in degrees. Values are restricted to the range [[-90, 90]]." example: -23.54809 'longitude': type: 'number' format: 'float' description: "Longitude in degrees. Values are restricted to the range [[-180, 180]]." example: -46.63638 ContactPhones: type: 'object' title: 'Contact Phones' required: ['commercialNumber'] properties: 'commercialNumber': type: 'string' description: 'Telephone number of the merchant' example: '11999999999' 'whatsappNumber': type: 'string' description: 'Whatsapp number of the merchant' example: '11998888888' Price: type: 'object' title: 'Price' required: ['value', 'currency'] properties: value: type: 'number' format: 'decimal' description: 'Price value. 4 decimals places are accepted' example: 40 currency: type: 'string' pattern: '^[A-Z]{3}$' description: 'The 3-letter ISO 4217 currency code.' example: 'BRL' # Repository: # type: 'object' # title: 'Repository' # required: # [ # 'document', # 'corporateName', # 'postalCode', # 'email', # 'website', # 'baseApiUrl', # 'TTL', # 'hostCompanyDocument', # ] # properties: # document: # type: 'string' # description: 'Company registration document' # pattern: "/^\\d{14}$/" # corporateName: # type: 'string' # description: 'Corporate Name' # maxLength: 500 # postalCode: # type: 'string' # description: 'Postal Code' # email: # type: 'string' # description: 'Contact Email. It is recommended that a contact be made available to deal with specific **Open Delivery** issues.' # website: # type: 'string' # format: 'URL' # description: 'Company Website. It is recommended to have a website (or landing page) with information about how the company works with Open Delivery.' # baseApiUrl: # type: 'string' # format: 'URL' # description: "Base URL of the endpoints with the company's data. It will be used by the indexing system to search the establishments under the responsibility of the menu software (see endpoint) and to search public menus (see endpoint)." # hostCompanyDocument: # type: 'string' # description: '**Software Service** registration document that provides the merchant information.' # pattern: "/^\\d{14}$/" # TTL: # type: 'integer' # description: "Time to Live (in seconds). # \nA new request must be done when the TTL expires." Error: type: object required: ['title', 'status'] properties: title: type: string description: 'Short description of the problem.' example: 'Unexpected error' status: type: integer description: 'HTTP code of the returned status.' example: 500 CancellationError: type: object required: ['title', 'status'] properties: title: type: string description: 'Short description of the problem.' example: 'Unexpected error' status: type: integer description: 'HTTP code of the returned status.' example: 500 cancellationStatus: type: string description: 'Indicates the result of the cancellation request.' enum: - 'CANCELLED' - 'CANCELLATION_REQUEST_DENIED' Image: description: Image Object type: object required: ['URL'] properties: URL: type: 'string' format: 'uri' description: "URL pointing to an image of the merchant logo.\n\n Image requirements: \n - Hosted on a secure connection (SSL). \n - File size must be less than 10MB. \n - Image must be in JPEG, PNG, GIF or WEBP format. \n - Both width and height must be between 320px and 1144px. \n\n > It is expected that the images referenced in the URL are downloaded from the server that is making the request, because the URL may no longer be valid after a period of time." example: 'https://food-company.com/image.jpg' CRC-32: type: string format: 'CRC32' description: 'CRC-32 of the image file. This field can be used to check for changes in the image file.' example: '96b41025' ImageWithType: description: Image Object type: object required: ['URL', 'type'] properties: URL: type: 'string' format: 'uri' description: "URL pointing to an image of the merchant logo.\n\n Image requirements: \n - Hosted on a secure connection (SSL). \n - File size must be less than 10MB. \n - Image must be in JPEG, PNG, GIF or WEBP format. \n\n > It is expected that the images referenced in the URL are downloaded from the server that is making the request, because the URL may no longer be valid after a period of time." example: 'https://food-company.com/image.jpg' CRC-32: type: string format: 'CRC32' description: 'CRC-32 of the image file. This field can be used to check for changes in the image file.' example: '96b41025' type: type: 'string' enum: ['MAIN', 'THUMB'] description: 'The type of the image. The `main` type is generally used for larger images, such as in the item detail, while the `thumb` type is for smaller images, typically used in the menu listing.' MerchantAPIInfo: type: 'object' description: 'Information about the endpoints that are hosted at the **Software Service**.' properties: getMerchantURL: type: object description: "Information about the merchant's **Software Service's** [GET /v1/merchant](#operation/getMerchant) access. This endpoint has the necessary information for the **Ordering Application** to be able to make the merchant's available on their plataform." required: ['baseURL'] properties: baseURL: type: 'string' format: 'uri' description: 'The URL for accessing the endpoint.' apiKey: type: 'string' description: 'The API_KEY for accessing the endpoint (see [AUTHENTICATION](#tag/authentication) section form more information).' ordersWebhookURL: type: string format: 'uri' description: "Information about the merchant's **Software Service's** [POST /v1/orderUpdate](#operation/newEvent) webhook access. This is where the **Ordering Application** will sent the order's events to the **Software Service** as they happen." orderingAppMerchantId: type: string description: 'Internal merchantId of the merchant in the **Ordering Application**' #Logistic DeliveryOrder: description: Delivery Order Object. type: object required: [ orderId, orderDisplayId, merchant, pickupAddress, returnToMerchant, canCombine, deliveryAddress, customerName, vehicle, limitTimes, totalOrderPrice, totalWeight, payments, ] properties: orderId: type: string format: "UUID" description: "The orderId generated by the **`Ordering Application`**." example: "52122852-6626-11ed-9022-0242ac120002" orderDisplayId: type: string description: "Order Id shown in the **`Ordering Application`** interface for the customer." example: "96b41025" merchant: type: "object" required: [id, "name"] description: "Merchant information." properties: id: type: 'string' description: |- Unique Identifier. Identifies the merchant in the different systems that the merchant will communicate. This id must be generated by the merchant's **`Software Service`**. > To avoid duplicates between different merchants it is recommended that the software creates the merchantId using: > `Merchant Document + UUID` > If this is not possible, it is recommended to at least use a UUID. minLength: 36 maxLength: 100 example: '22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824' name: type: 'string' description: 'Merchant Public Name' maxLength: 500 example: 'Pizza Plaza' pickupAddress: description: "Pickup Address." allOf: - $ref: "#/components/schemas/AddressLogistics" - type: object properties: pickupLocation: type: string description: "Pickup Location" parkingSpace: type: boolean description: "Parking Space" instructions: type: string description: "Any instructions that may help the delivery." pickupCode: type: string description: "Pickup code to be provided to the delivery person for order collection at the merchant. This code may have been generated by the 'Ordering Application' or by the 'Software Service'." notifyReadyForPickup: type: boolean description: "Inform whether the **`Logistic Service`** to wait for a notification that the order was ready for been picked up. This notification happens via the endpoint: [POST /logistics/orderPicked/{orderId}](#operation/logisticsReadyForPicked)" notifyPickup: type: boolean description: "Inform whether the **`Logistic Service`** to wait for a notification that the order has actually been picked. This notification happens via the endpoint: [POST /logistics/orderPicked/{orderId}](#operation/logisticsPicked)" notifyConclusion: type: boolean description: "Inform whether the **`Logistic Service`** to wait for a delivery finish notification from the requester, before actually finalizing the delivery in its system. This notification is made via the endpoint: [POST /logistics/finishDelivery/{orderId}](#operation/logisticsFinish)" returnToMerchant: type: boolean description: "Inform whether the delivery person should return to the pickup address after the delivery has been made." canCombine: type: boolean description: "Inform whether the **`Logistic Service`** can combine this order with other orders in the same delivery." confirmationCodeRequired: type: boolean description: " Inform whether the **Logistics Service** needs to validate a Delivery Confirmation Code passed by the customer to complete the delivery." deliveryAddress: description: "Delivery Address" allOf: - $ref: "#/components/schemas/AddressLogistics" - type: object properties: instructions: type: string description: "Instructions" customerName: type: "string" description: "Customer Name." customerPhone: type: "string" description: |- Customer's phone. Here you can enter the customer's phone number directly (provided that the customer has given permission for this data to be shared, according to local policies) or another phone number (such as the ordering application's call center phone number). **Please note**: The telephone number is considered an identification field and therefore the customer's advance consent is required. customerPhoneLocalizer: type: string description: "This propertie should be used as a complementary field to the `customerPhone` field in cases where a generic phone number is provided, such as a call center, and it is necessary to provide some order or customer identification." vehicle: description: "Vehicle Info. informs which vehicle options are to be used for delivery. More than one can be informed, but the logistics service must choose only one of the types of vehicles informed." allOf: - $ref: "#/components/schemas/Vehicle" limitTimes: type: object description: "Limit Times. Informs the maximum pickup and delivery times that must be met by the `Logistics Service`." properties: pickupLimit: type: integer description: "Pickup Limit in **minutes**. It should be used to inform the maximum amount of minutes from the time the request was made to which the order should be collected at the merchant." example: 23 deliveryLimit: type: integer description: "Delivery Limit in **minutes**. It should be used to inform the maximum amount of minutes from the time the request was made to which the order should be delivered at the consumer's address." example: 48 orderCreatedAt: type: string format: date-time description: "The date and time that the Order was created at the **Ordering Application**. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." preparationStartDateTime: type: 'string' format: 'date-time' description: "Estimated time when the order will start being prepared. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." totalOrderPrice: description: "Total order price that was calculated and displayed for the final consumer in the **`Ordering Application`**. This value may already contain taxes and shipping in addition to the value of the items purchased." allOf: - $ref: "#/components/schemas/Price" orderDeliveryFee: description: "This field informs the delivery fee paid by the consumer in the **`Ordering Application`**." allOf: - $ref: "#/components/schemas/Price" totalWeight: type: integer description: "Total packaging weight in **grams**" packageVolume: type: number description: "The cubage of the packaging in **cubic meters (m³)**." packageQuantity: type: integer description: |- Number of packages that will be transported in this order. For example, 2 packages, or 3 boxes. > The unit of measure will not be considered, only the quantity. items: type: 'array' description: 'List of items that are part of the delivery.' items: type: 'object' properties: name: type: 'string' description: 'Product name' quantity: type: 'number' format: 'decimal' description: |- Amount of items. > Use fractional values for quantities smaller than the unit of measure: > Example: 500 grams = 0.5 KG specialInstructions: type: string description: "Free text to describe special instructions that may apply. These instructions can be used to give some special guidance to the delivery person at the time of the pickup or delivery." additionalPricePercentual: type: number format: double description: |- Indicates to the **`Logistic Service`** an additional percentage to the list price that the requester agrees to pay for the delivery. > The delivery request will be refused if the delivery price exceeds this value. Example: List Price = $10 Actual calculated price = $15 Additonal price percentage = **50** In this case, any value informed below 50, would result in the order being rejected. payments: type: object description: "Payments Info. It informs the payment methods chosen by the consumer in the **`Ordering Application`**. This section should be used by the `Logistics Service` to check how much the delivery person should receive from the consumer when delivering the order." properties: method: type: string description: |- OFFLINE - The order will be paid by the consumer at the time the order is received. ONLINE - The order has already been paid through the order application. enum: - OFFLINE - ONLINE wirelessPos: type: boolean description: "Indicates whether the delivery person should take the wireless payment device with him." offlineMethod: type: array description: "If the method is `OFFLINE`, the payment information should be provided." items: type: object description: "" properties: type: type: "string" enum: - "CREDIT" - "DEBIT" - "MEAL_VOUCHER" - "FOOD_VOUCHER" - "PIX" - "CASH" - "CREDIT_DEBIT" - "OTHER" amount: allOf: - $ref: "#/components/schemas/Price" maxItems: 100 change: description: If type is `CASH`, tells how much change will be needed. allOf: - $ref: "#/components/schemas/Price" combinedOrdersIds: type: "array" description: "Combined Orders Ids. Informs the logistics service of the Id of other orders already in progress so that the operator can combine these orders. This combination may or may not be accepted by the logistic service, respecting the contracted policies." items: type: string format: uuid maxItems: 10 sourceAppId: type: "string" format: uuid description: "This field must be filled in with the AppId of the **Ordering Application** that originated the order. This field is to help the applications that will work as a Hub, intermediating the requests from the **Ordering Application** with the **Software Service** and the **Logistics Services**." sourceOrderId: type: "string" format: uuid description: "This field must be filled in with the original OrderId generated by the **Ordering Application**. In most cases this property will have the same value as the `orderId` property, since it is already recommended that the order id created by the **Ordering Application** be sent in the `orderId` property. But if the order id created by the **Ordering Application** is not sent in the `orderId` property then it must be entered in this field." Vehicle: description: Vehicle Object. type: object required: [type, container] properties: type: type: "array" description: "Vehicle Type" items: type: string enum: - "MOTORBIKE_BAG" - "MOTORBIKE_BOX" - "CAR" - "BICYCLE" - "SCOOTER" - "VUC" maxItems: 10 container: type: "string" description: "Vehicle container (bag) type." enum: - "NORMAL" - "THERMIC" containerSize: type: string description: "Vehicle container (bag) size." enum: - "SMALL" - "MEDIUM" - "LARGE" - "EXTRA_LARGE" instruction: type: "string" description: "Free text to describe special instructions that may apply. These instructions can be used to give some special guidance to the delivery person at the time of the pickup or delivery." DeliveryOrderResponse: description: Delivery Order Response Object. type: object required: [deliveryId, event, completion] properties: deliveryId: type: "string" format: "UUID" description: "The delivery Id generated by the **`Logistic Service`**." example: "48ae4d68-6626-11ed-9022-0242ac120002" event: description: "Current event of the order. It is expected to be sent with the value **`PENDING`** at this moment, since the acceptance or rejection of the request will be processed asynchronously." type: string enum: - PENDING - ACCEPTED - REJECTED - PICKUP_ONGOING - ARRIVED_AT_MERCHANT - ORDER_PICKED - DELIVERY_ONGOING - ARRIVED_AT_CUSTOMER - ORDER_DELIVERED - RETURNING_TO_MERCHANT - RETURNED_TO_MERCHANT - DELIVERY_FINISHED - CANCELLED completion: type: "object" description: "Informs the expected date and time for sending the acceptance or refusal of the delivery order." properties: estimate: type: string format: date-time description: "Expected date and time for completion. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." rejectAfter: type: string format: date-time description: "Maximum date and time to wait for the acceptance or refusal of the order. After this time the delivery request should be disregarded and a new request should be made. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." deliveryDetailsURL: type: "string" format: "URI" description: |- It is the URL where the delivery information can be found. It should return the [GET /logistics/delivery/{orderId}](#operation/logisticDetails) route for this order." example: "http://yourApiBaseUrl.com/v1/logistics/delivery/52122852-6626-11ed-9022-0242ac120002" DeliveryOrderEvent: description: Delivery Order Event Object. type: object required: [ deliveryId, orderId, orderDisplayId, merchant, event, customerName ] properties: deliveryId: type: "string" format: "UUID" description: "The delivery ID generated by the `Logistics Service`." example: "48ae4d68-6626-11ed-9022-0242ac120002" orderId: type: "string" format: "uuid" description: "The orderId generated by the **`Ordering Application`**." example: "52122852-6626-11ed-9022-0242ac120002" orderDisplayId: type: string description: "Order Id shown in the **`Ordering Application`** interface for the customer." example: "96b41025" merchant: type: "object" required: [id, "name"] description: "Merchant information." properties: id: type: 'string' description: |- Unique Identifier. Identifies the merchant in the different systems that the merchant will communicate. This id must be generated by the merchant's **`Software Service`**. > To avoid duplicates between different merchants it is recommended that the software creates the merchantId using: > `Merchant Document + UUID` > If this is not possible, it is recommended to at least use a UUID. minLength: 36 maxLength: 100 example: '22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824' name: type: 'string' description: 'Merchant Public Name' maxLength: 500 example: 'Pizza Plaza' event: description: "Current Event Info." allOf: - $ref: "#/components/schemas/DeliveryEvent" problem: type: array description: "List of problems that may occur." items: allOf: - $ref: "#/components/schemas/DeliveryProblem" customerName: type: "string" description: "Customer Name." vehicle: description: |- Chosen Vehicle Info. > This propertie is **REQUIRED** when `event > type` is different from `PENDING`, `REJECTED` and `CANCELLED` allOf: - $ref: "#/components/schemas/ChosenVehicle" deliveryPrice: description: |- Delivery Pricing Info. > This propertie is **REQUIRED** when `event > type` is different from `PENDING`, `REJECTED` and `CANCELLED` allOf: - $ref: "#/components/schemas/DeliveryPrice" eta: description: |- Estimate Times of Pickup and Delivery. > This propertie is **REQUIRED** when `event > type` is different from `PENDING`, `REJECTED` and `CANCELLED` allOf: - $ref: "#/components/schemas/ETA" deliveryPerson: description: |- Delivery Person Info. > This propertie is **REQUIRED** when `event > type` is different from `PENDING`, `REJECTED` and `CANCELLED` allOf: - $ref: "#/components/schemas/DeliveryMan" geoLocalization: description: "Geo Localization Info." allOf: - $ref: "#/components/schemas/GeoLocalization" externalTrackingURL: type: string format: "URI" description: "External URL, provided by the logistics service to track the delivery on a specific page. Example: Real-time map view, or delivery timeline." combinedOrdersIds: type: "array" description: "Combined Orders Ids. Informs which other orders from the same merchant are being carried by the same delivery person, with the same `deliveryId`." items: type: string format: uuid DeliveryEvent: description: Delivery Event Object. type: object required: [type, datetime] properties: type: type: string description: "The current delivery event." enum: - PENDING - ACCEPTED - REJECTED - PICKUP_ONGOING - ARRIVED_AT_MERCHANT - ORDER_PICKED - DELIVERY_ONGOING - ARRIVED_AT_CUSTOMER - ORDER_DELIVERED - RETURNING_TO_MERCHANT - RETURNED_TO_MERCHANT - DELIVERY_FINISHED - CANCELLED message: type: string description: "Free message. It should be used to provide more detailed information." datetime: type: string format: date-time description: "Date and time when the event ocurred. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." rejectionInfo: description: "Rejection Info. It should be informed to provide more information when the event type is `REJECTED`." allOf: - $ref: "#/components/schemas/DeliveryEventDenied" DeliveryEventDenied: description: Delivery Event Denied Object. type: object required: [reason] discriminator: propertyName: reason mapping: PRICE_EXCEEDED: "#/components/schemas/DeliveryEventDeniedPrice" VEHICLE_NOT_AVAILABLE: "#/components/schemas/DeliveryEventDeniedVehicle" NO_DELIVERYPERSON_AVAILABLE: "#/components/schemas/DeliveryEventDeniedNoDeliveryMan" DOES_NOT_MEET_REQUESTED_TIMES: "#/components/schemas/DeliveryEventDeniedEta" REGION_NOT_SERVED: "#/components/schemas/DeliveryEventDenied" INVALID_ADDRESS: "#/components/schemas/DeliveryEventDenied" OTHER: "#/components/schemas/DeliveryEventDenied" properties: reason: type: string description: Rejection reason. enum: - "PRICE_EXCEEDED" - "VEHICLE_NOT_AVAILABLE" - "NO_DELIVERYPERSON_AVAILABLE" - "DOES_NOT_MEET_REQUESTED_TIMES" - "REGION_NOT_SERVED" - "OTHER" DeliveryEventDeniedVehicle: description: Metadata allOf: - $ref: "#/components/schemas/DeliveryEventDenied" - type: object - properties: metadata: type: object description: "Information about vehicles availability at the moment." properties: availableVehicles: type: integer description: "Informs how many vehicles are available at the moment." vehiclesAvailable: description: "List of currently available vehicles." allOf: - $ref: "#/components/schemas/Vehicle" nextAvailableVehicle: type: integer description: "Informs how soon the next vehicle will be available in **minutes**." DeliveryEventDeniedPrice: description: Metadata allOf: - $ref: "#/components/schemas/DeliveryEventDenied" - type: object - properties: metadata: type: object description: "The actual delivery price calculated according to the data given in the request." allOf: - $ref: "#/components/schemas/DeliveryPrice" DeliveryEventDeniedNoDeliveryMan: description: Metadata allOf: - $ref: "#/components/schemas/DeliveryEventDenied" - type: object - properties: metadata: type: object description: "Information about delivery person availability." properties: nextAvailableVehicle: type: integer description: "Informs how soon the next delivery person will be available in **minutes**." DeliveryEventDeniedEta: description: Metadata allOf: - $ref: "#/components/schemas/DeliveryEventDenied" - type: object - properties: metadata: type: object description: "The actual ETAs calculated according to the data given in the request." allOf: - $ref: "#/components/schemas/ETA" DeliveryProblem: description: Delivery Problem Object. type: object required: [reason, datetime, canFinishDeliver, needMerchantAction] properties: reason: type: string description: "Problem reason." enum: - DELIVERYPERSON_OCCURRENCE - PAYMENT_PROBLEMS - WRONG_PRODUCT_OR_ITEM - ORDER_DELAYED - ORDER_DAMAGED_OR_VIOLATED - CUSTOMER_DID_NOT_PLACE_ORDER - CUSTOMER_ADDRESS_UNKNOWN - ORDER_MISSING_ITEMS - NOBODY_TO_RECEIVE - DELIVERYPERSON_WAITING_PAYMENT_FOR_ALREADY_PAID_ORDER - ORDER_DELIVERED_WITHOUT_PAYMENT - FRAUD_OR_THEFT - OTHER message: type: string description: "Free message. It should be used to provide more detailed information." datetime: type: string format: date-time description: "Date and time when the problem ocurred. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." canFinishDeliver: type: boolean description: "Informs whether or not it is still possible to finish the delivery." needMerchantAction: type: boolean description: "Informs whether or not the merchant needs to perform some action in order for delivery to continue." DeliveryProblemHistory: description: Delivery Event. type: object required: [reason, datetime, resolved] properties: reason: type: string description: "Problem reason." enum: - DELIVERYPERSON_OCCURRENCE - PAYMENT_PROBLEMS - WRONG_PRODUCT_OR_ITEM - ORDER_DELAYED - ORDER_DAMAGED_OR_VIOLATED - CUSTOMER_DID_NOT_PLACE_ORDER - CUSTOMER_ADDRESS_UNKNOWN - ORDER_MISSING_ITEMS - NOBODY_TO_RECEIVE - DELIVERYPERSON_WAITING_PAYMENT_FOR_ALREADY_PAID_ORDER - ORDER_DELIVERED_WITHOUT_PAYMENT - FRAUD_OR_THEFT - OTHER message: type: string description: "Free message. It should be used to provide more detailed information." datetime: type: string format: date-time description: "Date and time when the problem ocurred. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." resolved: type: boolean description: "Informs if the problem was resolved or not." actionTaken: type: string description: "Action taken by the requester." enum: - RETURN_TO_STORE - DELIVER_PRODUCT - CANCEL_DELIVERY resolutionDate: type: string format: date-time description: "Date and time when the problem was resolved. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." ChosenVehicle: description: Delivery Order Response Object type: object required: [type, container] properties: type: type: string description: "Vehicle Type." enum: - "MOTORBIKE_BAG" - "MOTORBIKE_BOX" - "CAR" - "BICYCLE" - "SCOOTER" - "VUC" container: type: "string" description: "The veichle container (bag) type." enum: - "NORMAL" - "THERMIC" containerSize: type: string description: "Vehicle container (bag) size." enum: - "SMALL" - "MEDIUM" - "LARGE" - "EXTRA_LARGE" instruction: type: "string" description: "Special Instructions." DeliveryPrice: description: Delivery Pricing type: object required: [price, pricingList, additionalPricePercentual] properties: price: description: "The calculated price of the delivery. It may be 0. The price shall be calculated according to the Price List being used, as well as previously established commercial agreements." allOf: - $ref: "#/components/schemas/Price" pricingList: type: string description: "Indicates what list was used to calculate the delivery price." enum: - "NORMAL" - "DYNAMIC" additionalPricePercentual: type: number description: |- Indicates the additional percentage to the list price that was calculated for this delivery. Example: List Price = $10 Actual calculated price = $15 Additonal price percentage = **50** DeliveryAvailabilityPrice: description: Delivery Order Object type: object required: [ pickupAddress, returnToMerchant, canCombine, deliveryAddress, vehicle, limitTimes, totalOrderPrice, totalWeight, ] properties: merchant: type: "object" required: [id, "name"] description: "Merchant information." properties: id: type: 'string' description: |- Unique Identifier. Identifies the merchant in the different systems that the merchant will communicate. This id must be generated by the merchant's **`Software Service`**. > To avoid duplicates between different merchants it is recommended that the software creates the merchantId using: > `Merchant Document + UUID` > If this is not possible, it is recommended to at least use a UUID. minLength: 36 maxLength: 100 example: '22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824' name: type: 'string' description: 'Merchant Public Name' maxLength: 500 example: 'Pizza Plaza' pickupAddress: description: "Pickup Address." allOf: - $ref: "#/components/schemas/AddressLogistics" - type: object properties: pickupLocation: type: string description: "Pickup Location" parkingSpace: type: boolean description: "Parking Space" instructions: type: string description: "Instructions" returnToMerchant: type: boolean description: "Inform whether the delivery person should return to the pickup address after the delivery has been made." canCombine: type: boolean description: "Inform whether the **`Logistic Service`** can combine this order with other orders in the same delivery." deliveryAddress: description: "Delivery Address" allOf: - $ref: "#/components/schemas/AddressLogistics" - type: object properties: instructions: type: string description: "Instructions" vehicle: description: "Vehicle Info. informs which vehicle options are to be used for delivery. More than one can be informed, but the logistics service must choose only one of the types of vehicles informed." allOf: - $ref: "#/components/schemas/Vehicle" limitTimes: type: object description: "Limit Times. Informs the maximum pickup and delivery times that must be met by the `Logistics Service`." properties: pickupLimit: type: integer description: "Pickup Limit in **minutes**. It should be used to inform the maximum amount of minutes from the time the request was made to which the order should be collected at the merchant." example: 23 deliveryLimit: type: integer description: "Delivery Limit in **minutes**. It should be used to inform the maximum amount of minutes from the time the request was made to which the order should be delivered at the consumer's address." example: 48 orderCreatedAt: type: string format: date-time description: "The date and time that the Order was created at the **Ordering Application**. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." totalOrderPrice: description: "Total order price that was calculated and displayed for the final consumer in the **`Ordering Application`**. This value may already contain taxes and shipping in addition to the value of the items purchased." allOf: - $ref: "#/components/schemas/Price" orderDeliveryFee: description: "This field informs the delivery fee paid by the consumer in the **`Ordering Application`**." allOf: - $ref: "#/components/schemas/Price" totalWeight: type: integer description: "Total Weight in **grams**" packageVolume: type: number description: "The cubage of the packaging in **cubic meters (m³)**." packageQuantity: type: integer description: |- Number of packages that will be transported in this order. For example, 2 packages, or 3 boxes. > The unit of measure will not be considered, only the quantity. specialInstructions: type: string description: "Free text to describe special instructions that may apply." additionalPricePercentual: type: number description: |- Indicates to the **`Logistic Service`** an additional percentage to the list price that the requester agrees to pay for the delivery. > The delivery request will be refused if the delivery price exceeds this value. Example: List Price = $10 Actual calculated price = $15 Additonal price percentage = **50** In this case, any value informed below 50, would result in the order being rejected. onlinePayment: type: boolean description: "Informs whether or not the payment has already been made in the **`Ordering Application`**" DeliveryAvailabilityPriceResponse: description: Delivery Order Response Object type: object properties: deliveryPrice: description: "Delivery Pricing Info." allOf: - $ref: "#/components/schemas/DeliveryPrice" vehicles: type: object description: "Chosen Vehicle Info." properties: availableVehicles: type: integer description: "Informs how many vehicles are available at the moment." vehiclesAvailable: description: "List of currently available vehicles." allOf: - $ref: "#/components/schemas/Vehicle" nextAvailableVehicle: type: integer description: "Informs how soon the next vehicle will be available in **minutes**." ETAs: description: "ETAs" allOf: - $ref: "#/components/schemas/ETA" ETA: description: ETA type: object required: [ updateMethod, pickupEtaInMinutes, pickupEtaDatetime, deliveryEtaInMinutes, deliveryEtaDatetime, maxDeliveryTime ] properties: updateMethod: type: string description: |- Update Method: Indicates how the times will be updated in the events. `OFFLINE`: The time will be calculated in the event `ACCEPTED` and will no longer be updated in the following events. `ONLINE`: The time will be updated in all events. In this case, when the collection has already occurred, the `pickupEtaInMinutes` property will be set to **0** and the `pickupEtaDatetime` property will be the time when the collection occurred. enum: - OFFLINE - ONLINE pickupEtaInMinutes: type: integer description: "Pickup Eta in **minutes**. Informs how many minutes it will take the delivery person to arrive at the merchant for order pickup." pickupEtaDatetime: type: string format: date-time description: "Pickup Eta Datetime. Informs the date and time the delivery person is expected to arrive at the merchant for order pickup. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." deliveryEtaInMinutes: type: integer description: "Delivery Eta in **minutes**. Informs how many minutes it will take the delivery person to arrive at the consumer's address for order delivery." deliveryEtaDatetime: type: string format: date-time description: "Delivery Eta Datetime. Informs the date and time the delivery person is expected to arrive at the consumer's address for order delivery. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." returnToMerchantEtaInMinutes: type: integer description: "Delivery Person return to merchant Eta in **minutes**. Informs how many minutes it will take the delivery person to return to the merchant. Only valid when `returnToMerchant` is `true`." returnToMerchantEtaDatetime: type: string format: date-time description: "Delivery Person return to merchant Eta Datetime. Informs the date and time the delivery person will arrive at the returning merchant. Only valid when `returnToMerchant` is `true`. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." maxDeliveryTime: type: string format: date-time description: "Maximum Date and Time for delivery. This time should not exceed the delivery time limit given in the order request. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." DeliveryMan: description: Delivery Person type: object required: [id, name] properties: id: type: string description: "Delivery Person Id generated at the `Logistics Service`." name: type: string description: "Delivery Person Name." pictureURL: type: string format: "URI" description: "URL to access the photo of the delivery person. Before entering this field, check that the parties allow data to be shared according to data disclosure laws and rules." phone: type: string description: "Delivery Person Phone. Before entering this field, check that the parties allow data to be shared according to data disclosure laws and rules." GeoLocalization: description: Delivery Event type: object required: [latitude, longitude] properties: latitude: type: "number" format: "float" description: "Indicates the latitude coordinate of the actual position of the delivery person.\n\n\n\nLatitude in degrees. Values are restricted to the range [[-90, 90]]." example: -23.54809 longitude: type: "number" format: "float" description: "Indicates the longitude coordinate of the actual position of the delivery person.\n\n\n\nLongitude in degrees. Values are restricted to the range [[-180, 180]]." example: -46.63638 lastAddress: description: The last known address that the delivery person was when the event was sent. type: object required: [distanceToPickup, distanceToDelivery, timestamp] properties: "country": type: "string" pattern: "^[A-Z]{2}$" description: "Two-letter [ISO 3166-1 alpha-2](https://www.iso.org/standard/72482.html) country code." example: "BR" state: type: "string" description: "State or country subdivision. It is recommended (but not required) that you use the [ISO 3166-2](https://www.iso.org/standard/72483.html) representation. " example: "BR-SP" "city": type: "string" description: "City name." example: "São Paulo" "district": type: "string" description: "District or Neighborhood name." example: "Moema" "street": type: "string" description: "Street Name." example: "Plaza Avenue" "postalCode": type: "string" description: "Postal Code." example: "20111-000" distanceToPickup: type: string description: "Distance To Pickup in **meters**." distanceToDelivery: type: string description: "Distance To Delivery in **meters**." timestamp: type: string format: date-time description: "Date and time when this information is valid. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." DeliveryCancel: description: Delivery Cancel type: object required: [reason] properties: reason: type: string description: "Cancel Reason." enum: - CONSUMER_CANCELLATION_REQUESTED - NO_SHOW - PROBLEM_AT_MERCHANT - HIGH_ACCEPTANCE_TIME - INCORRECT_ORDER_OR_PRODUCT_PICKUP - PROBLEM_RESOLUTION - DISCOMBINE_ORDER - OTHER action: type: string description: "Action to be taken by the delivery person, after the cancellation." enum: - RETURN_TO_STORE - CANCEL_DELIVERY message: type: string description: "Free message. It should be used to provide more detailed information." DeliveryCancelResponse: type: object required: [additionalCharges] properties: additionalCharges: type: boolean description: "Informs whether or not the cancellation will cause an additional charge to the delivery." DeliveryHandleProblem: description: Delivery Cancel type: object required: [reason, action] properties: reason: type: string description: "Problem Reason." enum: - DELIVERYPERSON_OCCURRENCE - PAYMENT_PROBLEMS - WRONG_PRODUCT_OR_ITEM - ORDER_DELAYED - ORDER_DAMAGED_OR_VIOLATED - CUSTOMER_DID_NOT_PLACE_ORDER - CUSTOMER_ADDRESS_UNKNOWN - ORDER_MISSING_ITEMS - NOBODY_TO_RECEIVE - DELIVERYPERSON_WAITING_PAYMENT_FOR_ALREADY_PAID_ORDER - ORDER_DELIVERED_WITHOUT_PAYMENT - FRAUD_OR_THEFT - OTHER action: type: string description: "The action that the delivery person should take to solve this problem." enum: - RETURN_TO_STORE - DELIVER_PRODUCT - CANCEL_DELIVERY message: type: string description: "Free message. It should be used to provide more detailed information." DeliveryOrderPicked: type: "object" title: "Order Picked" properties: pickupDate: type: "string" format: date-time description: "Date and time when the order pickup occurred. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." volumePicked: type: "integer" description: "Number of volumes picked up." observation: type: string description: "Free text. It should be used to provide more detailed information." DeliveryOrderFinish: type: "object" title: "Order Picked" required: ["finishDate"] properties: finishDate: type: "string" format: date-time description: "Date and time when delivery completion occurred. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." observation: type: string description: "Free text. It should be used to provide more detailed information." DeliveryOrderDetails: description: Delivery Order Details Object type: object required: [ deliveryId, orderId, orderDisplayId, merchant, customerName, events ] properties: deliveryId: type: "string" format: "UUID" description: "The delivery ID generated by the `Logistics Service`." orderId: type: "string" format: "UUID" description: "The orderId generated by the **`Ordering Application`**." orderDisplayId: type: string description: "Order Id shown in the **`Ordering Application`** interface for the customer." example: "96b41025" merchant: type: "object" required: [id, "name"] description: "Merchant information." properties: id: type: 'string' description: |- Unique Identifier. Identifies the merchant in the different systems that the merchant will communicate. This id must be generated by the merchant's **`Software Service`**. > To avoid duplicates between different merchants it is recommended that the software creates the merchantId using: > `Merchant Document + UUID` > If this is not possible, it is recommended to at least use a UUID. minLength: 36 maxLength: 100 example: '22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824' name: type: 'string' description: 'Merchant Public Name' maxLength: 500 example: 'Pizza Plaza' customerName: type: "string" description: "Customer Name." customerPhone: type: "string" description: |- Customer's telephone number. **Please note**: The telephone number is considered an identification field and therefore the customer's advance consent is required. events: type: array description: "Events History." items: allOf: - $ref: "#/components/schemas/DeliveryEvent" problem: type: array description: "History of problems that occuried during delivery." items: allOf: - $ref: "#/components/schemas/DeliveryProblemHistory" vehicle: description: |- Chosen Vehicle Info. > This propertie is **REQUIRED** when current `event > type` is different from `PENDING`, `REJECTED` and `CANCELLED` allOf: - $ref: "#/components/schemas/ChosenVehicle" deliveryPrice: description: |- Delivery Pricing Info. > This propertie is **REQUIRED** when current `event > type` is different from `PENDING`, `REJECTED` and `CANCELLED` allOf: - $ref: "#/components/schemas/DeliveryPrice" times: description: |- Estimate Times of Pickup and Delivery. > This propertie is **REQUIRED** when current `event > type` is different from `PENDING`, `REJECTED` and `CANCELLED` allOf: - $ref: "#/components/schemas/DeliveryTimes" deliveryPerson: description: "Delivery person Info." allOf: - $ref: "#/components/schemas/DeliveryMan" combinedOrdersIds: type: "array" description: "Combined Orders Ids. Informs which other orders from the same merchant are being carried by the same delivery person, with the same `deliveryId`." items: type: string format: uuid externalTrackingURL: type: string format: "URI" description: "External URL, provided by the logistics service to track the delivery on a specific page. Example: Real-time map view, or delivery timeline." DeliveryTimes: description: ETA type: object required: [deliveryEtaDate, maxDeliveryTime, isDeliveryFinished] properties: deliveryEtaDate: type: string format: date-time description: "Delivery Eta Datetime. Informs the date and time the delivery person is expected to arrive at the consumer's address for order delivery. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." maxDeliveryTime: type: string format: date-time description: "Maximum Date and Time for delivery. This time should not exceed the delivery time limit given in the order request. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." isDeliveryFinished: type: boolean description: "Informs whether or not the delivery is finished." deliveryFinishDate: type: string format: date-time description: "Date and time when the delivery finished. \n\n(UTC date-time in ISO timestamp format. See [Guidelines](#section/General-Guidelines) for more info)." DeliveryConfirmationCode: description: Delivery Confirmation Object. type: object required: [orderId, deliveryCode] properties: orderId: type: "string" format: "uuid" description: "The orderId informed in the Delivery Request." example: "52122852-6626-11ed-9022-0242ac120002" deliveryCode: type: string description: "Delivery confirmation code provided by the customer." examples: tokenExample: summary: New Token value: client_id: 'user1234' client_secret: 'ty23yhmas4ldfias9834023jsdf032j023f02' grant_type: 'client_credentials' # orderExample: # summary: 'Sample Order' # value: # id: '4818e72f-2304-466f-9fe7-af08f34ac4ed' # type: 'DELIVERY' # displayId: '12345' # createdAt: '2021-05-27T19:38:10.332Z' # orderTiming: 'INSTANT' # preparationStartDateTime: '2021-05-27T19:45:10.332Z' # merchant: # id: "7fb59cb8-5808-40c8-b967-1b3f20ee39cd" # name: 'Plaza Pizza' # items: # [ # { # id: "732bd31e-77fc-47ee-88ee-a0437f97b198", # index: 0, # name: 'Medium - 2 flavors', # externalCode: '22', # unit: 'UNIT', # quantity: 1, # specialInstructions: 'Do not put onions.', # unitPrice: { value: 43.00, currency: 'BRL' }, # optionsPrice: { value: 50.00, currency: 'BRL' }, # totalPrice: { value: 50.00, currency: 'BRL' }, # options: # [ # { # id: "e5232f14-430c-4a94-8ff6-289d5a16a87a", # name: '1/2 Pepperoni', # externalCode: '23', # unit: 'UNIT', # quantity: 1, # unitPrice: { value: 50.00, currency: 'BRL' }, # price: { value: 50.00, currency: 'BRL' }, # specialInstructions: 'None', # }, # { # id: "7e507cab-7235-4f75-a0c2-e955fb2f2048", # name: '1/2 Mozzarella', # externalCode: '24', # unit: 'UNIT', # quantity: 1, # unitPrice: { value: 30.00, currency: 'BRL' }, # price: { value: 30.00, currency: 'BRL' }, # specialInstructions: 'None', # }, # ], # }, # ] # otherFees: # [ # { # name: 'Delivery', # type: 'DELIVERY_FEE', # receivedBy: 'MARKETPLACE', # receiverDocument: '1234', # price: { value: 5.00, currency: 'BRL' }, # observation: 'None', # }, # ] # discounts: # [ # { # amount: { value: 20.00, currency: 'BRL' }, # target: 'DELIVERY_FEE', # sponsorshipValues: # [ # { # name: 'MARKETPLACE', # amount: { value: 10.00, currency: 'BRL' }, # }, # { # name: 'MERCHANT', # amount: { value: 10.00, currency: 'BRL' }, # }, # ], # }, # ] # total: # { # itemsPrice: { value: 50.00, currency: 'BRL' }, # otherFees: { value: 5.00, currency: 'BRL' }, # discount: { value: 20.00, currency: 'BRL' }, # orderAmount: { value: 35.50, currency: 'BRL' }, # } # payments: # prepaid: 55.00 # pending: 0 # methods: # [ # { # value: 55.00, # currency: 'BRL', # method: 'FOOD_VOUCHER', # methodInfo: 'None', # }, # ] # customer: # id: "d9730653-a8ba-4e85-8dbb-b5697e6ae8d5" # phone: # number: '11999999999' # extension: '0' # documentNumber: '12345' # name: 'John' # ordersCountOnMerchant: 1 # delivery: # deliveredBy: 'MERCHANT' # deliveryAddress: # country: 'BR' # streetName: 'Gomes de Carvalho Street' # formattedAddress: 'string' # streetNumber: '100' # city: 'São Paulo' # postalCode: '20111-000' # coordinates: # latitude: -23.54754 # longitude: -46.63611 # neighborhood: 'Moema' # state: 'SP' # complement: '102' # estimatedDeliveryDateTime: '2021-05-27T20:45:10.332Z' # deliveryDateTime: '2021-05-27T20:47:10.443Z' # extraInfo: 'None' merchantExample: summary: 'Merchant Example' value: lastUpdate: '2021-05-27T20:45:10.332Z' TTL: 500 id: '22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824' status: 'AVAILABLE' basicInfo: name: 'Pizza Plaza' document: '22815773000169' corporateName: 'Food Company' description: 'Food company specializing in pizzas.' averageTicket: 90.00 averagePreparationTime: 20 minOrderValue: value: 20.00 currency: 'BRL' merchantType: 'RESTAURANT' merchantCategories: ['PIZZA', 'FAMILY_MEALS', 'PREMIUM'] address: country: 'BR' state: 'SP' city: 'São Paulo' district: 'Moema' street: 'Plaza Avenue' number: '100' postalCode: '20111-000' complement: '2001' reference: 'Yellow house' latitude: -23.54804 longitude: -46.63630 contactEmails: ['food@company.com'] contactPhones: { commercialNumber: '11999999999', whatsappNumber: '11998888888' } logoImage: URL: 'https://food-company.com/logo.png' CRC-32: 432098ASDSR bannerImage: URL: 'https://food-company.com/banner.png' CRC-32: 09345UIHF98 createdAt: '2021-05-10T20:45:10.332Z' services: [ { id: 'f078e8e2-3044-4eec-b4a8-8359810de123', status: 'AVAILABLE', serviceType: 'DELIVERY', menuId: 'f627ccdc-6789-456f-a782-148538d5035b', serviceArea: { 'id': 'f078e8e2-3044-4eec-b4a8-8359810de124', 'polygon': [ { 'geoCoordinates': [ { 'latitude': -20.23330, 'longitude': -20.83830 }, { 'latitude': -20.85008, 'longitude': -21.00007 }, { 'latitude': -21.15002, 'longitude': -21.95483 }, ], 'price': { 'value': 5, 'currency': 'BRL' }, 'estimateDeliveryTime': 25, }, ], 'geoRadius': { 'geoMidpointLatitude': -20.2333, 'geoMidpointLongitude': -20.8383, 'radius': [ { 'size': 10, 'price': { 'value': 5.50, 'currency': 'BRL' }, 'estimateDeliveryTime': 10, }, ], }, }, serviceHours: { id: 'fb093d8c-2ca5-40fb-afcf-472fbdae81cc', weekHours: [ { dayOfWeek: [ 'MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', ], timePeriods: { startTime: '10:00:00.000Z', endTime: '18:00:00.000Z', }, }, { dayOfWeek: ['SATURDAY', 'SUNDAY'], timePeriods: { startTime: '14:00:00.000Z', endTime: '18:00:00.000Z', }, }, ], holidayHours: [ { date: '2021-05-27', timePeriods: { startTime: '12:00:00.000Z', endTime: '17:00:00.000Z', }, }, ], }, }, ] items: [ { id: '732bd31e-77fc-47ee-88ee-a0437f97b198', name: 'Medium - 2 flavors', description: 'Medium two-flavored pizza.', externalCode: '23', image: { URL: 'https://www.food-place.com/images/medium-pizza.png', CRC-32: 09345UIHF98, }, serving: 8, unit: 'UN', }, { id: 'b728fd88-4af0-43f7-956f-95c251f01ddd', name: 'Small - 1 flavor', description: 'Small one-flavored pizza.', externalCode: '23', image: { URL: 'https://www.food-place.com/images/small-pizza.png', CRC-32: 09345UIHF98, }, serving: 4, unit: 'UN', }, { id: '502ecf11-0509-48ed-b63c-6211c48fd9b9', name: '1/2 Pepperoni', description: 'Pepperoni flavored pizza with LOTS of pepperoni.', externalCode: '23', image: { URL: 'https://www.food-place.com/images/pepperoni.png', CRC-32: 09345UIHF98, }, nutritionalInfo: { description: 'Contains preservatives', calories: '2000 Cal', allergen: ['GLUTEN'], }, unit: 'UN', }, { id: 7e507cab-7235-4f75-a0c2-e955fb2f2048, name: '1/2 Mozzarella', description: 'Delicious mozzarella pizza.', externalCode: '24', image: { URL: 'https://www.food-place.com/images/mozzarella.png', CRC-32: 09345UIHF98, }, nutritionalInfo: { description: 'Contains preservatives', calories: '2500 Cal', allergen: ['GLUTEN', 'LACTOSE'], }, unit: 'UN', }, { id: 2c0f3447-5309-49cc-a167-4eac5c664470, name: 'Banana', description: 'Banana Pizza with cream.', externalCode: '25', image: { URL: 'https://www.food-place.com/images/banana.png', CRC-32: 09345UIHF98, }, nutritionalInfo: { description: 'Contains preservatives', calories: '2500 Cal', allergen: ['GLUTEN'], }, unit: 'UN', }, ] menus: [ { id: 'f627ccdc-6789-456f-a782-148538d5035b', name: 'Pizzas', description: 'Pizza menu', externalCode: '123', disclaimer: 'Lorem Ipsum is simply dummy text of the printing and typesetting industry.', categoryId: [ '92fad022-2c28-4239-a026-989f5b555cb7', '6bb71850-1d40-49f9-8046-b13e068c0cca', ], }, ] categories: [ { id: '92fad022-2c28-4239-a026-989f5b555cb7', index: 0, name: 'Salted Pizza', description: 'Salted pizza flavors.', image: { URL: 'https://food-company.com/category1.png', CRC-32: 09345UIHF98, }, externalCode: '13', status: 'AVAILABLE', availabilityId: ['11d063c4-73a7-4f87-a0eb-71636cc02029'], itemOfferId: ['f080cfb3-5c4a-4eb7-907d-2de3bbb5dfb9'], }, { id: '6bb71850-1d40-49f9-8046-b13e068c0cca', index: 1, name: 'Sweeted Pizza', description: 'Sweeted pizza flavors.', image: { URL: 'https://food-company.com/category2.png', CRC-32: 09345UIHF98, }, externalCode: '13', status: 'AVAILABLE', availabilityId: ['11d063c4-73a7-4f87-a0eb-71636cc02029'], itemOfferId: ['377b99ba-5413-43d1-b875-7cdcaa72860e'], }, ] itemOffers: [ { id: f080cfb3-5c4a-4eb7-907d-2de3bbb5dfb9, itemId: 732bd31e-77fc-47ee-88ee-a0437f97b198, index: 0, price: { value: 43.00, originalValue: 43.00, currency: 'BRL' }, availabilityId: ['11d063c4-73a7-4f87-a0eb-71636cc02029'], optionGroupsId: ['fe67e551-f42f-499a-8afb-0ed893c71fa3'], }, { id: 377b99ba-5413-43d1-b875-7cdcaa72860e, itemId: 7e507cab-7235-4f75-a0c2-e955fb2f2048, index: 1, price: { value: 30.00, originalValue: 30.00, currency: 'BRL' }, availabilityId: ['11d063c4-73a7-4f87-a0eb-71636cc02029'], optionGroupsId: ['c524c066-96fa-458d-b78c-3712661529b3'], }, ] optionGroups: [ { id: 'fe67e551-f42f-499a-8afb-0ed893c71fa3', index: 0, name: 'Choose your salted pizza flavor', description: 'Choose your salted pizza flavor.', externalCode: '12', status: 'AVAILABLE', minPermitted: 2, maxPermitted: 2, options: [ { id: 'e5232f14-430c-4a94-8ff6-289d5a16a87a', itemId: '502ecf11-0509-48ed-b63c-6211c48fd9b9', index: 0, price: { value: 50.00, originalValue: 50.00, currency: 'BRL' }, maxPermitted: 1, }, { id: 'e5232f14-430c-4a94-8ff6-289d5a16a87b', itemId: '7e507cab-7235-4f75-a0c2-e955fb2f2048', index: 1, price: { value: 43.00, originalValue: 43.00, currency: 'BRL' }, maxPermitted: 1, }, ], }, { id: 'c524c066-96fa-458d-b78c-3712661529b3', index: 0, name: 'Choose your sweeted pizza flavor', description: 'Choose your sweeted pizza flavor.', externalCode: '12', status: 'AVAILABLE', minPermitted: 1, maxPermitted: 1, options: [ { id: '2419d582-357f-4149-9089-12321537f147', itemId: '2c0f3447-5309-49cc-a167-4eac5c664470', index: 0, price: { value: 30.00, originalValue: 30.00, currency: 'BRL' }, maxPermitted: 1, }, ], }, ] availabilities: [ { id: '11d063c4-73a7-4f87-a0eb-71636cc02029', startDate: '05/01/2021', endDate: '05/30/2021', hours: [ { dayOfWeek: ['MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY'], timePeriods: { startTime: '10:00:00.000Z', endTime: '18:00:00.000Z' }, }, { dayOfWeek: ['SATURDAY', 'SUNDAY'], timePeriods: { startTime: '14:00:00.000Z', endTime: '18:00:00.000Z' }, }, ], }, ]