The API endpoints are developed around RESTful principles secure via the OAuth2.0 protocol.
Beyond the entry points, the API also provides a line of communication into your system via webhooks.
For testing purposes, we offer a staging environment. Also, more detailed information about the business rules and workflows can be found on the Documentation Section
Each API is versioned individually, but we follow these rules:
- Non breaking changes (eg: adding new fields) are added in the current version without previous communication
- Breaking changes (fields removal, semantic changed or schema update) have the version incremented
- Users will be notified about new versions and will be given time to migrate (the time will be set on a case by case)
- Once users migrate to the new version, we will deprecate the old ones
- Once there is a new version for an API, we won't accept new integrations targeting old versions
The APIs use resource-oriented URLs communicating, primarily, via JSON and leveraging the HTTP headers, response status codes, and verbs.
To exemplify how the API is to be consumed, consider a fake GET resource endpoint invocation below:
curl --request GET 'https://{{public-api-url}}/v1/resource/123' \\
--header 'Authorization: Bearer 34fdabeeafds=' --header 'X-Store-Id: 321' --header 'X-Application-Id: e22f94b3-967c-4e26-bf39-9e364066b68b'
Header | Description |
---|---|
Authorization |
Standard HTTP header is used to associate the request with the originating invoker. The content of this header is a Bearer token generated from you client_secret, defined in the API Auth guide. |
X-Application-Id |
The plain-text Application Id , provided at onboarding. |
X-Store-Id |
The ID of the store in your system this call acts on behalf of. |
All resource endpoints expect the Authorization
and X-Application-Id
header, the remaining headers are explicitly stated in the individual endpoint documentation section.
With these headers, the system will:
- Validate the client token, making sure the call is originating from a trusted source.
- Validate that the Application has the permission to access the
v1/resource/{id}
resource via the Application's pre-configured scopes. - Translate your X-Store-Id to our internal store ID (e.g.
AAA
). - Validate and retrieve resource
AAA
, that is associated to your Application via store id321
.
POST/PUT methods will look similar to the GET calls, but they'll take in a body in the HTTP request (default to the application/json content-type).
curl --location --request POST 'https://{{public-api-url}}/v1/resource' \\
--header 'Authorization: Bearer 34fdabeeafds=' --header 'X-Store-Id: 321' --header 'X-Application-Id: e22f94b3-967c-4e26-bf39-9e364066b68b\"
--data '{\"foo\": \"bar\"}'
The Authorization API is based on the OAuth2.0 protocol, using the client credentials grant. Resources expect a valid token sent as a Bearer
token in the HTTP Authorization
header.
To generate the token, use the Application ID
and Client Secret
(provided during onboarding) to the Token Auth endpoint endpoint. The result of this invocation is a token that is valid for a pre-determined time or until it is manually revoked.
The response of the following endpoints will return a token that will be sent as a Bearer
value of the Authorization
HTTP header, along with meta information such as expiry-date.
Note that the referred client_id
is the Application ID
because though we chose adhere to the OAuth2.0 standard for the auth APIs.
The API exposes a token generation endpoint expects your client_id and client_secret to be formatted as application/x-www-form-urlencoded content type.
curl --location --request POST 'https://{{public-api-url}}/v1/auth/token' \\
--header 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'scope=ping' \\
--data-urlencode 'grant_type=client_credentials' \\
--data-urlencode 'client_id=[APPLICATION_ID]' \\
--data-urlencode 'client_secret=[CLIENT_SECRET]'
Alternatively, the API also accepts a Basic
Authorization header with the Base64 encoding of the client_id
(Application ID
) and client_secret
joined by a single colon :
.
BASE64_ENCODED_CREDENTIALS = base64_encode(client_id + \":\" + client_secret)
curl --location --request POST 'https://{{public-api-url}}/v1/auth/token' \\
--header 'Authorization: Basic [BASE64_ENCODED_CREDENTIALS]' \\
--header 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'scope=ping' \\
--data-urlencode 'grant_type=client_credentials'
The Public API is able to send notifications to your system via HTTP POST requests.
Every webhook is signed using HMAC-SHA256 that is present in the header X-HMAC-SHA256
, and you can also authenticate the requests using Basic Auth, Bearer Token or HMAC-SHA1 (legacy). Please, refer to Webhook Authentication Guide for more details.
Please work with your Account Representative to setup your Application's Webhook configurations.
Example Base-URL = https://{{your-server-url}}/webhook
Name | Type | Description |
---|---|---|
eventId | string | Unique id of the event. |
eventTime | string | The time the event occurred. |
eventType | string | The type of event (e.g. create_order). |
metadata.storeId | string | Id of the store for which the event is being published. |
metadata.applicationId | string | Id of the application for which the event is being published. |
metadata.resourceId | string | The external identifier of the resource that this event refers to. |
metadata.resourceHref | string | The endpoint to fetch the details of the resource. |
metadata.payload | object | The event object which will be detailed in each Webhook description. |
curl --location --request POST 'https://{{your-server-url}}/webhook' \\
--header 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36' \\
--header 'Authorization: MAC <hash signature>' \\
--header 'Content-Type: application/json' \\
--data-raw '{
\"eventId\": \"123456\",
\"eventTime\": \"2020-10-10T20:06:02:123Z\",
\"eventType\": \"orders.new_order\",
\"metadata\": {
\"storeId\": \"755fd19a-7562-487a-b615-171a9f89d669\",
\"applicationId\": \"e22f94b3-967c-4e26-bf39-9e364066b68b\",
\"resourceHref\": \"https://{{public-api-url}}/v1/orders/bf9f1d81-f213-496e-a026-91b6af44996c\",
\"resourceId\": \"bf9f1d81-f213-496e-a026-91b6af44996c\",
\"payload\": {}
}
}
The partner application should return an HTTP 200 response code with an empty response body to acknowledge receipt of the webhook event.
Please, refer to Rate Limiting Guide for more details.
PHP 7.4 and later. Should also work with PHP 8.0.
To install the bindings via Composer, add the following to composer.json
:
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git"
}
],
"require": {
"GIT_USER_ID/GIT_REPO_ID": "*@dev"
}
}
Then run composer install
Download the files and include autoload.php
:
<?php
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');
Please follow the installation procedure and then run the following:
<?php
require_once(__DIR__ . '/vendor/autoload.php');
$apiInstance = new OpenAPI\Client\Api\AuthEndpointsApi(
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
// This is optional, `GuzzleHttp\Client` will be used as default.
new GuzzleHttp\Client()
);
$grant_type = 'grant_type_example'; // string | The OAuth2.0 grant types supported.
$scope = 'scope_example'; // string | The scope to request, multiple scopes are passed delimited by a space character.
$client_id = 'client_id_example'; // string | The ID of the client (also known as the Application ID).
$client_secret = 'client_secret_example'; // string | The secret of the client.
try {
$result = $apiInstance->requestToken($grant_type, $scope, $client_id, $client_secret);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling AuthEndpointsApi->requestToken: ', $e->getMessage(), PHP_EOL;
}
All URIs are relative to https://}
Class | Method | HTTP request | Description |
---|---|---|---|
AuthEndpointsApi | requestToken | POST /v1/auth/token | Generate token |
CallbackEndpointsApi | publishError | POST /v1/callback/error | Publish callback error |
DeliveryEndpointsApi | acceptDeliveryCallback | POST /v1/delivery/{deliveryReferenceId}/accept | Notify the result of an accept delivery event |
DeliveryEndpointsApi | cancelDeliveryCallback | POST /v1/delivery/{deliveryReferenceId}/cancel | Notify the result of a cancel delivery event |
DeliveryEndpointsApi | deliveryCallbackError | POST /v1/delivery/callback/error | Publish delivery callback error |
DeliveryEndpointsApi | requestDeliveryQuoteCallback | POST /v1/delivery/{deliveryReferenceId}/quotes | Notify the result of a request delivery quote event |
DeliveryEndpointsApi | updateDeliveryStatus | PUT /v1/delivery/{deliveryReferenceId}/status | Update delivery status |
FinanceEndpointsApi | postFinancialTransactions | POST /finance/v1/financial-transactions | Post financial transactions |
ManagerMenuEndpointsApi | managerGetMenuPublishTargets | GET /manager/menu/v1/menus/publish-targets | Get the publish-targets for a store |
ManagerMenuEndpointsApi | managerPublishMenu | POST /manager/menu/v1/menus/publish | Publish menus to targets for a store |
ManagerMenuEndpointsApi | managerSuspendMenuEntities | POST /manager/menu/v1/menus/entities/availability/suspend | Suspend menu entities targets for a store |
ManagerMenuEndpointsApi | managerUnsuspendMenuEntities | POST /manager/menu/v1/menus/entities/availability/unsuspend | Unsuspend menu entities targets for a store |
ManagerOrderEndpointsApi | getManagerOrder | GET /manager/order/v1/sources/{source}/orders/{orderId} | Fetch order with Manager Info |
ManagerOrderEndpointsApi | managerGetOrderFeed | GET /manager/order/v1/orders | Fetch order feed for a store |
ManagerOrderEndpointsApi | markAsFulfilled | POST /manager/order/v1/sources/{source}/orders/{orderId}/fulfill | Mark an order as fulfilled. |
ManagerOrderEndpointsApi | markAsReadyToPickup | POST /manager/order/v1/sources/{source}/orders/{orderId}/ready-to-pickup | Mark an order as ready to pickup |
ManagerOrderEndpointsApi | requestOrderCancelation | POST /manager/order/v1/sources/{source}/orders/{orderId}/cancel | Request order cancelation |
ManagerOrderEndpointsApi | requestOrderConfirmation | POST /manager/order/v1/sources/{source}/orders/{orderId}/confirm | Request order confirmation |
ManagerOrderEndpointsApi | requestOrderReInjection | POST /manager/order/v1/sources/{source}/orders/{orderId}/re-inject | Request order re-injection |
MenusEndpointsApi | getAsyncJobStatus | GET /v1/menus/jobs/{jobId} | Get the async menu job status |
MenusEndpointsApi | getMenu | GET /v1/menus | Get the menus for a store |
MenusEndpointsApi | getMenuPublishTargets | GET /v1/menus/pos/publish/targets | DEPRECATED - Get the MenuPublishTargets for a store |
MenusEndpointsApi | menuPublishCallback | POST /v1/menus/publish | Notify the result of a Publish Menu event |
MenusEndpointsApi | menuSendCallback | POST /v1/menus/current | Notify the result of a Send Menu event |
MenusEndpointsApi | menuUpsertHours | POST /v1/menus/hours | Notify the receival of a Upsert Hours Menu event |
MenusEndpointsApi | publishMenu | POST /v1/menus/pos/publish | DEPRECATED - Publish menus to targets for a store |
MenusEndpointsApi | suspendMenuEntities | POST /v1/menus/pos/entity/availability/suspend | DEPRECATED - Suspend menu entities targets for a store |
MenusEndpointsApi | unsuspendMenuEntities | POST /v1/menus/pos/entity/availability/unsuspend | DEPRECATED - Unsuspend menu entities targets for a store |
MenusEndpointsApi | updateMenuEntitiesAvailabilitiesCallback | POST /v1/menus/entity/availability/bulk | Notify the result of a Update Menu Entities Availabilities event |
MenusEndpointsApi | upsertMenu | POST /v1/menus | Upsert menus for a store |
OrdersEndpointsApi | createOrder | POST /v1/orders | Create order |
OrdersEndpointsApi | getOrderFeed | GET /v1/orders/feed | DEPRECATED - Fetch order feed for a store |
OrdersEndpointsApi | getPosOrder | GET /v1/orders/{orderId}/{source}/pos | DEPRECATED - Fetch order with POS Info |
OrdersEndpointsApi | posUpdateOrder | POST /v1/orders/status | DEPRECATED - Update order status |
OrdersEndpointsApi | updateOrder | PUT /v1/orders/{orderId} | Update order |
OrdersEndpointsApi | updateOrderCustomerPayment | PUT /v1/orders/{orderId}/payments | Update order customer payment |
OrdersEndpointsApi | updateOrderDeliveryInfo | PUT /v1/orders/{orderId}/delivery | Update order delivery information |
OrdersEndpointsApi | updateOrderStatus | POST /v1/orders/{orderId}/status | Update order status |
PingEndpointsApi | ping | GET /v1/ping | Ping the system |
ReportsEndpointsApi | generateReport | POST /v1/reports | Request a business report for a store |
StorefrontEndpointsApi | postPauseStoreEventResult | POST /v1/storefront/pause | Notify the result of a pause request event |
StorefrontEndpointsApi | postStoreAvailabilityChange | POST /v1/storefront/availability | Notify about store availability change |
StorefrontEndpointsApi | postStoreHoursConfigurationChange | POST /v1/storefront/hours | Notify about store hours configuration change |
StorefrontEndpointsApi | postUnpauseStoreEventResult | POST /v1/storefront/unpause | Notify the result of an unpause request event |
StoresEndpointsApi | updateStoreStatusEndpoint | PUT /v1/stores/status | Update Store Status |
StoresEndpointsApi | upsertStorelinkEventResultEndpoint | POST /v1/stores | Complete Store Onboarding |
- AcceptDeliveryCallbackRequest
- AcceptDeliveryEvent
- AcceptDeliveryRequest
- AdditionalCharge
- Address
- AllergenClassification
- BulkUpdateItemStatus
- CancelDeliveryCallbackRequest
- CancelDeliveryEvent
- CancelDeliveryResponse
- CaptchaRequest
- CaptchaSolution
- Category
- CompositeFinanceLine
- Courier
- CustomerPayment
- CustomerPaymentV2
- CustomerTip
- DeliveryCost
- DeliveryInfo
- DeliveryQuote
- DeliveryQuoteOptions
- DeliveryStatus
- DeliveryStatusUpdateEvent
- DeliveryStatusUpdateRequest
- DietaryClassification
- Distance
- EnergyKcal
- EntityPathOverrideRule
- EntityPathOverrideRuleAllOf
- ErrorDetail
- ErrorMessage
- EventCallbackError
- EventNotification
- EventNotificationBase
- EventNotificationNoPayload
- EventNotificationNoPayloadAllOf
- EventResultMetadata
- FinancialData
- FinancialTransaction
- FulfilledCredential
- FulfillmentInfo
- FulfillmentModeOverrideRule
- FulfillmentModeOverrideRuleAllOf
- FulfillmentPathEntity
- GenerateReportRequest
- GenerateReportResponse
- HourInterval
- Hours
- HoursData
- HydraToken
- IntentToCancelEvent
- Item
- Item2
- ItemModifier
- ItemPriceOverride
- ItemSelector
- ItemStatus
- ItemTax
- ItemUpdateRequest
- JobReference
- Location
- ManagerCancelOrderRequest
- ManagerConfirmOrderRequest
- ManagerItemIssue
- ManagerItemIssues
- ManagerOrderCancelDetails
- ManagerOrderIssue
- ManagerOrderIssues
- Menu3PD
- MenuAsynchronousJob
- MenuData
- MenuItem3PD
- MenuItemPOS
- MenuPOS
- MenuPublishEvent
- MenuPublishJobState
- MenuPublishRequest
- MenuPublishResponse
- MenuPublishResponseMenuPublishTargets
- MenuPublishTarget
- MenuPublishTargets
- Menus
- MenusUpsertRequest
- MetadataObject
- MetadataObjectNoPayload
- ModifierGroup
- ModifierGroupUpdateRequest
- ModifierItem
- Money
- NutritionalInfo
- OptionalStoreIdInMetadata
- OptionalStoreIdInMetadataMetadata
- Order
- OrderCustomerPaymentUpdateRequest
- OrderDeliveryInfoUpdateRequest
- OrderExternalIdentifiers
- OrderFeed
- OrderIdentifier
- OrderIdentifierFinance
- OrderItemInformation
- OrderItemIssue
- OrderReference
- OrderStatusEvent
- OrderStatusHistory
- OrderStatusHistoryOrderAcceptedInfo
- OrderStatusUpdateRequest
- OrderTotal
- OrderTotalV2
- OrderWithManagerInfo
- OrderWithPosInfo
- OverrideRule
- OverrideRule3PD
- POSCancelOrderRequest
- POSConfirmOrderRequest
- POSFeedDelivery
- POSOrderStatusUpdateRequest
- POSReInjectionRequest
- PauseStoreEventResult
- Payout
- PayoutInfo
- PercentageValue
- Person
- PersonalIdentifiers
- Photo
- PingEvent
- PongObject
- PosItemIssue
- PosItemIssues
- PosOrderCancelDetails
- PosOrderIssue
- PosOrderIssues
- PriceOverride
- RegularHours
- ReportGeneratedEvent
- RequestDeliveryQuoteCallbackRequest
- RequestDeliveryQuoteEvent
- RequiredAddress
- RequiredDeliveryInfo
- RequiredEventResultMetadata
- RequiredPerson
- SendMenuEventCallback
- ServiceProviderCharge
- Servings
- SimpleFinanceLine
- SkuBarcode
- SkuDetails
- SpecialHours
- Store
- StoreAvailabilityEventResult
- StoreHours
- StoreHoursConfiguration
- StoreHoursConfigurationEventResult
- StoreInfo
- StorefrontRegularHours
- StorefrontSpecialHours
- StorefrontTimeRange
- SuspendItemsRequest
- SuspensionStatus
- TimeRange
- UnpauseStoreEventResult
- UnsuspendItemsRequest
- UpdateItemStatusEntry
- UpdateStorelinkStatusRequest
- UpsertFullMenuEventCallback
- UpsertHoursEvent
- UpsertStorelinkEvent
- UpsertStorelinkEventResultRequest
- UpsertStorelinkEventResultRequestErrorMessage
- VehicleInformation
- ViewCredential
- ViewCredentialsArray
- Type:
OAuth
- Flow:
application
- Authorization URL: ``
- Scopes:
- menus.publish: Token has permission to notify the result of a publish menus operation for a given store.
- menus.get_current: Token has permission to send the current state of a menu, after being requested by a webhook event.
- menus.upsert_hours: Token has permission to notify the receiving of the upsert hours menu event, after being requested by a webhook event.
- menus.pos_publish: Token has permission to read available integration targets and to publish complete menus for selected integration targets.
- menus.async_job.read: Token has permission to read the status of a menu upsert job.
- menus.entity_suspension: Token has permission to notify the result of a menu entity availability update, after being requested by a webhook event.
- menus.read: Token has permission to read the current menus for a given store.
- menus.upsert: Token has permission to create/update menus for a given store.
- orders.customer_payment_update: Token has permission to update customer’s payment information for a previously created order for a given store.
- orders.delivery_info_update: Token has permission to update delivery information for a previously created order.
- orders.status_update: Token has permission to update the order status for a previously created order.
- orders.create: Token has permission to create new order for a given store.
- orders.update: Token has permission to create and update new orders for a given store.
- ping: Token has permission to ping the system.
- reports.generate_report: Token has permission to request reports for a given store and period of time.
- storefront.store_pause_unpause: Token has permission to notify the result of a pause/unpause operation, after being requested by a webhook event.
- storefront.store_availability: Token has permission to send the current state of store.
- storefront.store_hours_configuration: Token has permission to send the current store hours configuration.
- delivery.provider: Token has permission to send the delivery operation result.
- callback.error.write: Token has permission to send failed webhook event results.
- stores.manage: Allow the use of stores' endpoints and webhooks.
To run the tests, use:
composer install
vendor/bin/phpunit
This PHP package is automatically generated by the OpenAPI Generator project:
- API version:
v1
- Build package:
org.openapitools.codegen.languages.PhpClientCodegen