TransFollow References

1. Notation Conventions

  • HTTP Methods are in capital letters, such as GET
  • The resource name in an URL is separated from related parameters by a question mark ( ? )
  • Parameters in URL's are separated by ampersands ( & )
  • Parameter or Resource instance values are enclosed in curly braces ( { } )
  • When listing a choice of parameter values, options are separated by a pipe ( | )

2. Request and Response Content Type

POST requests for an access token require a application/x-www-form-urlencoded content type. In cases where binary data is involved the content type will be image/jpg or application/pdf. See the Guidelines. These are the only exceptions to the general rule that the TransFollow API only deals with JSON content. Regular POST, PUT and PATCH requests can contain HTTP body information in JSON format. A correct Accept HTTP header line is mandatory for every request that expects content in order for the API implementation to determine the right response format, for example in the form of

Accept: application/json

A correct Content-Type HTTP header line is mandatory for every POST, PUT and PATCH request in order for the API implementation to determine the content format. All responses will carry a HTTP header line with

Content-Type: application/json.

The Accept header line may request a different format than the Content Type header line offers.

3. TransFollow Error Format

The TransFollow API returns collections of standardized error codes to communicate errors back to the clients. Syntax and meaning of error messages and error coding will be uniform for everyone using the API. Every message references an error situation that can have one or more root causes and one or more verbal descriptions. The errors element contains an array of one or more errors. Every error element contains at least two elements, error code and error description in English. In appropriate cases an element called 'field' indicates the datafield involved. The code is meant for handling the error, the description is for developers. It is not to be exposed to end users. For a full list see below. An API error message looks like this:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errors": [
    {
      "code": "1.12",
      "description": "The user is not authorized to access the resource."
    }
  ]
}

4. API and Call Versioning

Version format

A version is a three-part number, the parts separated by a dot. (The first version is 0.0.1) We call the parts Major, Minor and Build or Patch (see http://semver.org/). The last part is a build-number that identifies for bug fixes or re-builds in the backend implementation. We use the second part (Minor) for identifying ongoing - non breaking - changes. The first part is a version number that indicates a different, possibly SIMULTANEOUS instance of the backend. So version 1.x.x and 2.x.x can be live AT THE SAME TIME. Each version has its own set of API endpoints and documentation. To the outside world a version is a path element indicated by ../vX/.. where X is the Major version, e.g. api.transfollow.com/v1/api/

Compatibility between versions

Compatibility between Major versions is not guaranteed, Minor versions within a Major version will always be compatible. More specific from the perspective of the clients: backwards compatible API additions or changes increment the Minor part, and backwards incompatible API changes increment the Major version. If the Minor part changes client developers will have to adapt their code but their current product will keep working. If the Major part changes their current product will NOT keep working properly. They will have to create a new client version that interacts with the new API endpoints. If the Build/Patch increment changes client developers do not need to apply any changes.

Switching Major versions

Every version will be represented only by its MAJOR part in the Endpoint URL as the first path element, e.g. api.transfollow.com/v1/api/heartbeat. The actual v1 code will be running version 1.x.y where x is the last deployed minor version and y is the latest build number. All ../v1/.. requests will be routed to a Major version 1 where the last minor and build version is installed.

Suppose we create a new version of the heartbeat endpoint, called newheartbeat, containing breaking changes. To make sure clients can be adapted to a new Major version with as much manoeuvering room as possible we will do the following: within a reasonable timeframe we will simultaneously offer the old and the new endpoints. This means that both api.transfollow.com/v1/api/heartbeat and a new implementation of the same functionality called api.transfollow.com/v1/api/newheartbeat will be available. Both old and new endpoints can be used by clients simultaneously and without data loss. The old endpoint will be deprecated with Major version v1 in the future. The new endpoint will also be available in v2.

The amount of grace time before deprecating a previous Major version will be indicated in the Release Notes of the new Major version.

Switching Minor increments

Since new Minor increments will not break the functionality of client applications they will be offered without changes in the API URL. Announcements of new Minor increments with accompanying Release Notes will be made at deploy time. The Release Notes will guide client developers in adapting their products. Minor increments will be deprecated with their major version but not before that time.

5. Guidelines and Applied Practice

Strictness on content.

TransFollow is following the Robustness Principle (https://en.wikipedia.org/wiki/Robustness_principle) as much as possible. This means that - as a prime data source - we ask you to be conservative in what you send and liberal in what you accept from our endpoints. The last part means that we can add values to enumerations or json structures without expecting this to break your code. Of course we will not remove values or attributes under the same rule. All these changes will be communicated clearly. Breaking changes will be announced well in advance.

Filters and sorting

Filtering syntax is:

?filters=attributeName1.eq.value1,attributeName2.lt.value2,attributeName3.gt.value3
(the operands are eq, gt, lt, ge, and le, for =, >, <, >=, and <=).

Sorting syntax is:

?sort=attributeName1.asc,attributeName2.desc
(asc=ascending, desc=descending)

The comma's between the various filter and sort blocks indicate an AND condition. Beware: not all attributes are a candidate for filtering and/or sorting. In the Entity definition a column will indicate this capacity.

Dealing with optional elements or attributes.

If an element - or attribute - of a request body (or payload) is defined as optional and you do not wish to provide a value for that element you have two options: it can be left out of the request body completely or it can have a null value.

JSON:

{
  "optionalAttribute": null
}

Freightdocuments as PDF files

If you want to download a freight document as PDF, the Accept header of the GET /freightdocuments/{id} request must be application/pdf (not application/json) The API will send a PDF version of the freightdocument.

GET /api/freightdocuments/10001 HTTP/1.1
Host: partner.transfollow.com
Accept: application/pdf
Authorization: Bearer 3c3f7cb-b7dd-47ba-b047-8bc0fcddb4dc

Attachments as binary content

In case of JSON the content attribute is called 'content'.

JSON:

{
  "content": "..."
}

Within a JSON envelope the actual content will always be base-64 encoded. GET attachment/{id} will return the complete JSON instance of the attachment, GET attachment/{id}/content only the content. If the content needs to be encoded with base-64 the request for this must be made as a query-parameter.

/attachment/{id}/content?encodeBase64=true

A maximum of 10MB total storage per Freight Document is available at creation time. Afterwards attachments can be uploaded (as comments) without limit. Type of attachment should be pdf, png, jpeg or jpg, image size in total should not exceed 2MB.

6. Tools and Apps

Partner environment

The partner environment is a separate webportal with backend and mobile applications. You must use this environment for demonstration, testing and development purposes.

TransFollow API access

Each system needs to have an API key in order to have access to the TransFollow API. Instructions to the usage of this key are documented above and the key can be requested at support@transfollow.org.

The base URL of the TransFollow API in the partner environment is https://partner.transfollow.com/api.

The webportal is available at https://portal.partner.transfollow.com. On this portal you will be able to view freight documents, order credits and update your account information. Credits will not be invoiced on the partner environment.

Freight documents can not be created on the webportal, therefore we provide test tooling. See below.

TransFollow mobile applications

In order to complete a TransFollow freight document lifecycle you will need at least two mobile devices with internet connection. One device needs to have the TransFollow Android App installed, the second device will need to have an Enabler app installed or the TransFollow Android app installed.

Mobile applications are distributed via the official platforms of Google and Apple.

The minimal version of Android is 4.4 and the devices need the following capabilities:

- android.hardware.CAMERA
- android.hardware.camera.AUTOFOCUS
- android.hardware.TOUCHSCREEN

The are two types of mobile apps:

1: TransFollow Production Android App

This app can be used by the shipping party (consignor), the carrier and the receiving party (consignee) in the supply chain.

This app also contains an integration interface, useable with intents to allow for signing by board computer apps. The authorization requisites can be found in our TransFollow app intents documentation.

The production versions can be found here:

2: TransFollow Partner application for developers

While developing against the TransFollow API or just for demonstration or training purposes, you will need to use the partner versions of the TransFollow app to complete the full lifecycle of an freight document. For example, signing of issued freight documents can only be done by two parties, each using their own mobile app.

Partner Environment

The TransFollow partner environment app is bound to the partner TransFollow API that is separate from our production environment. This Partner environment has its own accounts with their credits and freight documents. These accounts are not present in the production environment. Functionally the Partner environment is identical to the production environment. To create and issue freight documents you will need to obtain credits here also. The credits are free of charge in the Partner environment. The portal of the Partner environment can be found at https://portal.partner.transfollow.com. Here you can create your accounts and order your credits .

Scenarios of use

Our standard scenario involves three parties: Consignor, Carrier and Consignee. Exchange of goods and creating a proof of delivery with the apps involves two of those parties at each hand-over. So, you will need three accounts, two of which will be active at any exchange.

Prerequisites for the apps.

This also means you will need at least two - or three if you want a device for every role – smartphones or 7 or 8 inch tablets with accurate camera’s, WIFI or Mobile Data connection and a recent version - 5 or higher is recommended - of Android.

Distribution of the apps.

Apps for the partner environment are not obtainable through the regular Play Stores, like the production versions. Instead they can be found in the closed BETA section of Google Play. Please contact us by email at support@transfollow.org and send us your Google Play email address if you want to be a part of the BETA program and we will send you an URL which can be used to opt-in and opt-out. When opt-in you will be able to search for the "TransFollow Partner" app in Google Play.

For creating and issuing freight documents you can also use the TF Android app.

Updates to the app will be distributed the same way as regular apps are. You will get a notification when this is available.

7. TransFollow Error Codes

Overview

The TransFollow API returns collections of error codes to communicate errors back to the clients. Using these error codes clients are able to identify particular errors, so the clients can display matching error messages to their users. Syntax and meaning of error messages and error coding will be uniform for everyone using the API. Every message references an error situation that can have one or more root causes and one or more verbal descriptions. The format of the message is derived from the general API guidelines. The errors element contains an array of one or more errors. Every error element contains at least two elements, error code and error description in English. In appropriate cases an element called 'field' indicates the datafield involved. The code is meant for handling the error, the description is directed at developers and for system monitoring / maintenance purposes. It is not to be exposed to end users. The TransFollow API full error codes are structured as follows:

error-category-code.error-detail-code

Examples

Full Error Code Short Name Description
1.6 Invalid client credentials "The client credentials are not in the system. The Authorization Header is present but the client credentials given are not correct"
3.2 Minimal length A field in the input does not meet the minimal length

The first example will look like this in a complete message:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="transfollow",error="unauthorized"
Content-Type: application/json

{
    "errors": [
        {
        "code": "1.6",
        "description": "Invalid Client Credentials."
        }
    ]
}

Category Codes

Code Name Description
1 Security Error Error code regarding authentication or authorization errors
2 Request Error Error code for expressing faults at the request level
3 Input Validation Error Error code for invalid parameters
4 Business Logic Error Error code which indicates that some business rule doesn't allow the operation
5 Catch All Error code which expresses that something went wrong
10+ Reserved All categories above 9 are reserved for non-API use.

Error Detail Codes

The following sections describe each possible error code from each error category.

Security Errors (category 1)

The following describe possible errors relating to security.

Error Code Short Name Description
1.1 Client not authenticated The client is not authenticating itself with the system. This is the case when the HTTP Authorization Header is missing
1.2 Not used Not used
1.3 Client not authorized The client is not authorized to execute a certain action
1.4 User not authorized The user is not authorized to execute a certain action
1.5 Not used Not used
1.6 Invalid client credentials The client credentials are not in the system. The Authorization Header is present but the client credentials given are not correct
1.7 Invalid user credentials The user credentials provided are not known in the system
1.8 No access token No access token found in the request.
1.9 No user credentials provided No user credentials were sent with the authorization request.
1.10 General security error This error is a catch-all for any other security-related errors.
1.11 Invalid access token The access token is invalid.
1.12 Resource access not authorized User is not authorized to access this resource (e.g. attachment).
1.13 Invalid grant token grant A new token could not be granted.

Request Error (category 2)

Error Code Short Name Description
2.1 Missing parameter A request parameter is missing.
2.2 Resource does not exist The requested resource does not exist.
2.3 Not used Not used.
2.4 Request body invalid The request body cannot be parsed.
2.5 Request method not supported The http request method is not supported for the endpoint.
2.6 Media type not supported The media type is not supported.
2.7 Request body is missing The required request body is missing.

Input Validation Errors (category 3)

These errors are usually coupled with an error response that contains the specific field to which the error applies.

Error Code Short Name Description
3.1 Required A part of the input is missing a required field.
3.2 String length error A field in the input does not meet the minimum or maximum length requirements
3.3 Assert true A field must be true, for example the "acceptTermsAndConditions" field, is always required to be true
3.4 Email format A field is not in email format
3.5 Email is not unique A email field is not unique in the system
3.6 Pattern format not correct A field does not have the correct pattern
3.7 Same password Update credentials with the same password as the old one
3.8 Wrong attachment type The attachment's mime-type is not allowed
3.9 Value not allowed A field contains an invalid value.
3.10 Reference wrong name/value pair The reference should contain both name and value
3.11 Invalid country code The country code is not valid
3.12 Invalid currency code The currency code is not valid
3.13 To date before from date The to date must be after from date.
3.14 Invalid phone number The phone number contains non-valid character(s). Valid chars: (), space, ., 0-9, -, #, +, *, p, w
3.15 TakingOver before Delivery date EstimatedTakingOver must be before EstimatedDelivery date-time
3.16 More than one field has value For a group of fields, a rule may exist that only one of them can contain a value. This rule has been violated.
3.17 Format not correct The format of the input field is not correct.
3.18 Attachment content may not be empty Attachment content may not be empty at creation
3.19 Filter query syntax error Filter query expression is not valid
3.20 Filter query operation not allowed Filter query operation is not allowed
3.21 Filter query attribute invalid Filter query attribute name is unknown/not allowed
3.22 Sort expression invalid Sort expression is invalid
3.23 Sort attribute invalid Specified sort attribute is unknown/not allowed
3.24 Sort order invalid Sort order is invalid (should be asc or desc)
3.25 Query invalid Only filter/sort are allowed in query expression
3.26 Date format Date field cannot contain time value or date value is invalid.
3.27 Field not allowed The field is not allowed in request and should be null.
3.28 Search type not supported The search type is not supported.
3.29 Number minimum Number is less than minimum allowed.
3.30 Pagination error The value for the pagination is not allowed.
3.31 Pagination size error The value for the size of the pagination is not allowed.
3.32 Currency code not specified The currency code must be specified.
3.33 Money amount error The amount specified is not valid
3.34 Attachment size error The total size of all existing and submitted attachments exceeds the maximum allowed
3.35 Carrier account nr and email The carrier may not submit both an account number and an email.
3.36 Freight document delegate exists The delegate already exists for this freight document.
3.37 Remove account delegate Removal of permanent account delegate is not allowed from specific freight document.
3.38 Account delegate exists For this freight document an account delegate already exists.
3.39 No license plate rights The user does not have rights to add or edit license plate data on this freight document.
3.40 Goods and Structured Goods You can not provide both the Goods and the Structured Goods fields.
3.41 Goods or Structured Goods You must provide either Goods or Structured Goods. They cannot both be empty.
3.42 Place of Taking Over mandatory Place of Taking Over role is mandatory on freight document.
3.43 Country Code mandatory Country Code for Place of Taking Over role is mandatory.
3.44 Country Code is immutable Country Code for Place of Taking Over role is immutable.
3.45 License plate invalid role License plates are only allowed on carrier or subsequent carrier roles.
3.46 No license plates There should be at least one license plate in the insert / update request.
3.47 Incorrect status The status of the freight document is incorrect, license plates can only be inserted or updated by the (sub)carrier while freight document has status ISSUED or TRANSIT.
3.48 Incorrect Role This role is not allowed to add or edit license plate data.
3.49 Not updated No license plates were updated.
3.50 Fields required All of the fields must be present or not.

Business Logic Errors (category 4)

These errors describe the possible business logic errors which can occur on the server side.

Error Code Short Name Description
4.1 Record does not exist The record does not exist in the repository.
4.2 Could not insert record Could not save a record into the data repository.
4.3 Client already exists The client application already exists in the system.
4.4 Attachment not part of the freight document The attachment is not part of the specified freight document.
4.5 FreightDocument not DRAFT Freight document is not in DRAFT status.
4.6 Account info immutable Role submitterAccountName, submitterAccountEmailAddress are immutable.
4.7 Delegating account failed Creating the account delegate failed.
4.8 Role reference immutable The reference to a role cannot be updated (for example the submitted account email address).
4.9 Estimated pickup date-time immutable The estimated date-time of taking-over cannot be updated when FD is in TRANSIT or DELIVERED.
4.10 Estimated delivery date-time immutable The estimated date-time of delivery cannot be updated when FD is DELIVERED.
4.11 Established country immutable The established country cannot be updated.
4.12 Comment period expired Cannot add a comment to the Freight Document because the comment expiry period has past (14 days after delivery).
4.13 Previous commits list is incorrect The previous commits list contains commit id's that are not in this freight document.
4.14 Callback URL invalid Callback URL invalid (max. 255 characters and must start with http(s)://).
4.15 Too many subscriptions Maximum number of subscriptions reached.
4.16 New status invalid New status for cargo transfer approval may not be DRAFT or ISSUED.
4.17 Sub-account not allowed to use credits The sub-account is not allowed to use credits of the main account.
4.18 Incorrect status The Freight Document is not in the correct status to apply the operation.
4.19 Transfer not allowed Transfer to account in POST-PAY payment scheme is not allowed.
4.20 Incorrect type The specified type of the freight document is not supported.
4.21 Not used Not used.
4.22 Not used Not used.
4.23 Not used Not used.
4.24 Not used Not used.
4.25 Not used Not used.
4.26 Not used Not used.
4.27 Not used Not used.
4.28 Not used Not used.
4.29 Invalid status transition The transition from 'oldSTATUS' to 'newSTATUS' is not valid.
4.30 PDF template merge error PDF template merge error.
4.31 PDF template parse error PDF template parse error.
4.32 Not used Not used.
4.33 Role cannot be removed Cannot remove the role with id 'id'.
4.34 Not used Not used.
4.35 Email token error Email token error description.
4.36 Attachment type invalid The attachment type is invalid.
4.37 Expired email token Email token has expired.
4.38 Invalid email token Email token does not exist.
4.39 Account already activated The account was already activated.
4.40 Account number not found The account number does not match any of the active accounts in the system.
4.41 Insufficient credits Insufficient amount of credits.
4.42 Not delegated No delegated rights to revoke.
4.43 Carrier account not found No account could be found for the carrier.
4.44 Attachment type not allowed Illegal attachment type for add attachment.
4.45 Commit list empty Expected values in commit list, but commit list was empty.
4.46 Adding new Structured Goods not allowed Freight document contains no Structured Goods, not allowed to add new Structured Goods.
4.47 Freight document not found The freight document was not found.
4.48 Not used Not used.
4.49 Not used Not used
4.50 Value not allowed The value sent is not allowed.
4.51 At least one available signing method required At least one available signing method must be provided

Catch All Errors (category 5)

Error Code Short Name Description
5.0 Catch All The error code for catch all errors

8. OAUTH 2

Overview

Several workflows are defined within the OAuth 2.0 framework. TransFollow mobile app will use the ‘Resource Owner Password Credentials Grant’ workflow. See the OAuth 2.0 RFC. The user requests an access token from the authorization server by offering his username and password. The app authenticates by offering client id and a client secret. Client credentials are used to differentiate between type of apps or client systems. The combination of user and client is granted an access token and a refresh token. This guideline will describe three scenarios in which the workflow will be implemented:

  • The first request for an Access Token
  • The Refresh Token request
  • The regular Resource request

In normal operations a user will request an access token by entering a username and password in the app. The app will add client credentials and request an access token. The response after a grant type password call contains tokens and an accountSecret. This accountSecret is needed for cargo Transfer & Approval. It will not be included in the response after a grant type refresh_token. The received access and refresh tokens as well as the accountSecret will be stored client-side. The password and user information must be discarded. All following requests will be bearing the access token. If the access token expires the server will reply with an error and the app can request a new access token by using the refresh token.

First request for access token by client and user authentication

The POST request for an access token authenticates the app with client_id and client_secret by offering a Basic Authorization header. The Basic string is the base64 encoded form of {client_id}:{client_secret}. The authorization server requires client authentication, it will authenticate the client, and validate the user password credentials. Since this access token request utilizes a password, the authorization server protects the endpoint against brute force attacks. The dialog must be encrypted by TLS. The realm header parameter (typically a description of the system being accessed) and scope will allways be “transfollow”. If the request lacks the required information (e.g., unaware that authentication is necessary or attempt using an unsupported authentication method), the server will not include an error code or other error information.

POST /oauth/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dHJ1c3RlZC1jbGllbnQ6c29tZXNlY3JldA==

grant_type=password&username=user@example.com&password=user-password&scope=transfollow

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "cdcce70d-f40b-4a89-8a16-4722034e8d6c",
    "token_type": "bearer",
    "refresh_token": "48691eb6-8192-42fd-8a07-8d18b2ad3c82",
    "expires_in": 43199,
    "accountSecret": "532496794312690300000",
    "scope": "transfollow"
}

Refresh Request for access token

The refresh request for an access token authenticates the app with client_id and client_secret by offering a Basic Authorization header. The Basic string is the base64 encoded form of ‘client_id:client_secret’. The authorization server must require client authentication, authenticate the client, and validate the refresh token. The authorization server will issue a new access token and the client will replace the old token with the new token. The accountSecret will not be included in the response. The scope will be identical to the one included by the client in the request. The dialog must be encrypted by TLS. If the request lacks the required information (e.g., unaware that authentication is necessary or attempt using an unsupported authentication method), the server will not include an error code or other error information.

POST /oauth/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dHJ1c3RlZC1jbGllbnQ6c29tZXNlY3JldA==

grant_type=refresh_token&refresh_token=48691eb6-8192-42fd-8a07-8d18b2ad3c82&scope=transfollow


HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "2YotnFZFEjr1zCsicMWpAA",
    "token_type": "bearer",
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
    "expires_in": 43199,
    "scope": "transfollow"
}

Regular Resource access request

The HTTP POST request creating a new TransFollow account is possible without a Bearer type Authorization header, so without an access token. This call must be carried out, encrypted by TLS, with a Basic Authorization for the Client system the end user is on. The reason for this is that account creation is an open service, accessible to everyone but only from known client systems. See the endpoints Specifications. Every other HTTP request for a TransFollow resource will be accompanied by an Authorization header, type Bearer, that holds the access token. The dialog must be encrypted by TLS. When a request fails, the server responds using the appropriate HTTP status code (400, 401 or 403) and includes the right error code in the response. Possible errors are: The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, uses more than one method for including an access token, or is otherwise malformed. The access token provided is expired, revoked, malformed, or invalid for other reasons. The server responds with the HTTP 401 (Unauthorized) status code and a standard error description in the body. The client may request a new access token and retry the protected resource request. The request requires higher privileges than provided by the access token. The resource server responds with the HTTP 403 (Forbidden) status code and a standard error description in the body.

GET /resource HTTP/1.1
Accept: application/json
Authorization: Bearer IamAFakeAccessToken

HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer realm="transfollow",error="invalid_token"

{
    "errors": [
        {
            "code": "1.11",
            "description": "Invalid access token"
        }
    ]
}

9. OAUTH 2 Third Party Integration

Third party software can also operate on behalf of users, by use of OAuth2. For example, a third party web/cloud application can ask the user if it can operate on his behalf. (The third party application needs a TransFollow API key with integration feature turned on.) The user is then redirected to a login page on the TransFollow system, where he can authorize your request by logging in. There are two possible flows: authorization code and implicit. The authorization code flow creates an intermediate code which can be used to an access token. An authorization code can be used only once. The implicit flow yields an access token right away and is less secure, but easier to implement.

See the diagrams below for a detailed description of the necessary communication among the user, TransFollow and your application:

Authorization code

Authorization code

An example of part of this flow shows the specifics. Note that clientId and clientSecret are treated differently from the 'normal' login call.

The redirect:

HTTP/1.1 302 Found
Location: https://partner.transfollow.com/api/oauth/authorize?redirect_uri=https%3A%2F%2Fdevelopers.google.com%2Foauthplayground&prompt=consent&response_type=code&client_id=xxxxxxxx&scope=transfollow&access_type=offline

The login request and response with the authorization code:

POST /api/oauth/token HTTP/1.1
Host: partner.transfollow.com
Content-length: 223
content-type: application/x-www-form-urlencoded
user-agent: google-oauth-playground

code=yXe7ui&redirect_uri=https%3A%2F%2Fdevelopers.google.com%2Foauthplayground&client_id=xxxxxxx&client_secret=yyyyyy&scope=&grant_type=authorization_code

HTTP/1.1 200 OK
Content-length: 171
X-content-type-options: nosniff
Strict-transport-security: max-age=31536000; includeSubDomains
Server: TransFollow
Content-type: application/json;charset=UTF-8

{
  "access_token": "fe239000-0e23-4337-b4b6-2c9c99e0e41c",
  "token_type": "bearer",
  "expires_in": 899,
  "refresh_token": "64913a83-3fb5-45ee-98ff-3c56ea889f80",
  "scope": "transfollow"
}

Implicit

Implicit

10. Principles and Guidelines

URL syntax

Case

The URL's in the implementation of the API will not contain uppercase letters. Attributes and Elements will be camelCased.

HTTP Methods

In general all partial updates to entities will be delivered as a PATCH endpoint. PUT endpoints can expect (and will check for) the full set of attributes present in the request. PATCH endpoints will be specified in our API specs completely (headers, body) for every predefined change to the Resource.

Format discrepancies

Date and time (or any other format-specific ) validation rules will always be enforced. So, if for example a date is wanted and a datetime offered the backend will respond with an appropriate error message. It will not tolerate otherwise or work around the issue.

HTTP Status codes

With a successful response the HTTP Status will be either 200 if content is available, 201 if resource is created, 204 if no content and 205 if the client view should be refreshed. Token confirmation is answered by 301, Redirect Permanently. With unsuccessful response the HTTP Status will be one of: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 405 Method Not Allowed or 409 Conflict.

Sorting, filtering

Filtering is done on content attributes of entities (only resource fields with content, not with references to other resources). Syntax is:

?filters=attributeName1.eq.value1,attributeName2.lt.value2,attributeName3.gt.value3
(the operands are ne, eq, gt, lt, ge, and le, for !=, =, >, <, >=, and <=).

Sorting is also done on content attributes of entities, not on references. Syntax is:

?sort=attributeName1.asc,attributeName2.desc
(asc=ascending, desc=descending)

Pagination

Query parameters for pagination of lists of Freigth Docuents are 'limit' and 'first'. The 'limit' is the number of Freight Documents returned. The 'first' is the offset. The 'first' parameter's value is 1-indexed. So limit=10 and first=1 will show the first 10 results. Thus limit=10 and first=11 will show records 11 through 20, and so on. If the 'first' parameter is not given, then the default is first=1. Syntax is:

?limit=10&first=1

The comma's between the various filter and sort blocks indicate an AND condition. Beware: not all attributes are a candidate for filtering and/or sorting. In the Entity definition (see Domain menu option) a column will indicate this capacity.

11. Languages

API English Dutch
freightDocument Consignment Note Vrachtbrief
references References Referentie
carrierCode Carrier Code Vergunningnummer
agreedDateTimeOfTakingOver Agreed date / time of taking over Overeengekomen ophaaldatum
agreedDateTimeOfDelivery Agreed date / time of delivery Overeengekomen afleverdatum
estimatedDateTimeOfTakingOver Estimated pick-up date / time Geplande ophaaldatum
estimatedDateTimeOfDelivery Estimated delivery date / time Geplande afleverdatum
establishedDate Established on Opgesteld op
establishedPlace Established in Opgesteld te
goods Marks and numbers, number of packages, method of packaging, the nature of the goods, statistical number, gross weight, volume in m3 Omschrijving van de goederen, merken, colli verpakkingsmethode en gewicht
senderInstructions Sender’s Instructions Instructies afzender
specialAgreements Special Agreements Speciale overeenkomsten
attachments (type = GOODS) Goods Attachments Bijlagen
attachments (type = GENERAL) Attached Files Bijlagen
attachments (type = COMMENT) ANNEX Voorbehouden en opmerkingen
attachments.name Name attachement Naam
attachments.mimeType / attachments.originalFileName File Bestand
attachments.sealed Sealed Verzegeld
comments Reservations and observations Opmerkingen
createDateTimeClient Date / Time Datum / Tijd
creatorName By Door
status Status Status
lastModifiedDateTime Last modified date / time Datum en tijd laatste wijziging
approvals (type = OWN) Own approval Ondertekend door vervoerder
approvals (type = TFA) TransFollow Approval TransFollow Akkoord
approvals (type = SIGN_ON_GLASS) Sign On Glass Handtekening op scherm
consignor Sender Afzender
consignee Consignee Geadresseerde
carrier Carrier Vervoerder
placeOfDelivery Place of delivery Plaats van aflevering
placeOfTakingOver Place of taking over Plaats in ontvangstname goederen
subsequentCarriers Successive carrier Opvolgende vervoerders
reimbursementCurrency / reimbursementAmount Cash on delivery Remboursement

12. Unordered JSON arrays

In spite of the strict JSON specifications we currently do not honor the order of JSON array elements. Please note that the order of elements in an array can be different from the posted array, while retrieving content.

13. Signed JSON

Signed JSON can be requested from TransFollow according to the OpenPGP specification. Currently we only support requesting PGP signed documents for Freight Document resources.

OpenPGP Signature

By supplying the /freightdocuments/{id} endpoint with the "application/vnd.freightdocument.v1+pgp-signature" Accept header, you will receive a verifiable PGP signature response. Please refer to our RAML specification for further technical specification of the endpoint.

14. Subscriptions

It is possible to configure webhooks to listen for changes on certain TransFollow resources (e.g. Freight Documents). Whenever a Freight Document receives a status update (e.g. TRANSIT to DELIVERED), an HTTP POST request is done to the configured webhook.

The HTTP request stops attempting after 3 failed tries. A successful response is implied when a response code 200 is returned. Please note that on any given resource a maximum of 10 subscriptions are allowed. If this number is exceeded, the API will return an error.

Currently we do not provide a way to configure the incoming request (i.e. specify authentication), other than the URL to make the request to.

A good way to implement the webhook is to add a random key to the callback URL (see example below). This way it is possible to identify calls from TransFollow. Other (unwanted) calls can easily be blocked or ignored.

{
  "callbackUrl": "https://www.yourdomain.tld/callback?key=00004356&check=645674356743327886536334"
}

An example of an incoming webhook request:

Method:

POST

Content-Type:

application/json;charset=UTF-8

Accept:

text/plain, application/json, application/\*+json, \*/\*

Body:

{
    "freightDocumentId": "0",
    "status": "DELIVERED"
}