Sales

Welcome to the Sales API.

Sales API is a collection of all the APIs needed to perform a sale ranging from the creation of Orders and receiving Payments to sending Receipts to the customer. In this section we will document the different available APIs and guide you through your first sale.

Services

Authentication

All endpoints in the Sales API requires an authentiation header. The authentication header must be an Entur-issued OAuth2 bearer token. In order to Issue a valid token you must have a client_id and client_secret. (TODO)

curl --request POST \
  --url 'https://<type_of_token>.<environment>.entur.org/oauth/token' \
  --header 'content-type: application/json' \
  --data '{"grant_type":"client_credentials","client_id": "<clientid>","client_secret": "<clientsecret>","audience": "https://api.<envirnoment>.entur.io"}

Headers

Most endpoints also requires a header describing which point-of-sale (POS) the request originates from. This value is represented by the header Entur-POS. The Point of Sale header indicates where the product was purchased. This is a convenience header for the client, and it is up to the client using the API to decide the content for it. All requests will also have a correlation id which is pertained with a request as it propagates through the system. This value will show which request is being processed as it flows through the system. This value is automatically created and maintained by the internal logging library, and should not require any further actions from client developers. Sales and payment requires a header describing which distribution channel id (DCI) the request originates from. Distribution Channels controls which organisations can sell, refund or inform on available products or salepoints.

Versioning

The Entur Sales API follows a unified versioning scheme for the entire service portfolio, meaning that all services within the API should expose the same endpoint versions. Bumping this global version number indicates a breaking API change, and thus should happen infrequently.

Format:

The API version consists of a "v" prefix, followed by the API version number, e. g. "v1", "v2", etc.

API consistency:

All endpoints for a specific API version should guarantee API consistency – a client should be confident that the API will not change, as long as the version remains constant. For development purposes, endpoints subject to changes should maintain a beta version number throughout development, i. e. "/v1beta/...".

Pagination

Some of the endpoints for the API will potentially return large arrays of data, which could be taxing for the client. For this reason, the client must use pagination to limit the number or results returned from the API. Specifying current page and page size

To specify which page to be returned from the API, use the page query parameter in the URL. There is a default page size set for the relevant services, but this size can be overridden by specifying the perPage query parameter. In addition to the items for the current page, the response will contain the total item count (totalItems) and the total number of pages (totalPages).

This is an example of a query to /sales/v1/payments?page=1&perPage=4:

Query filters

Paged endpoints can also contain a form of filtering queries. These are query parameters which can be appended multiple times to build up a more complex filter.

Filter operators

eq - equal to ne - not equal gt - greater than gte - greater than or equal lt - lower than lte - lower than or equal

Example

/orders?totalAmount=gte:1000.00&organisationId=eq:1 would return all orders where total amount is greater than or equal to 1000.00 and has organisationId equal to 1.

Currency

The Entur Sales API has a standardised way of representing value of products. Firstly, a currency code must always be specified for a given product (e. g. "NOK", "USD", etc). Secondly, the amount for the given currency is represented as a numeric string with two decimal points (e. g. "100.00").

The example below shows how an order costing NOK 1446.00 is represented in the API. Note that many fields has been omitted from the order structure for better readability.

{
    "id": "ABCDEFGH",
    "version": 1,
    "status": "CONFIRMED",
    "totalAmount": "1446.00",
    "totalTaxAmount": "154.93",
    "balance": "0.00",
    "currency": "NOK",
    "paymentRefs": [
        {
            "orderVersion": 1,
            "paymentId": 6406,
            "amount": "1446.00",
            "currency": "NOK",
            "completedAt": "2018-09-03T12:47:18Z"
        }
    ],
    "travellers": [],
    "reservations": [],
    "organisationId": 1,
    "createdAt": "2018-09-03T12:44:27Z"
}

Dates

All dates returned from the Entur Sales API follows the ISO 8601 standard, i. e. "YYYY-MM-DDTHH:mm:SSZ".

Note that time is always represented in UTC, so the developer needs to convert it to the correct local time before presented to the end user. 2018-12-24T18:00:00Z is an example of a valid timestamp returned from the API.