API documentation General

Contents

• Server
• Authentication
• Payload Format
• HTTP Headers
• HTTP Status Codes
• HTTP Verbs
• Rate Limits

Server

There are two identical servers, one for testing, one for production use.
For testing purposes only sandbox server must be used!

Server	Root URL
Production	https://app.viaeurope.com/api
Sandbox	https://app-sandbox.viaeurope.com/api

Authentication

Every API request must contain your API token in the following HTTP header:

Authorization: Token token="YOUR_API_KEY"

You get two API keys (production / sandbox), make sure to use the correct one. If the request response is code 401 Unauthorized, you did not provide the correct key. The production API key is only provided once integration and testing has been completed successfully.

Payload format

• Please make sure to always send data encoded as UTF-8, you can in return expect to always receive data encoded as UTF-8.
• All endpoints accept and return data structured in JSON-format (compatible with RFC 7159).
• You can validate your syntax here: https://jsonlint.com.
• Numbers, such as units, weight or base_value, must _not_ be given as strings but integers.
• PDFs, such as waybill manifest, must be base64-encoded (compatible with RFC 2045) first, so they can be included in JSON as strings.

HTTP headers

Authorization: Token token="YOUR_API_KEY"
Content-Type: application/json
Accept: application/json

HTTP status codes

We make use of HTTP status codes to indicate success/failure of requests:

• 2XX - your request was successful
• 4XX - there was a problem with your request
  • 401 - incorrect/missing authentication header
  • 404 - endpoint or resource not found
  • 422 - unprocessable, see response body for details
  • 429 - rate limit, see response body for details
• 5XX - unexpected error on our side

HTTP verbs

Where possible, API v4 strives to use appropriate HTTP verbs for each action.

Verb	Description
GET	Used for retrieving existing resources
POST	Used for creating resources
PATCH	Used for updating existing resources
DELETE	Used for deleting resources

Rate limit

• We allow up to 100 read requests (GET) per second.
• We allow up to 30 write requests (POST/PUT/PATCH/DELETE) per second.
• Duplicate POST/PATCH/PUT requests within a 30 seconds window are rejected. The first request will be successful, but consecutive, identical requests will return an error.
• When a rate limit is reached, HTTP status 429 "Too Many Requests" will be returned, along with a description in the response body.
• It is recommended to implement this rate limit on the client side to avoid running into rate limiting in the first place.