Introduction

To get access to this api you will need to have the api-module activated. Head in your account to https://backoffice.retaildesk.com/apps/my/create to create an client. Some request will return paginated results. Please use the provided urls to request the next set of data.

This documentation aims to provide all the information you need to work with our API.

Rate limiting

Every request to the API counts towards a general limit of 60 requests per minute per OAuth client. Some endpoints have an additional, stricter limit; this is listed at the endpoint (for example reports/summary: 1 request per 10 minutes). A request counts towards all limits that apply to it, so the most restrictive one determines when you are blocked.

When a limit is exceeded the API responds with 429 Too Many Requests. Wait until the limit resets before sending new requests.

Rate limit headers

When multiple limits apply, the headers describe the limit with the fewest remaining requests.

Reading the headers

$response = Http::withToken($accessToken)
    ->acceptJson()
    ->get('https://api.retaildesk.com/v1/transactions/sales');

$limit = (int) $response->header('X-RateLimit-Limit');
$remaining = (int) $response->header('X-RateLimit-Remaining');

if ($response->status() === 429) {
    // Wait the number of seconds the API asks for, then retry.
    sleep((int) $response->header('Retry-After'));
}

const response = await fetch('https://api.retaildesk.com/v1/transactions/sales', {
    headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
});

const limit = Number(response.headers.get('X-RateLimit-Limit'));
const remaining = Number(response.headers.get('X-RateLimit-Remaining'));

if (response.status === 429) {
    const retryAfter = Number(response.headers.get('Retry-After'));
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
}

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

1. Create Client

First create client id + secret in the app-center. https://backoffice.retaildesk.com/apps.

2. Request authorization code

redirect to: https://api.retaildesk.com/oauth/authorize?client_id=<client_id&redirect_uri=<redirect_uri>&response_type=code&scope=<scope>&state=<your_state>

Scopes are per resource: {resource}:read for GET requests and {resource}:write for POST/PUT/PATCH/DELETE, e.g. scope=products:read stock:read stock:write. Available resources: sales, cash_mutations, logging, customers, revenue_reports, catalogue_reports, stock_reports, products, stock, categories, taxgroups, turnovergroups, suppliers, brands, warehouses, registers, price_levels, promotions, webhooks, coupons. The old group scopes (catalogue, transactions, reports, customers, coupons) are deprecated; request the per-resource scopes instead.

Once a client has been created, you may use your client ID and secret to request an authorization code and access token from Retaildesk. First, the your application should make a redirect request to your /oauth/authorize route.

3. Redirect and verify
If the user approves the authorization request, they will be redirected back to your redirect url. Your app should first verify the state parameter against the value that was stored prior to the redirect.

4. Request Access code

(4) POST oauth/token
    [
        'grant_type' => 'authorization_code',
        'client_id' => 'client-id',
        'client_secret' => 'client-secret',
        'redirect_uri' => 'http://third-party-app.com/callback',
        'code' => 'code',    
    ]  

If the state parameter matches then the consumer should issue a POST request to your application to request an access token. The request should include the authorization code that was issued by your application when the user approved the authorization request. This /oauth/token route will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires.

5. Refreshing tokens

 (5) POST oauth/token
    [
        'grant_type' => 'refresh_token',
        'refresh_token' => 'the-refresh-token',
        'client_id' => 'client-id',
        'client_secret' => 'client-secret',
        'scope' => 'sales:read products:read revenue_reports:read',    
    ]     

You will need to refresh the access tokens with the refresh token that was provided to you when the access token was issued.

6. Passing the access token

(6) $response = Http::withHeaders([
    'Accept' => 'application/json',
    'Authorization' => 'Bearer '.$accessToken,
])->get('https://api.retaildesk.com/v1/endpoint');

When calling routes that are protected, your application's API consumers should specify their access token as a Bearer token in the Authorization header of their request. For example, when using the Guzzle HTTP library: