Introduction to the external API

How a request travels

1. Your application sends an HTTP request with the authentication headers described under Authentication.
2. The gateway checks the client ID and the calling IP address. A failed check is answered with 401 or 403 and the request goes no further.
3. A valid request is given the context of your organisation and routed to your own isolated database. Every organisation’s data is held separately; a request can only ever reach the data of the organisation its credentials belong to.
4. The result comes back as JSON in the standard envelope.

Requests that change data also carry a signature computed from the payload with your client secret, so a tampered payload is rejected.

The response envelope

Every endpoint answers in the same shape. A successful call:

{
  "success": true,
  "data": {},
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 10
  }
}

pagination appears on list endpoints. A failed call carries the HTTP status and a message that says what was wrong:

{
  "success": false,
  "status": 400,
  "message": "Row 1: Items quantity must be a positive number"
}

Status codes

• 200 OK: the request succeeded. GET, PUT and PATCH calls.
• 201 Created: the resource was created. POST calls that create something.
• 400 Bad Request: the payload or a parameter is invalid: a validation error, a malformed UUID, a missing nonce or timestamp.
• 401 Unauthorized: authentication failed: the client ID is missing or invalid, the timestamp has expired, or the nonce has been used before.
• 403 Forbidden: the calling IP address is not on the integration’s allowed list.
• 404 Not Found: the product, invoice, customer or warehouse UUID does not exist.
• 409 Conflict: the operation is not allowed in the resource’s current state, for example voiding an invoice that is already void.
• 429 Too Many Requests: the integration has exceeded 100 requests per minute.
• 500 Internal Error: an unexpected error on our side. Retry, and tell us if it persists.