Skip to content

Latest commit

 

History

History
488 lines (414 loc) · 30.2 KB

README.md

File metadata and controls

488 lines (414 loc) · 30.2 KB
Raw

OpenAPIClient-php

Overview

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

Versioning

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

API General Definitions

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

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\"}'

API Authentication/Authorization

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.

Request Examples

URL Encoded Form

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]'

HTTP Basic Auth

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'

Webhook

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

Notification Schema

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.

Notification Request Example

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\": {}
   }
}

Expected Response

The partner application should return an HTTP 200 response code with an empty response body to acknowledge receipt of the webhook event.

Rate Limiting

Please, refer to Rate Limiting Guide for more details.

Installation & Usage

Requirements

PHP 7.4 and later. Should also work with PHP 8.0.

Composer

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

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');

Getting Started

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;
}

API Endpoints

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

Models

Authorization

OAuth2.0

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

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

  • API version: v1
  • Build package: org.openapitools.codegen.languages.PhpClientCodegen