Keeta Open Delivery API (v.1.0.6)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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. 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. 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.

Preparation Phase

1. NDA

Please contact the Keeta team to sign the NDA (Non-disclosure Agreement).

2. 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.

3. Set up test store and Keeta test APP

1. a. Please log in to the Dev Portal and use the Test Store Tool to create a test store.
2. 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.
3. 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.
4. d. For instructions on using test store in Keeta test APP, click here .
5. 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

1. 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).

2. 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.

3. 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

1. 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).

2. 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

1. 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.

• 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 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 endpoint.

• Place a Test Order

  Once the store mapping has been successfully configured, refer to the 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, and then either confirm or cancel the order.

  Once the order is prepared, you must either mark it as ready or dispatch it — 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.

• 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 section for the complete algorithm specification.

• PARAMETERS IN Keeta (Keeta --> SOFTWARE SERVICE)

  • GET /merchant 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.

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

1. 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.
2. 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.
3. 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.
4. 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.

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.

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:

1. Tap the address in the top-right corner of the screen.
2. Select “Tap to Change.”
3. Tap the top-right region selector (e.g., “Brasil”).
4. Choose the first option: “Bongolava”, then tap “Confirm.”
5. 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.

1. Time Zone Conversion Target Object

• Get information of a Merchant
  • services.serviceHours
  • availabilities
• New Merchant Update Notification
  • services.serviceHours
  • availabilities
• Get Merchant Status and Service Hours
  • services.serviceHours

2. Time Zone Conversion Rules

3. Time Zone Conversion Examples

Take Brazil's official time zone UTC-3 as an example.

3.1 [ data + timePeriod ] combination scenario

(1) The conversion to UTC+0 will not cross the day

[
  {
    "date": "2021-04-07",
    "timePeriods": {
        "startTime": "11:00:00.000Z",
        "endTime": "23:00:00.000Z"
    }
  }
]

(2) The conversion to UTC+0 will cross the day

[
  {
    "date": "2021-04-07",
    "timePeriods": {
        "startTime": "13:00:00.000Z",
        "endTime": "23:59:00.000Z"
    }
  },
  {
    "date": "2021-04-08",
    "timePeriods": {
        "startTime": "00:00:00.000Z",
        "endTime": "01:00:00.000Z"
    }
  }
]

3.2 [ dayOfWeek + timePeriod ] combination scenario

(1) The conversion to UTC+0 will not cross the day

[
  {
    "dayOfWeek": [
        "MONDAY",
        "TUESDAY"
    ],
    "timePeriods": {
        "startTime": "11:00:00.000Z",
        "endTime": "23:00:00.000Z"
    }
  }
]

(2) The conversion to UTC+0 will cross the day

[
  {
    "dayOfWeek": [
        "MONDAY"
    ],
    "timePeriods": {
        "startTime": "11:00:00.000Z",
        "endTime": "23:59:00.000Z"
    }
  },
  {
    "dayOfWeek": [
        "TUESDAY"
    ],
    "timePeriods": {
        "startTime": "00:00:00.000Z",
        "endTime": "01:00:00.000Z"
    }
  },
  {
    "dayOfWeek": [
        "TUESDAY"
    ],
    "timePeriods": {
        "startTime": "11:00:00.000Z",
        "endTime": "23:59:00.000Z"
    }
  },
  {
    "dayOfWeek": [
        "WEDNESDAY"
    ],
    "timePeriods": {
        "startTime": "00:00:00.000Z",
        "endTime": "01:00:00.000Z"
    }
  }
]

Finally merge into:

[
  {
    "dayOfWeek": [
        "MONDAY",
        "TUESDAY"
    ],
    "timePeriods": {
        "startTime": "11:00:00.000Z",
        "endTime": "23:59:00.000Z"
    }
  },
  {
    "dayOfWeek": [
        "TUESDAY",
        "WEDNESDAY"
    ],
    "timePeriods": {
        "startTime": "00:00:00.000Z",
        "endTime": "01:00:00.000Z"
    }
  }
]

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:

1. Enter the APP ID of the service provider's application (available from the provider).
2. Confirm provider information to ensure accuracy.
3. 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.
4. Click Confirm to proceed.
5. Copy authorization code(Optional) If the application you are about to authorize is an application in shop level authorization code mode, You will see the authorization_code on the page. Please copy this code and give it to the software service to complete the authorization process.
6. Click "Registro da autorização" to automatically download an Excel file containing the authorization record
7. 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.

1. The merchant opens the URL and logs in using either a brand-level or store-level account.
2. The merchant does not need to input an APP ID—simply select the stores to authorize, and click Confirm.
3. Copy authorization code(Optional) If the application you are about to authorize is an application in shop level authorization code mode, You will see the authorization_code on the page. Please copy this code and give it to the software service to complete the authorization process.
4. Click “Registro da autorização” to automatically download an Excel record of the authorization.
5. 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:

1. Bulk revocation:

   Select the current list of stores and revoke authorization in a batch. A double-confirmation popup is required before the operation proceeds.

2. Single revocation:

   Click the designated button and confirm to revoke authorization for an individual store.

Upon completion:

1. An Excel file containing the operation record will be automatically downloaded for reference.
2. The service provider's merchant operations email will receive a notification.
3. The provider's system will receive a Webhook event.
4. 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.

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

• Initiate Request: The service provider system calls the Keeta API to retrieve the authorization URL.

  Note: If API integration is not available, the URL can be manually acquired via the Add Authorization button on the Dev Portal.

• Generate Link: Keeta returns an authorization link containing the required parameters.
• Distribute Link: The service provider shares the link with the target merchant to begin the authorization flow.

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.

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.