# 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 <TOKEN>' 
 https://{baseURL}/v1/events:polling
```
> Refresh Token is not available at this version.

Type: oauth2
Token URL: oauth/token
Scopes:
- `od.all`: Access to all **Open Delivery** APIs

### 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/@l10n/en/apis/@opendelivery/opendelivery.yaml)

## Authentication

 - [POST /oauth/token](https://api-docs.mykeeta.com/en/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`, pleas
 - [GET /oauth/authorization/url](https://api-docs.mykeeta.com/en/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 mer
 - [GET /oauth/authorized/{authId}/merchantInfo](https://api-docs.mykeeta.com/en/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 informati
 - [POST /webhook/authorization](https://api-docs.mykeeta.com/en/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
## Merchant

 - [PUT /v1/merchantOnboarding](https://api-docs.mykeeta.com/en/apis/opendelivery/merchantendpoints/putmerchantonboarding.md): Register and update the Merchant endpoint [GET /v1/merchant](#operation/getMerchant) information in Keeta. For the Software Service, **all authorized merchant will use the same token**. To enable Ke
 - [GET /v1/merchant](https://api-docs.mykeeta.com/en/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
 - [POST /v1/merchantUpdate/{merchantId}](https://api-docs.mykeeta.com/en/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
 - [GET /v1/merchant/{id}/status](https://api-docs.mykeeta.com/en/apis/opendelivery/merchantendpoints/merchantstatus.md): > **Get /v1/merchant/{id}/status** Return the merchant status, service hours(serviceHours), and sourceAppId. HOST: **Keeta** DIRECTION:
 - [POST /v1/merchant/image/upload](https://api-docs.mykeeta.com/en/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 /v1/events:polling](https://api-docs.mykeeta.com/en/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 fu
 - [POST /v1/events/acknowledgment](https://api-docs.mykeeta.com/en/apis/opendelivery/orderspolling/pollingacknowledgment.md): Acknowledge a set of events, dismissing them from future polling calls. HOST: **Keeta** DIRECTION:
## Order-Webhook

 - [POST /v1/newEvent](https://api-docs.mykeeta.com/en/apis/opendelivery/orderswebhook/newevent.md): > **POST /v1/newEvent** Information about a new event in the systems HOST: **SOFTWARE SERVICE** DIRECTION:
## Order-Order API

 - [GET /v1/orders/{orderId}](https://api-docs.mykeeta.com/en/apis/opendelivery/orderapi/orderdetails.md): Endpoint to consult the details of an order. HOST: **Keeta** DIRECTION:
 - [POST /v1/orders/{orderId}/confirm](https://api-docs.mykeeta.com/en/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:
 - [POST /v1/orders/{orderId}/readyForPickup](https://api-docs.mykeeta.com/en/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:
 - [POST /v1/orders/{orderId}/requestCancellation](https://api-docs.mykeeta.com/en/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:
 - [POST /v1/orders/{orderId}/acceptRefund](https://api-docs.mykeeta.com/en/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:
 - [POST /v1/orders/{orderId}/rejectRefund](https://api-docs.mykeeta.com/en/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:
 - [POST /v1/batchDecrypt](https://api-docs.mykeeta.com/en/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 phon
## Order-Merchant Fulfill API

 - [POST /v1/orders/{orderId}/dispatch](https://api-docs.mykeeta.com/en/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
 - [POST /v1/orders/{orderId}/delivered](https://api-docs.mykeeta.com/en/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
 - [POST /v1/orders/{orderId}/tracking](https://api-docs.mykeeta.com/en/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 th
