# Keeta Open Delivery API
# ■ --- GENERAL INFO --- ■
**Special Note:**
- Keeta Open Delivery API is based on **Open Delivery v1.5.0**. For basic understanding, please refer to Open Delivery API.
- For some of the APIs, **Keeta has made some adjustments based on business scenarios**. Therefore, when Software Service integrates with Keeta, please refer to the APIs definitions in this document.
**The major changes include:**
> - Authentication: **The credentials have been changed from the merchant level to the software level, and the token as well.** However, software services cannot access the merchant data without the merchant's authorization first.
> - Signature: **Keeta requires the Software Service to include a signature in the header of every API request.** This is to enhance security and prevent the risk of data leakage due to token exposure (such as man-in-the-middle attacks).Please refer to the detailed documentation for the specific signing requirements.
> - Merchant Menu: Keeta supports menu push (software services push via POST /merchantUpdate interface) and pull (Keeta pulls via GET /merchant interface); however, **Keeta currently only supports full menu updates (modular entry updates are not supported at this time)**. For details, please refer to the description of the corresponding Merchant endpoints in this document.
> - Order: **Keeta supports querying order events of batch merchants in the polling endpoint**, since the credential is in the software level.
> - Fields: **Keeta has made some adjustments to the fields in each endpoint, including the number of fields, whether the fields are required, etc.** Please refer to the definitions in this document.
> - Refund Process: When requesting a total/partial refund after order completion, a negotiation will be initiated between the **Customer** and the **Merchant**. This allows the **Merchant** the opportunity to `ACCEPT` or `DENY` the Customer's request. For details, refer to **ORDERS** section.
> - User Privacy Data: To protect users' personal privacy, Keeta will return encrypted data in [order details](#operation/orderDetails). In scenarios involving **merchant self-delivery or third-party logistics (3PL)**, this data can be decrypted. If Software Services need to decrypt the data, they must make additional calls to the [data decryption endpoint](#operation/batchDecrypt). For details, please refer to the description in the **Order section** of this document.
- We strongly recommend software services to integrate the menu API for data synchronization, to avoid merchants maintaining menus in multiple places.
- Keeta provides a self-service authorization feature in its merchant management system . Merchants can log in to the system to independently authorize or revoke access for Software Services. Detailed instructions are available in the relevant documentation section .
- In addition, Keeta offers API endpoints that enable Software Services to automate merchant authorization and embed the workflow into their own SaaS software. For implementation details, please refer to the relevant documentation section .
- You can
Download the Postman Collection
and add signature calculation script to the pre-request section in Postman to simplify integration and testing.
**Important** :You need to replace the secret value in the Postman script with the one assigned to you by Keeta.
- For some general instructions, can directly refer to Open Delivery Documents, and relevant links will be attached.
# ─► How to Start
Preparation Phase
NDA
Please contact the Keeta team to sign the NDA (Non-disclosure Agreement).
Complete profile information
After you have signed the NDA, Keeta API experts will share developer account and test application ID and secret with you. Log in to the Keeta Developer Portal using the developer account we provided.
Please complete the profile on the Information Management page of the Dev Portal, including company logo, contact phone number, contact email, and merchant operations email.
These details are essential—make sure all information is fully filled out and accurate.
Please note that your company logo will be visible to customers, so ensure it is uploaded correctly. Additionally, Keeta will send the test store credentials and merchant onboarding details to the email addresses listed above — please double-check that they are accurate.
Set up test store and Keeta test APP
-
a.
Please log in to the Dev Portal and use the Test Store Tool to create a test store.
-
b.
During the store creation process, please scan the Keeta App QR code to download the Keeta Test App. Then, register as a Keeta user using your mobile phone number.
-
c.
Once registration is complete, enter your phone number to link your user account with the test store. After this step, you’ll be able to view your test store within the app.
-
d.
For instructions on using test store in Keeta test APP, click here .
-
e.
Once you've created a test store, the credentials will be sent to the primary contact email. You can then use the account to log into the Keeta Merchant Management System , where you'll be able to manage store business hours, basic information, and menus.
Development Phase
SOW (Statement of Work)
Before initiating technical development, please download the SOW file from the Integration Document Management section. Complete the document before the online integration testing (SIT homologation) with Keeta, and upload it to the Dev Portal.
(This file defines the scope of this integration (SOW – Statement of Work) and will help you understand keeta API system).
Developer Self-Test
Please download and review the SIT file, which is a set of self-testing use cases for your reference during internal QA. Keeta team will use the same test cases in the Joint SIT (system integration test) test in the future. We recommend that you follow these test cases to ensure the system functions properly. Please fill in and submit the self-test records before conducting SIT tests with Keeta.
Joint SIT (System Integration Test) with Keeta
After completing the developer self-test, please schedule an online joint SIT test (homologation) with Keeta. Keeta team will attend to conduct test with you and help resolve issues. If the SIT test meets the requirements, Keeta will sign off the test, and assign an application for the production environment (including the ID and secret) to you. It is strongly recommended to conduct thorough self-testing before the joint SIT test with Keeta.
UAT (User Acceptance Test) Phase
Schedule UAT Test
After passing the SIT test, we will coordinate with a common customer (restaurant) and schedule the UAT test (you can also recommend one to us).
Conduct UAT Test (Pilot store test)
Before the test, notify the responsible person of the customer's restaurant to ensure support for the test. The Keeta team will place and pay for orders in the actual store to verify that the software system functions properly (such as menu management, order management, KDS, receipt printing).
Please note that during the UAT testing phase, you must use the production environment application (which Keeta will assign to you after passing SIT testing) to access Keeta.
Test applications used during the development phase will not have access to merchant data.
Recommendation
Operational Meeting
We recommend that both parties' operational teams hold an operation meeting after the system integration is completed to discuss the subsequent merchant activation/authorization process and align on daily operation and technical issue handling mechanisms.
In addition, based on your developer account, Keeta can provide operation accounts upon request. This accounts allow you to view and manage merchants that have authorized your applications on the Dev Portal.
# ─► Integrating with Keeta API
- ### Authenticate
All API endpoints (except **Get Access Token** itself) require authentication. Therefore, you must first obtain an access token by calling the [Get Access Token](#operation/getToken) endpoint before making any further requests.
- ### Configure Store Mapping and Webhooks
After obtaining the access token, you can register the mapping between your internal `merchantId` and the `Keeta merchantId`, and configure webhook endpoints by calling the [Merchant Onboarding](#operation/putMerchantOnboarding) endpoint.
- ### Place a Test Order
Once the store mapping has been successfully configured, refer to the [**Keeta Test App**](./Keeta-test-APP) to place a test order for the configured store and proceed to the **Order Module** testing phase.
- ### Order Workflow Testing
At this stage, whenever a new order is placed from the registered store, you will receive a `PLACED` event via webhook or polling.
Upon receiving a `PLACED` event, you should first [retrieve order details](#operation/orderDetails), and then either [confirm](#operation/confirmOrder) or [cancel](#operation/cancelOrder) the order.
Once the order is prepared, you must either [mark it as ready](#operation/orderReady) or [dispatch it](#operation/dispatchOrder) — depending on whether the delivery will be fulfilled by the merchant or a third-party logistics provider.
✅ Good job! Your app is now ready to receive and process orders. For more advanced features, please refer to the relevant sections of this documentation.
# ─► Basic Concepts
- **PARAMETERS IN THE SOFTWARE SERVICE** (SOFTWARE SERVICE --> Keeta)
- **{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.
- **clientId** and **clientSecret**
- **Keeta** 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 are generated by Keeta, that is, **if several MERCHANTS use the same Software Service, the software will have a same clientId and clientSecret**.
- **AppId**
- It is the unique ID of Keeta which is generated by Keeta itself, it will be informed to all the Software Services that it will integrate.
- **X-App-Signature**
- Keeta requires Software Service to generate a signature and include it in the header of each API request. Refer to the [Signature Calculation](https://api-docs.mykeeta.com/apis/opendelivery/section/signature-calculation) section for the complete algorithm specification.
- **PARAMETERS IN Keeta** (Keeta --> SOFTWARE SERVICE)
- **[GET /merchant](#tag/merchantEndpoints) endpoint URL:**
- Keeta 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`
- ### General Guidelines
For general guidelines on the Keeta Open Delivery API, please refer directly to Open Delivery General Guidelines.
- ### Error Handling
For error handling guidelines on the Keeta Open Delivery API, please refer directly to Open Delivery Error Handling.
# ─► Keeta Developer Portal
Dev Portal is the developer backend for the Keeta API open platform, comprising two main modules:
1. Application Management
In this module, you can create and manage applications, view application tokens, and check the list of associated merchants.
For setting regular webhooks, please use the Open Delivery approach to register and update webhooks(e.g., via the " Register / Update Merchant endpoint info " method).
For Merchant authorization updates webhooks, you can directly configure them in the webhook setting page.
Please focus only on the webhook configuration for Formal Store. 1301 represents the webhook for new authorization notifications, and 1302 represents the webhook for authorization cancellation notifications.
2. Development Testing Tools
-
Store Mapping Check
This tool allows you to view and search all authorized merchant lists and their menu push statuses. To validate the accuracy of store mapping between systems, you can upload the store IDs and coordinates recorded in your system to Keeta. The system will automatically calculate the geographical deviation distance to achieve validation.
-
Test Store Tool
This tool allows you to create test stores. Please note that you must create an application before proceeding. You can also use this tool to manage the store’s operating status—for example, to reopen a store that was closed due to order failures. After creating a test store, go to Store Details → Edit → Link with your Keeta user account. Be sure to enter the same phone number you used to register as a Keeta user. This will make the test store visible in your app.
-
Keeta Rider Simulator
To test the full lifecycle of orders, you can use this tool to simulate the entire fulfillment process of a Keeta rider, including rider dispatching, arrival at the restaurant, food pickup, and delivery completion.
-
Test Order Tool
The Test Order Tool is a convenient web-based utility that allows developers to place test orders at designated test stores, enabling quick validation of the order flow. Alternatively, you may choose to download and use the Keeta Test App to browse store menus and place test orders directly.
# ─► Test Store Management
You can create a test store yourself in the Dev Portal (see Keeta Developer Portal for details), or use the test store assigned to you by Keeta. Using the account and password of the test store to log into the Keeta Merchant Management System , you will have access to all store management functions, including: viewing orders, viewing historical data, setting store operating hours and status, viewing and editing menus, and setting up promotion activities etc.
Menu Management
If you do not integrate with Keeta's Menu API (i.e., do not manage and publish menus via the API), you can edit and upload menus in the Merchant Management System for testing purposes. If needed, Please use the menu upload template (including PDV Code) to help quickly batch upload full menu and the corresponding external codes. Please contact Keeta team for details and support if needed.
Please note:
If the menu is not integrated, manual entry is required — and it's important to ensure the PDV Code is entered correctly.
However, if menu synchronization is performed via API, Keeta will automatically disable manual entry and modification through the Merchant Management System to prevent data inconsistencies and potential order failures.
If a merchant needs to make manual adjustments to the menu despite API integration, please contact the Keeta API team for support.
Promotion Settings
We recommend setting up various types of marketing activities and placing test orders in the test store to ensure that promotional information in the orders is processed correctly.
Additionally, if you wish to test scenarios involving Keeta platform subsidies, please contact the Keeta API team. We will add Keeta platform promotional items to your test store for this purpose.
Please note that in the SIT testing environment (homologation), we will test scenarios involving both merchant subsidies and platform subsidies to ensure the orders are processed correctly and the promotional information is accurately parsed.
# ─► Keeta test APP
To place orders for test stores, there are two available methods:
Developer Portal with Test Order Tool:
Log into the Dev Portal and use the Test Order Tool to directly place orders at the test store. This method is convenient and allows for rapid validation of order flow, but its functionality is limited.
Keeta Test App:
Download and use the Keeta Test App to browse the store menu and place orders directly within the app. This approach enables a full end-to-end simulation from the user perspective, provides a visualized menu interface, and allows you to trigger refund operations—making it essential for testing reverse order flows and other features.
Keeta team will share the download link for the Test APP (available for both Android and iOS versions). Please download and install the app, then select the Bongolava region (as shown in the image below), and complete the user registration (Brazilian phone numbers are supported).
Test Store Registration and Location Settings
After registration, please inform Keeta of your registered phone number and the test store ID you previously created via the link. The Keeta team will bind the two for you to place test orders. After this you will be able to see the test store in the Home page and place test orders with mocked payment.
Note: Keeta's test stores are located in the Bongolava region of Madagascar. Please ensure that the delivery address for the test order is near the test store.
If your test store cannot accept orders and displays “Out of Delivery Area,” please switch your current location to a nearby point within the designated testing region.
To update your location:
- Tap the address in the top-right corner of the screen.
- Select “Tap to Change.”
- Tap the top-right region selector (e.g., “Brasil”).
- Choose the first option: “Bongolava”, then tap “Confirm.”
- Select any available location point within the region and tap “Confirm Location.”
Once your location is updated, you will be within the testing area and can place orders at the designated test store.
# ─► Signature Calculation
This document describes the HMAC-SHA256 signature calculation process used for API authentication. The signature is generated by combining the request URL, query parameters, and request body into a signature string, then computing an HMAC-SHA256 hash using a secret key.
**Algorithm**: HMAC-SHA256
**Encoding**: Base64
**Signature Header**: X-App-Signature
## Signature Generation Process
#### Step 1: Extract Request Components
1. **URL**: Extract the base URL (without query parameters)
2. **Query Parameters**: Extract all enabled query parameters
3. **Request Body**: Process the request body content
#### Step 2: Build Signature String
The signature string is constructed by concatenating the following components with `&` as separator:
```curl
signature_string = URL + "&" + sorted_query_params + "&" + request_body
```
##### 2.1 URL Processing
- Use the base URL without query parameters
- Example: `https://api.example.com/v1/orders`
##### 2.2 Query Parameters Processing
- Extract all enabled query parameters
- Sort parameters by key name (alphabetical order)
- Format each parameter as `key=value`
- Join multiple parameters with `&`
- Handle null/undefined values as empty strings
**Example:**
```curl
Original parameters: {c: "3", a: "1", b: "2"}
Sorted result: a=1&b=2&c=3
```
##### 2.3 Request Body Processing
- JSON Format: Use JSON string directly
- Null Value Handling: Empty objects `{}` or empty strings will be skipped
- Type Conversion: Non-string types will be converted to JSON strings
#### Step 3: Calculate HMAC-SHA256 Signature
1. Use the constructed signature string as the message
2. Use the provided secret key
3. Calculate HMAC-SHA256 hash
4. Encode the result in Base64 format
## Examples
#### Example 1: GET Request with Query Parameters
**Request:**
``` curl
URL: https://api.example.com/v1/users
Query Parameters: {page: "2", limit: "10", sort: "name"}
Body: (empty)
```
**Signature String:**
``` curl
https://api.example.com/v1/users&limit=10&page=2&sort=name
```
#### Example 2: POST Request with JSON Body
**Request:**
``` curl
URL: https://api.example.com/v1/orders
Query Parameters: (empty)
Body: {"userId": 123, "productId": 456, "quantity": 2}
```
**Signature String:**
``` curl
https://api.example.com/v1/orders&{"userId":123,"productId":456,"quantity":2}
```
#### Example 3: PUT Request with Both Query Parameters and Body
**Request:**
```curl
URL: https://api.example.com/v1/products
Query Parameters: {version: "v2", format: "json"}
Body: {"name": "Product A", "price": 99.99}
```
**Signature String:**
```curl
https://api.example.com/v1/products&format=json&version=v2&{"name":"Product A","price":99.99}
```
## Signature calculation script example
- Below is a complete calculation script example of the signature (**JAVA**). You can refer to it to implement the signature calculation script of your development language.
```java
import org.apache.commons.lang.StringUtils;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import java.util.Map;
import java.util.TreeMap;
public class SignatureUtils {
/**
* generate signature
* @param url: request url
* @param queryParamMap: request query parameters Map Structure
* @param bodyJSONString: request body JSON String
* @param clientSecret: client secret
* @return
*/
public String generateSignature(String url, Map queryParamMap, String bodyJSONString, String clientSecret) {
StringBuilder sb = new StringBuilder();
// step 1: concat url
sb.append(url);
// step 2: concat query parameters
if (!queryParamMap.isEmpty()) {
// 2.1: sort by alphabetical order
TreeMap sortedParams = new TreeMap<>(queryParamMap);
// 2.2: concat key and value
for (Map.Entry entry : sortedParams.entrySet()) {
String key = entry.getKey();
String value = entry.getValue() != null ? entry.getValue().toString() : null;
sb.append("&");
sb.append(key + "=" + value);
}
}
// step 3: concat body
if (StringUtils.isNotBlank(bodyJSONString)) {
sb.append("&");
sb.append(bodyJSONString);
}
// step 4: got a complete string waiting to generate a signature
String signatureString = sb.toString();
try {
// step 5: initialize the HmacSHA256 algorithm with the clientSecret
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(clientSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
// step 6: calculate signature
byte[] bytes = mac.doFinal(signatureString.getBytes(StandardCharsets.UTF_8));
// step 7: encode the signature in Base64 format
String signature = new String(Base64.getEncoder().encode(bytes), StandardCharsets.UTF_8);
return signature;
}catch (NoSuchAlgorithmException e){
throw new IllegalStateException("Algorithm HmacSHA256 does not exist.", e);
}catch (InvalidKeyException e){
throw new RuntimeException("Key is invalid.", e);
}
}
}
```
# ─► Merchant Authorization
Merchant Adding Authorization (with APP ID)
If a merchant wants to authorize an application, the merchant should go to the App Activation tab in the Merchant Management
system, and click the "Activar aplicativo" button at the top right corner of the page and follow the steps below:
-
Enter the APP ID of the service provider's application (available from the provider).
-
Confirm provider information to ensure accuracy.
-
Select the store(s) to be authorized:
- For store-level accounts, this step is skipped.
- For brand-level accounts, the merchant must select which stores to authorize.
-
Click Confirm to proceed.
-
Click "Registro da autorização" to automatically download an Excel file containing the authorization record
-
Once authorization is complete:
- The service provider's merchant operations email will receive a notification.
- The provider's system will receive a webhook notification.
- The provider can retrieve authorized merchant data via API.
Merchant Adding Authorization (via URL)
The service provider logs into the Keeta Dev Portal using a developer or sub-account (operations account), clicks “Add Authorization” , and shares the generated authorization URL with the merchant.
- The merchant opens the URL and logs in using either a brand-level or store-level account.
- The merchant does not need to input an APP ID—simply select the stores to authorize, and click Confirm.
- Click “Registro da autorização” to automatically download an Excel record of the authorization.
-
Once authorization is completed:
- The provider’s merchant operations email will receive a notification.
- The provider’s system will receive a Webhook notification.
- Authorized merchant data can be retrieved via API.
After authorization, the merchant should contact the provider to complete store configuration (such as store mapping).
Merchant Revokeing Authorization
Merchants can revoke authorization using either of the following methods:
-
Bulk revocation:
Select the current list of stores and revoke authorization in a batch. A double-confirmation popup is required before the operation proceeds.
-
Single revocation:
Click the designated button and confirm to revoke authorization for an individual store.
Upon completion:
- An Excel file containing the operation record will be automatically downloaded for reference.
- The service provider's merchant operations email will receive a notification.
- The provider's system will receive a Webhook event.
- The provider will lose access to merchant store data via API.
Stay updated of merchants authorization activity
The service provider can receive notifications for merchant authorization cancellations or new authorizations via Webhook . Keeta will also send an email to the merchant operation mailbox, please check the inbox.
Or, the service provider can also view all the authorized stores in the Mapping Check in Dev Portal with detailed infomation, as mentioned above.
# ─► Merchant Self-serve Authorization
Before accessing merchant data, service providers must obtain authorization from merchants. Within the Keeta platform, it is recommended to use Merchant Self-Authorization to automate and streamline this process.
Step 1: Retrieve Authorization Link
Step 2: Merchant Authorization Operation
- Access Authorization Page: The merchant clicks the link, redirecting their browser to the Keeta authorization page.
- Authentication: The merchant logs in via Keeta, using either a Brand Account or a Store Account.
- Store Selection: The system displays the merchant’s store list.
- Brand account users must select the store scope to authorize.
- Store account users will proceed without additional selection.
Step 3: Post-Authorization Handling (Two Modes)
Mode A: Redirect Integration (Automated Workflow)
- Automatic Redirect: After authorization, Keeta redirects to the service provider system with the authId.
- Fetch Store Info: The service provider calls the API to retrieve detailed store information.
- Store Mapping UI: The service provider displays a mapping interface for the merchant to match their stores with the service provider’s system.
- Integration Complete: Upon confirmation, the service provider registers store data via the onboarding API.
Mode B: Manual Mapping via Authorization Records
- Merchant-side Download: After authorization, the Keeta merchant management system automatically downloads a spreadsheet of the authorized stores. Alternatively, merchants may manually download the store list to assist with mapping. To explore detailed functionality and operations, please log in to the merchant portal using a test store account.
- Email Notification to Service Provider: Keeta sends the authorized store list to the merchant operations email provided by the service provider for reference and mapping.
- View in Dev Portal: Service providers can log into the Dev Portal and use the Mapping Check feature to search for authorized store records and maintain mappings manually.
#
# ■ --- CHANGELOG --- ■
**Version[1.0.6] - Sep 2, 2025**
1. Added `Delivered` and `Send Delivery Updates` APIs related to "Merchant Responsible Delivery".
**Version[1.0.5] - Jul 25, 2025**
1. Added Integrating with the Keeta API.
2. Added Postman Collection.
**Version[1.0.4] - Jul 18, 2025**
**ORDERS changes**
1. Added the post `/v1/batchDecrypt` endpoint.
**Version[1.0.3] - Jul 8, 2025**
**ORDERS changes**
1. Added the post `/v1/orders/{orderId}/dispatch` endpoint. request validation only.
**Version[1.0.2] - Jul 7, 2025**
**MERCHANT changes**
1. Removed the post `/v1/merchantStatus/{merchantId}/available` and `post /v1/merchantStatus/{merchantId}/unavailable` endpoints, and unified the merchant status update through the `POST /merchantUpdate` endpoint (consistent with the native Open Delivery protocol).
**Version[1.0.1] - Jun 30, 2025**
**Response Body Structure Definition Change**
1. Version 1.0.0 introduced response body structural changes, while v1.0.1 was adjusted to **maintain alignment with the Open Delivery**.
**ORDERS changes**
1. Updated order events diagram and order flow diagram in **Order Overview** section.
2. Added **Order Refund** instruction under **Order Overview** which follows Keeta's refund rules.
3. Added sample metadata for payload within `USER_REFUND_REQUEST` event that could be notified by polling or webhook mechanism.
**MERCHANT changes**
1. The data structure and fields of `GET /merchant` and `POST /merchantUpdate` endpoints are adjusted to be consistent with the native Open Delivery protocol.
# ■ --- API REFERENCE --- ■
Version: v.1.0.6
## Servers
```
https://open.mykeeta.com/api/open/opendelivery
```
## Security
### OAuth2
OAuth2 should be the standard authentication method between parties.
- For the **ORDERS** and **MERCHANT** endpoints, **Keeta** 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 **Keeta** or **Logistics Service** company and access the [/oauth/token](#operation/getToken) endpoint.
> **Keeta** provide one `clientId` and `clientSecret` credentials for **Software Service**. Each **Software Service** is assigned only one client_id and client_secret.
### 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
-H 'authorization: Bearer '
https://{baseURL}/v1/events:polling
```
> Refresh Token is not available at this version.
Type: oauth2
### apiKey
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.
Type: apiKey
In: header
Name: X-API-KEY
### Sig
To enhance overall security, Keeta requires **Software services** to include a signature in the header when making requests to Keeta.
The signature should be generated as follows: SHA256 hash of the request body, using the client secret as the key.
Type: apiKey
In: header
Name: X-App-Signature
## Download OpenAPI description
[Keeta Open Delivery API](https://api-docs.mykeeta.com/_spec/apis/@opendelivery/opendelivery.yaml)
## └────► Authentication
Keeta suports two types of authentication methods: **OAuth 2** and **apiKey**.
### Get Access Token
- [POST /oauth/token](https://api-docs.mykeeta.com/apis/opendelivery/authentication/gettoken.md): Requests new access token for accessing Keeta API resources.
> The client_id and client_secret are issued by Keeta. .
The Software Service must obtain the merchant’s authorization before accessing their data.
HOST:
DIRECTION:
### Get Authorization URL
- [GET /oauth/authorization/url](https://api-docs.mykeeta.com/apis/opendelivery/authentication/getauthorizationurl.md): Get Keeta merchant authorization link for merchant authorization process.
> Merchants can click this link to complete the authorization process.
The returned URL can be used to redirect merchants to Keeta's authorization page.
URL Example: "https://merchant.mykeeta.com/m/web/openapi/authorize?locale=en®ion=BR&cityId=110200008&risk_cost_id=&responseType=client_credentials&appId=2123830428&redirectUri=&state=&scope=all/#/app-activation"
If Software Services wants merchants to be redirected to your own page after authorization, you can set the parameter accordingly.
When the merchant completes authorization, they will be redirected to your specified with the following parameters appended:
- : Unique authorization identifier for this specific authorization session. Use this ID for subsequent API calls.
- : State parameter for request/response correlation (matches your original request)
- : Your application identifier
- : Authorization completion timestamp
For detailed workflow, please refer to: Merchant Self-serve Authorization"
HOST:
DIRECTION:
### Get Authorized Merchant Store List
- [GET /oauth/authorized/{authId}/merchantInfo](https://api-docs.mykeeta.com/apis/opendelivery/authentication/getmerchantinfo.md): Retrieves authorized merchant store list with basic store information and pagination data.
> Valid access token required to access this endpoint.
Returns all authorized store information for the specified authorization ID with pagination support.
> This endpoint is commonly used for functionality, allowing service providers to retrieve authorized store details and bind them to their own systems for shop onboarding.
HOST:
DIRECTION:
### Receive Authorization Status Change Notification
- [POST /webhook/authorization](https://api-docs.mykeeta.com/apis/opendelivery/authentication/receiveauthorizationwebhook.md):
This endpoint should be implemented by Software Services to receive authorization status change notifications from Keeta system.
> This is an endpoint you need to implement on your server.
You can log in to the Developer Portal, where there is a webhook configuration section. You can configure webhooks there.
Please focus only on the webhook configuration for Formal Store. 1301 represents the webhook for new authorization notifications, and 1302 represents the webhook for authorization cancellation notifications.
- Merchant adds new store authorization
- Merchant cancels store authorization
- HTTP POST
- application/json
- Recommended within 5 seconds
- Must return 200 for success
- JSON with code and message fields
- Use authId and opType to ensure operation idempotency
- Respond quickly, process business logic asynchronously
- Log all received notifications for troubleshooting
- Set up monitoring and alerting for webhook reception
HOST:
DIRECTION:
## └────► Merchant Endpoint
This section details the `GET /v1/merchant` endpoint.
This endpoint should be implemented by the Software Service and its URL should be informed to Keeta.
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.
### Register / Update Merchant endpoint info.
- [PUT /v1/merchantOnboarding](https://api-docs.mykeeta.com/apis/opendelivery/merchantendpoints/putmerchantonboarding.md): Register and update the Merchant endpoint GET /v1/merchant information in Keeta.
For the Software Service, .
To enable Keeta to identify which merchant needs to be registered,
the Software Service must include the in its requests.
Merchants can obtain this merchantId from the Keeta merchant portal.
> :
> 1. It is necessary to provide the Keeta merchant ID to ensure that the mapping between the merchant ID of Software Service and the merchantId of Keeta is accurate.
> 2. If an existing or under the App has been previously registered, any subsequent onboarding request containing these identifiers will result in the deletion of historical data and the creation of a new mapping configuration.
> 3. This enables Keeta to properly identify the merchantId in your system. Otherwise, no order events will be received via polling or webhook.
HOST:
DIRECTION:
### Get information of a Merchant
- [GET /v1/merchant](https://api-docs.mykeeta.com/apis/opendelivery/merchantendpoints/getmerchant.md): Endpoint to get data of a specific merchant, such as basic info, menus, and services.
- this endpoint can require an for authentication, and the Software Service that hosts the endpoint can decide whether it is needed.
- The Software Service can pass the data through the PUT /v1/merchantOnboarding endpoint.
>
HOST:
DIRECTION:
### New Merchant Update Notification
- [POST /v1/merchantUpdate/{merchantId}](https://api-docs.mykeeta.com/apis/opendelivery/merchantendpoints/merchantupdate.md):
>
Information about a update in the systems.
This endpoint can be used in the following ways:
This will force Keeta to make a new request to the GET /v1/merchant endpoint to update all the merchant information.
This will force the opening or closing of the merchant within Keeta, without forcing a new GET /v1/merchant call.
This will force Keeta to update only the sent objects, without forcing a new GET /v1/merchant call.
>
> 1- Please do not pass and & at the same time. When has a value, the request will be regarded as updating only merchant status, and & will be ignored.Please update merchant status and other entity separately.
> 2- When the field is populated, the field cannot be empty.
> 3- It is recommended not to pass an empty body, but to pass a specific entity to be updated to avoid invalid update operations.
> 4- An item must have either a delivery price or a pickup price. Currently, item with only price is not permitted.
> 5- The business status of a store is determined by many factors (business hours, number of items available for sale, merchant status, etc.).
HOST:
DIRECTION:
## └────► Polling
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 Keeta.
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.
> **IMPORTANT**: It is important that the Software Service performs the requests within the timeframe determined by Keeta, as blocking and penalties may occur depending on the application's rules.
**Keeta Polling Rate Limiting and Event TTL**
- The Keeta polling API enforces a rate limit of **no more than two requests per minute per token**. Once a request is blocked due to rate limiting, it will be allowed again in the next time window, which resets every minute.
- It is recommended to poll for the latest order events associated with the token **every 30 seconds**. **The TTL for order events is 4 hours and 10 minutes**. In the Keeta system, orders automatically transition to a final state after 4 hours; an additional 10 minutes is provided as a buffer for time discrepancies.
**Availability of new events in polling:**
- Keeta may have specific rules about the maximum time new events are available in polling before they are removed.
- Always check with Keeta what the rules are for using the polling service.
**Duplicate Events**
- Eventually Keeta 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**.
- 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**.
> **IMPORTANT**: The 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 Keeta can handle this situation in two different ways:
- As Keeta processes the requests synchronously, then Keeta should return `HTTP 422`, indicating that that event has been received before.
### Acknowledgment Events
When receiving new events via **Polling**, the Software Service should always send acknowledgement so that Keeta 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.
> - It is recommended that this be the default treatment for all events not yet mapped in the Software Service application.
> - The Software Services only needs to send acknowledgment of the event once.
> **IMPORTANT**: Acknowledgment NOT apply for WEBHOOKS.
### Get New Events
- [GET /v1/events:polling](https://api-docs.mykeeta.com/apis/opendelivery/orderspolling/pollingevents.md): 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.
> Important: The software service to register the store before calling this endpoint, otherwise the polling endpoint will not be able to obtain the events.
HOST:
DIRECTION:
### Acknowledge Events
- [POST /v1/events/acknowledgment](https://api-docs.mykeeta.com/apis/opendelivery/orderspolling/pollingacknowledgment.md): Acknowledge a set of events, dismissing them from future polling calls.
HOST:
DIRECTION:
## └────► Webhook
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 **Keeta**.
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 **Keeta** does not receive a `200` acknowledgement response, than the webhook event will be resent based on **Keeta** policies.
**Keeta Webhook Retry Policy**
The Keeta webhook retry policy is designed to ensure reliable delivery of webhook events. If the merchant **Software Service** does not acknowledge receipt of a webhook event with a `200` response, Keeta will retry sending the event up to 3 times. The retries will occur at intervals of 1 minute, 2 minutes and finally 3 minutes. If the merchant **Software Service** still does not acknowledge the event after these retries, the event will be considered undelivered.
### 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 **Keeta** |
| 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 Keeta. Webhooks requests contain an X-App-Signature header.
### New Order Event Notification
- [POST /v1/newEvent](https://api-docs.mykeeta.com/apis/opendelivery/orderswebhook/newevent.md): >
Information about a new event in the systems
HOST:
DIRECTION:
## └────► Order API
### Get Order Details
- [GET /v1/orders/{orderId}](https://api-docs.mykeeta.com/apis/opendelivery/orderapi/orderdetails.md): Endpoint to consult the details of an order.
HOST:
DIRECTION:
### Confirm
- [POST /v1/orders/{orderId}/confirm](https://api-docs.mykeeta.com/apis/opendelivery/orderapi/confirmorder.md): Informs that the order has been accepted and preparation will start soon.
> It is expected to receive a event after this action.
HOST:
DIRECTION:
### Ready For Pickup
- [POST /v1/orders/{orderId}/readyForPickup](https://api-docs.mykeeta.com/apis/opendelivery/orderapi/orderready.md): Informs that the order is ready for pickup.
> It is expected to receive a event after this action.
HOST:
DIRECTION:
### Request order cancellation
- [POST /v1/orders/{orderId}/requestCancellation](https://api-docs.mykeeta.com/apis/opendelivery/orderapi/requestcancellation.md): Request order cancellation to Keeta.
> It is expected to receive a event after this action.
HOST:
DIRECTION:
### Accept order refund
- [POST /v1/orders/{orderId}/acceptRefund](https://api-docs.mykeeta.com/apis/opendelivery/orderapi/acceptrefund.md): Informs Keeta that the refund request has been accepted and the order can be refunded.
> It is expected to receive a event after this action.
HOST:
DIRECTION:
### Deny order refund
- [POST /v1/orders/{orderId}/rejectRefund](https://api-docs.mykeeta.com/apis/opendelivery/orderapi/rejectrefund.md): Informs Keeta that the refund request has been denied and the order cannot be refunded.
> It is expected to receive a event after this action.
HOST:
DIRECTION:
### BatchDecrypt
- [POST /v1/batchDecrypt](https://api-docs.mykeeta.com/apis/opendelivery/orderapi/batchdecrypt.md): Call this endpoint to decrypt the encrypted data returned by the API.
> 1. For orders, this endpoint can be called to decrypt the user's phone number and address.
> 2. A maximum of data items can be decrypted at once.
> 3. The encrypted data generally uses as a prefix.
The following data returned by the order details endpoints will be encrypted data (ciphertext data prefixed with ):
> 1. customer.phone.number
> 2. delivery.deliveryAddress.district
> 3. delivery.deliveryAddress.number
> 4. delivery.deliveryAddress.complement
> 5. delivery.deliveryAddress.formattedAddress
## └────► Merchant Fulfill API
The endpoint below should be used **when the order logistics service is provided by the Merchant** and is only available for updates **after the merchant accepts the order**. Orders that are completed or cancelled cannot be updated.
### Dispatch
- [POST /v1/orders/{orderId}/dispatch](https://api-docs.mykeeta.com/apis/opendelivery/merchantfulfillapi/dispatchorder.md): Informs that the order has been dispatched.
> It is expected to receive a event after this action.
This endpoint should be sent .
HOST:
DIRECTION:
### Delivered (Optional)
- [POST /v1/orders/{orderId}/delivered](https://api-docs.mykeeta.com/apis/opendelivery/merchantfulfillapi/orderdelivered.md): Informs that the order has been delivered.
> It is expected to receive a event after this action.
This endpoint is not mandatory and should be sent .
HOST:
DIRECTION:
### Send Delivery Updates (Optional)
- [POST /v1/orders/{orderId}/tracking](https://api-docs.mykeeta.com/apis/opendelivery/merchantfulfillapi/senddeliveryupdates.md): Sends information about the delivery in progress.
HOST:
DIRECTION:
