API: Booking commands

The examples are based on the Geodis Leaps system, but the same applies to any other Leaps system, just replaced the URL etc.

Accessing the API

The API is accessed using the following URL:

https://portal.ff.geodis.com/api/endpoint.php

All communication with the API is facilitated using UTF-8 encoded JSON.

When communicating with the API, the JSON should be provided in the parameter json using either POST or GET ex.

https://portal.ff.geodis.com/api/endpoint?json=...

Other Leaps systems (e.g. GLS) use different URLs.

Definitions

All communications are facilitated using JSON. In this documentation we use the following terms, to reference different JSON structures.

Set

A set is defined as field:value pairs, defined in JSON as:

{field1: value1, field2: value2,...}

A value can be a basic type, another set or a collection.

Collection

A collection is defined as a list of values, defined in JSON as:

[value1, value2,...]

A value can be a basic type, a set or another collection.

Basic types

The API uses the following basic types:

Concept

The API is used to pass one or more commands to Leaps. The commands are given in a collection, which again is wrapped in an envelope containing identification information such as the API-key, user name and/or password. When all commands has been executed, a structure is returned with the result of each command.

Versioning

Fields and commands are never removed from the API, but new fields can be implemented both in objects and command results. Therefore it is important that implementations against the API allows for this, in order to be forward-compatible.

Envelope

All communication to the API must be contained in an envelope, as described in this section. The envelope is a set containing the following fields:

The envelope can also contain the following field:

An example envelope can look like this in JSON:

{"contract": xxx,"apikey":"xxx","username":"xxx","password":"xxx","commands": []}

If there is an error in the envelope, the following set will be returned:

If the envelope is correct, the following set will be returned:

Command

A command is a set containing at least the following field:

The rest of the fields in the set is determined by the command executed.

If the command fails it will return the following set:

If the command succeeds it will return a set containing at least the following field:

The rest of the fields in the set is determined by the command executed.

Testing the API / Example

Connection to the API can be tested using the Echo command, which take a parameter text which is just returned as a result in the field answer.

The JSON for calling the Echo command looks like this:

{"portal":"XXX","apikey":"","username":"X","password":"X","commands":[{"command":"Echo","text":"Hello World"}]}

(remember to substitute the X's for the info received from Geodis).

Using GET the command can be executed calling this URL:

https://portal.ff.geodis.com/api/endpoint.php?json=%7B%22portal%22%3A%22X%22%2C%22apikey%22%3A%22X%22%2C%22username%22%3A%22X%22%2C%22password%22%3A%22X%22%2C%22commands%22%3A%5B%7B%22command%22%3A%22Echo%22%2C%22text%22%3A%22Hello+World%22%7D%5D%7D

If the envelope is correct, the server will respond with:

{"status":1,"msg":"OK","results":[{"status":1,"answer":"Hello World"}]}

Complex types

All complex types are sets, describing objects in Leaps. All fields in bold are required. If an optional field is omitted and the command operates on existing data, the current value of the field will be preserved.

(X) This field is only provided when receiving objects from the API. It is ignored when transmitting to the API.

address

The id field can be 0 if this is a temporary address, instead of an address from the address book.

countryandlocation

The locations set holds a list of location names, indexed by internal IDs.

package

width, height, length, weight, volume are specified in the units used by the portal, see GetUnits.

priceline

sheet

shipment

Possible statuses: Booked, Pending, In transit, Deviation, Delivered, Confirmed, Cancelled, Cancelled by CCS.

statusmessage

Miscellaneous commands

Echo

Input

Output

Price commands

GetCountriesAndLocations

Retrieves a list of countries and locations.

Input

Output

GetCurrencies

Get a list of available currencies.

Input

Output

GetPackageTypes

Get list of the available package types. The result is a set with the names of the package types, indexed by the package type numbers.

Input

Output

GetProducts

Get list of the available products.

Input

Output

Each item in the collection contains two fields: id and title.

GetUnits

Get the units being used, ie. kg or lb, m3 or ft3.

Input

Output

GetPriceCalculation

Calculate the prices for a shipment.

Input

The number of packages, their packtype and weight and volume should be specified in fields named pcs1, packtype1, weight1, volume1, width1,height1,length1, pcs2, packtype2, weight2, volume2, pcs3 etc.

Weight and volume is specified per package.

If addon_cost isn't set then the result is returned in EUR. Otherwise the result is returned in the currency specified by currency.

Output

Booking commands

GetBookingsByLastChange

Get the SLI numbers of all shipments that have changed since a given date/time.

Input

Output

GetBookingBySLIno

Get details about a shipment.

Input

Output

GetStatusMessagesBySLIno

Get list of status messages for a shipment.

Input

Output

GetLabelBySLIno

Get the label for a shipment.

Input

Output

GetLabels

Get the labels for the shipments for a period. The period can be no longer than 14 days. The dates refer to the creation date of the shipments. Only carrier labels are returned.

Input

Output

AddStatusMessage

Add a status message to a shipment. The message will simply appear in the list of status messages for the shipment, it will not be emailed to those who may subscribe to status messages.

Input

Output