Using the API

Introduction

Our API is accessible on the following base endpoint https://apps.xynaps.net/api/{version} Where {version} must be replaced by the current version. For the moment the API is at version 2. Use the version number prefixed with the letter ‘v’ in the url. So the current base endpoint is https://apps.xynaps.net/api/v2

Conventions

Message format

Our API supports 2 possible formats for the request and response message payload:

  1. JSON (default)
  2. XML

The default format used is Json. If you want to receive the messages in xml you can use the Accept header in your request. For example:

GET /api/v2/transportdocuments/12 HTTP/1.1
Host: apps.xynaps.net
Authorization: Bearer 164ajioAEJ6868yUpkk831385
Accept: application/xml

If you want to use xml as message payload data when sending request to our API (for example in a POST or PUT), use the Content-Type header to specify the message format. For example:

POST /api/v2/transportdocuments/12 HTTP/1.1
Host: apps.xynaps.net
Authorization: Bearer 164ajioAEJ6868yUpkk831385
Content-Type: application/xml
Accept: application/xml

Note

Always consult the API reference to verify if the format can be used for the specific resource you want to access.The OAuth 2.0 API for example has more strict rules on the formats used. The POST operations on the OAuth 2.0 token endpoint only accept data form url encoded and return token information in json format.

Filtering results

Filtering the results can be done using the filter query parameter.

The example below shows how to search for a transport document where the consignment note number equals B001E

https://apps.xynaps.net/api/v2/transportdocuments/?filter=cmrNumber eq 'B001E'

See the table below for the operators that can be used:

Operator
Description
eq
Equal to the expression on the rhs
neq
Not equal to the expression on the rhs
gt
Greater than the expression on the rhs
lt
Less than the expression on the rhs
ge
Greater than or equal to the expression on the rhs
le
Less than or equal to the expression on the rhs
contains
Contains the expression on the rhs

Expressions can be combined using ‘and’ and ‘or’ logical operators. When specifying date and time values use the following syntax

datetime'yyyy-MM-ddTHH:mm:ss'
date'yyyy-MM-dd'

The following example searches for documents between 2 issued dates.

https://apps.xynaps.net/api/v2/transportdocuments/?filter=issuedDate gt datetime'2016-02-23T00:00:00' and issuedDate lt datetime'2016-02-24T00:00:00'

Paging results

Using the ‘page’ and ‘size’ query parameters you can get paged results. Use the ‘page’ parameter to set the number of the page starting from 1. Use the ‘size’ query parameter to set the number of results per page.

https://apps.xynaps.net/api/v2/transportdocuments/?page=2&size=30

Prerequisites

In order to use and call the API, you first have to register and obtain your client ID and client secret. See the section on ‘Authentication and Authorization’ for more information on how to get these credentials. Next determine which of the scenarios you need to implement.

  1. Use the API from a server on behalf of an organisation
  2. Use the API from a webserver on behalf of a user
  3. Use the API from a mobile device on behalf of a user

Use the API from a server on behalf of an organisation

Implement this scenario if you need to author (create, issue and manage) consignment notes for your own organization or the organization of a customer. To call the API, you will first need to obtain an access token for the organisation. This can be done using the OAuth 2.0 Resource Owner Credentials grant. You will need additional connection credentials from the organization for which you want to author the consignment notes. Contact our support service at support@pionira.be for the connection credentials for a certain organization.

Obtain the access token from the token endpoint of our Authorization Server located at https://apps.xynaps.net/api/v1/oauth2/token

For example, a request for an access token is sent using the password grant type. All necessary parameters are sent form url encoded:

POST /api/v1/oauth2/token HTTP/1.1
Host: apps.xynaps.net
Content-Type: application/x-www-form-urlencoded

grant_type=password&client_id=7979797YIYZYEZ&client_secret=66YD82D2DOZIADDAFDAOD&username=&password=A3ddj3w

After successful validation of the client credentials and resource owner credentials, the server responds with a

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"164ajioAEJ6868yUpkk831385",
    "token_type":"bearer",
    "expires_in":3600
}

When you retrieve an access token, use it in the authorization header to call the API.

For example:

GET /api/v2/transportdocuments/12 HTTP/1.1
Host: apps.xynaps.net
Authorization: Bearer 164ajioAEJ6868yUpkk831385

Note

For testing purposes or if your organization has received client credentials (client ID and secret). You can use the ‘Client Credentials Grant’ instead of the ‘Resource Owner credentials Grant’ to obtain a token and access the API. This token will of course be limited to accessing only the resources of your organization.