Skip to main content

Requests

info

The API is currently in beta. We are working on improving the API and adding the features described in this document.

If you have any feedback, please contact us at francois.veauvy@jdc.fr.

All API requests must be made over HTTPS to https://api.pragma-project.dev/ for the production environment.

The staging environment which is used for testing purposes is available at https://api-staging.pragma-project.dev/.

Calls made over plain HTTP will be redirected or fail. API requests without authentication will also fail.

The Pragma API consumes and produces JSON data. Thus the following headers should be included with all requests to the API:

  • Accept: application/json
  • Content-Type: application/json

Specifications​

Below are described formats of special attributes returned by the API.

Monetary values​

All monetary values are returned as integers in the smallest currency unit (e.g. cents, pence, etc.) to avoid the loss of precision commonly associated with the use of floating point numbers.

Monetary values are generally expressed tax included.

Example

10,00 € is represented as 1000.

Currently the API only supports the Euro currency. This will be extended in the future.

Tax rates​

All tax rates are returned as integers in the smallest currency unit (e.g. cents, pence, etc.) to avoid the loss of precision commonly associated with the use of floating point numbers.

Example

20% is represented as 2000.

Dates and times​

All dates and times are returned in ISO 8601 format.

Item Canceled​

The POS application has a functionality allowing an authorized user to cancel a product after it has been ordered.

If you take a look at the items array in the response of an order, you will notice a special attribute named isCanceled available for each item. This attribute will be set to true when the product has been canceled by a user.

Canceled item in an order
{
  "description": "Martini rouge",
  "category": "Aperitifs",
  "subCategory": "Aperitifs",
  "quantity": 1,
  "total": 450,
  "unitPrice": 450,
  "isCanceled": true, // The item has been canceled
  "isTransferred": false,
  "transferReason": null,
  "cancelReason": "Client parti sans payer", // The reason why the item has been canceled
  "discountsApplied": [],
  "tax": {
    "taxName": "TVA 20",
    "taxRate": 2000,
    "taxAmount": 75
  },
  "itemCatalogId": "686947bc-e197-4e5d-bc19-59f2ec32a5d3"
}

A short explanation video — item cancelation before the payment stage

info

When an item is canceled, you will find the reason in the cancelReason attribute.

A canceled item will not be included in the total amount of the order nor in the total amount of the daily report.

Order Canceled​

The POS application has a functionality allowing an authorized user to cancel a whole order before of after the payment stage.

When requesting orders, you will notice a special attribute named isCanceled available at the root level of each order. This attribute will be set to true when the order has been canceled by a user.

Canceled order
{
  "id": "be3dae12-8f6c-4311-b470-c0b190a54cfe",
  "createdAt": "2022-11-29T10:58:30.620Z",
  "updatedAt": "2022-11-29T10:58:30.620Z",
  "customerId": null,
  "locationId": "fcbd4eb1-eb94-4b03-a522-e44738c8150f",
  "reportId": "e6acb72c-6585-4c2d-9f10-be71d48366f2",
  "openedAt": "2022-11-29T10:34:27.000Z",
  "closedAt": "2022-11-29T10:57:24.000Z",
  "guests": 2,
  "orderPlace": "Salle étage",
  "orderNumber": "7",
  "operatorId": "6a4b7edf-bfdf-4bb2-9b00-a48e55580aa7",
  "operatorName": "Gérant",
  "total": 0,
  "totalTax": 0,
  "totalDiscount": 0,
  "items": [
    // ...
  ],
  "menus": [],
  "payments": [
    // ...
  ],
  "isCanceled": true, // The order has been canceled
  "isTransferred": false,
  "transferReason": null,
  "cancelReason": "Faute de frappe" // The reason why the order has been canceled
}
info

When an order is canceled, you will find the reason in the cancelReason attribute.

A canceled order will not be included in the total amount of the daily report.

Order Transferred​

The POS application has a feature allowing a user to transfer a specific order to a PMS third party application (Property Management System for Hotels).

Guests in a hotel-restaurant can request to transfer their orders made in the restaurant to their Hotel room.

In these cases:

  • products ordered will be recorded by the restaurant POS application and expose by this API,
  • however payments and taxes will be recorded by the hotel PMS app. The API cannot retrieve them at the moment.

When requesting orders, you will notice a special attribute named isTransferred available at the root level of each order. This attribute will be set to true when the order has been transferred to a PMS.

Transferred order
{
  "id": "f7383813-89f0-4f21-abed-e4797c2411f7",
  "createdAt": "2022-11-29T11:32:06.061Z",
  "updatedAt": "2022-11-29T11:32:06.061Z",
  "customerId": null,
  "locationId": "fcbd4eb1-eb94-4b03-a522-e44738c8150f",
  "reportId": "d97711ad-4740-4197-acc6-1e00e16e5c29",
  "openedAt": "2022-11-29T11:31:10.000Z",
  "closedAt": "2022-11-29T11:31:21.000Z",
  "guests": 2,
  "orderPlace": "Salle étage",
  "orderNumber": "7",
  "operatorId": "6a4b7edf-bfdf-4bb2-9b00-a48e55580aa7",
  "operatorName": "Gérant",
  "total": 900,
  "totalTax": 0, // No tax is recorded on the order
  "totalDiscount": 0,
  "items": [
    // ...
  ],
  "menus": [],
  "payments": [], // No payments recorded in the order
  "isCanceled": false,
  "isTransferred": true, // The order has been transferred to the PMS
  "transferReason": "Transfert Octorate", // The reason why the order has been transferred
  "cancelReason": null
}
info

When an order is transferred, you will find the reason in the transferReason attribute.

Popina and Jalia are among other things integrated with Octorate PMS.

Rate Limiting​

This feature is a work in progress 🚧

To make it easier to determine if your application is being rate-limited, or is approaching that level, we add the following HTTP headers on our successful responses:

  • X-Ratelimit-Limit
  • X-Ratelimit-Remaining

There is a limit of 300 API calls per minute.

If you exceed the limit you will receive a 429 Too Many Requests response.

Errors​

The Pragma API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an action failed, etc). Codes in the 5xx range indicate an error with our servers (these are rare).

Each error object will usually contain several fields that explain the error, including status code, error title, detailed message etc. See two examples below :

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "body must have required property 'application'"
}

Some common error responses are listed below:

  • 400 Bad Request – Your request may be malformed
  • 401 Unauthorized – Your API key is wrong, or your user does not have access to this resource
  • 403 Forbidden – The record requested is hidden
  • 404 Not Found – The specified record could not be found
  • 405 Method Not Allowed – You tried to access a record with an invalid method
  • 429 Too Many Requests – You have exceeded the API rate limit

Pagination​

The Pragma API uses page-based pagination for all list endpoints. The responses will contain the paginated data.

The page query parameter is reserved for pagination and can be used like this:

GET /v1/orders?index=3&size=100

Here, index is the index of the page you want to retrieve and size is the number of results you want to return in the response. By default, the page[size] is 10 and is capped at 100.

Versioning​

The Pragma API includes the major version number as a prefix for all endpoints (e.g. /v1). While we reserve the right to make changes to the API as we see fit, we endeavour not to make any changes to the API that will break backwards compatibility.

In the rare case that we do need to break backwards compatibility, we will release a new major version of the API and deprecate the old version. This will give any integrations time to migrate to the new version.