# Keeta Open Delivery API Version: v.1.0.7 ## 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/_bundle/apis/@opendelivery/opendelivery.yaml) ## Authentication ### 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. If you have completed the development in full compliance with the Open Delivery native protocol's grant_type=client_credentials, please contact Keeta. If you have already completed development using grant_type=client_credentials and have passed SIT certification or are already in production, you can continue to use grant_type=client_credentials without any impact. > IMPORTANT: The Software Service must obtain the merchant’s authorization before accessing their data. ##### APP Level Token mode 1. Application-level access_token: The access_token can be used to access all stores authorized 2. grant_type = app_level_token: Generate and refresh access_token ##### Shop Level Authorization Code mode 1. Store-level access_token: The access_token can be used to access one store authorized 2. grant_type = shop_level_authorization_code: Use authorization_code to generate access_token, and return refresh_token for subsequent refresh 3. grant_type = refresh_token: Use this parameter to refresh a new access_token and refresh_token, before the old access_token expires. HOST: Keeta 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. > NOTE: 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" Authorization Flow: If Software Services wants merchants to be redirected to your own page after authorization, you can set the redirectUri parameter accordingly. When the merchant completes authorization, they will be redirected to your specified redirectUri with the following parameters appended: redirectUri?authId=authId&state=%s&appId=%s×tamp=%s&keetaMerchantId=%s&code=%s Parameter definitions: - authId: Unique authorization identifier for this specific authorization session. Use this ID for subsequent API calls. - state: State parameter for request/response correlation (matches your original request) - appId: Your application identifier - timestamp: Authorization completion timestamp - keetaMerchantId: The merchant ID generated by Keeta, only returned when the application is in shop_level_authorization_code mode - code: The authorization code generated by Keeta, only returned when the application is in shop_level_authorization_code mode For detailed workflow, please refer to: Merchant Self-serve Authorization HOST: Keeta 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. > IMPORTANT: Valid access token required to access this endpoint. Returns all authorized store information for the specified authorization ID with pagination support. > USE CASE: This endpoint is commonly used for store binding functionality, allowing service providers to retrieve authorized store details and bind them to their own systems for shop onboarding. HOST: Keeta DIRECTION: ### Receive Authorization Status Change Notification - [POST /webhook/authorization](https://api-docs.mykeeta.com/apis/opendelivery/authentication/receiveauthorizationwebhook.md): Webhook Endpoint for Software Services This endpoint should be implemented by Software Services to receive authorization status change notifications from Keeta system. > IMPORTANT: This is an endpoint you need to implement on your server. How to configure webhooks 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. Notification Triggers: - Merchant adds new store authorization - Merchant cancels store authorization Technical Requirements: - Method: HTTP POST - Content-Type: application/json - Response Time: Recommended within 5 seconds - HTTP Status: Must return 200 for success - Response Format: JSON with code and message fields Best Practices: - Idempotency: Use authId and opType to ensure operation idempotency - Async Processing: Respond quickly, process business logic asynchronously - Logging: Log all received notifications for troubleshooting - Monitoring: Set up monitoring and alerting for webhook reception HOST: Service Provider DIRECTION: ## 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, all authorized merchant will use the same token. To enable Keeta to identify which merchant needs to be registered, the Software Service must include the Keeta merchant ID in its requests. The Software Service should also save the mapping relationship between the Keeta merchant ID and its own merchant ID in the system. Merchants can obtain this merchantId from the Keeta merchant portal. > IMPORTANT: > 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 Keeta MerchantId or External MerchantId 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. Store registration via onboarding endpoint must be completed prior to order flow integration. This enables Keeta to properly identify the merchantId in your system. Otherwise, no order events will be received via polling or webhook. HOST: Keeta 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 optionally require an apiKey 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. - 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. > An item must have either a delivery price or a pickup price. Currently, item with only indoor price is not permitted. HOST: SOFTWARE SERVICE DIRECTION: ### New Merchant Update Notification - [POST /v1/merchantUpdate/{merchantId}](https://api-docs.mykeeta.com/apis/opendelivery/merchantendpoints/merchantupdate.md): > POST /v1/merchantUpdate/{merchantId} 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 Keeta to make a new request to the GET /v1/merchant 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 Keeta, without forcing a new GET /v1/merchant call. 3 - Sent with only the entityType and updatedObjects fields: This will force Keeta to update only the sent objects, without forcing a new GET /v1/merchant call. > IMPORTANT: > 1- Please do not pass merchantStatus and entityType&updatedObjects at the same time. When merchantStatus has a value, the request will be regarded as updating only merchant status, and entityType&updatedObjects will be ignored.Please update merchant status and other entity separately. > 2- When the entityType field is populated, the updatedObjects 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 indoor 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.). > 6- Please do note that the number of available Options under the Option Group must meet the Option Group's minPermitted requirement. If not, the Option Group will become unfufillable, causing all items using this Option Group to be hidden on the APP. HOST: Keeta DIRECTION: ### Get Merchant Status and Service Hours - [GET /v1/merchant/{id}/status](https://api-docs.mykeeta.com/apis/opendelivery/merchantendpoints/merchantstatus.md): > Get /v1/merchant/{id}/status Return the merchant status, service hours(serviceHours), and sourceAppId. HOST: Keeta DIRECTION: ### Image Upload - [POST /v1/merchant/image/upload](https://api-docs.mykeeta.com/apis/opendelivery/merchantendpoints/imageupload.md): This endpoint allows merchants to upload images to the Keeta platform. The returned image URL can be used during menu synchronization. ## Order-Polling ### 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 must first call the Merchant Onboarding endpoint to register the store before calling this endpoint, otherwise the polling endpoint will not be able to obtain the events. HOST: Keeta 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: Keeta DIRECTION: ## Order-Webhook ### New Order Event Notification - [POST /v1/newEvent](https://api-docs.mykeeta.com/apis/opendelivery/orderswebhook/newevent.md): > POST /v1/newEvent Information about a new event in the systems HOST: SOFTWARE SERVICE DIRECTION: ## Order-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: Keeta DIRECTION: ### Confirm - [POST /v1/orders/{orderId}/confirm](https://api-docs.mykeeta.com/apis/opendelivery/orderapi/confirmorder.md): Informs Keeta that the order has been accepted and preparation will start soon. > It is expected to receive a CONFIRMED event after this action. HOST: Keeta DIRECTION: ### Ready For Pickup - [POST /v1/orders/{orderId}/readyForPickup](https://api-docs.mykeeta.com/apis/opendelivery/orderapi/orderready.md): Informs Keeta that the order is ready for pickup. > It is expected to receive a READY_FOR_PICKUP event after this action. HOST: Keeta 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 CANCELLATION_REQUESTED event after this action. HOST: Keeta 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 REFUNDED event after this action. HOST: Keeta 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 REFUND_FAILED event after this action. HOST: Keeta 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 merchant self-delivery or third-party logistics (3PL) orders, this endpoint can be called to decrypt the user's phone number and address. > 2. A maximum of 50 data items can be decrypted at once. > 3. The encrypted data generally uses ENC_ as a prefix. The following data returned by the order details endpoints will be encrypted data (ciphertext data prefixed with ENC_): > 1. customer.​phone.​number > 2. delivery.​deliveryAddress.​district > 3. delivery.​deliveryAddress.​number > 4. delivery.​deliveryAddress.complement > 5. delivery.​deliveryAddress.​formattedAddress ## Order-Merchant Fulfill API ### Dispatch - [POST /v1/orders/{orderId}/dispatch](https://api-docs.mykeeta.com/apis/opendelivery/merchantfulfillapi/dispatchorder.md): Informs Keeta that the order has been dispatched. > It is expected to receive a DISPATCHED event after this action. Important: This endpoint should be sent only in cases where the order logistics service is provided by the Merchant and not the Marketplace. HOST: Keeta DIRECTION: ### Delivered - [POST /v1/orders/{orderId}/delivered](https://api-docs.mykeeta.com/apis/opendelivery/merchantfulfillapi/orderdelivered.md): Informs Keeta 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. HOST: Keeta DIRECTION: ### Send Delivery Updates - [POST /v1/orders/{orderId}/tracking](https://api-docs.mykeeta.com/apis/opendelivery/merchantfulfillapi/senddeliveryupdates.md): 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. HOST: Keeta DIRECTION: