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:

Type	Example	Format, when sending to API	Format, when receiving from API
string	Hello World	Hello World	Hello World
number (integer)	29	29	29
float	12.59	12.59 / 12,59	12.59
boolean	true	true / 1 / yes	1
	false	false / 0 / no	0
email	test@invalid.inv	test@invalid.inv	test@invalid.inv
date	5. august 2011	2011-08-05	2011-08-05
		05-08-2011
		5-8-2011
		05/08/2011
		(etc)
time	18:45	18:45:00	18:45:00
		18:45
		18.45
		(etc)
binary	N/A	N/A	N/A

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:

`contract`	number	A contract number (provided by Geodis)
`apikey`	string	An API key (provided by Geodis)
`username`	string	A user name (provided by Geodis)
`password`	string	A password (provided by Geodis)
`commands`	collection	A collection of the commands which are to be executed.

The envelope can also contain the following field:

`haltonerror`	0 or 1	If set to 1, the API will halt execution if a command throws an error, otherwise the API will just continue to the next command (default behavior)
`remoteagent`	string	The API client can identify itself by providing a short identifier string, which will be recorded in the Leaps log and help troubleshooting.

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:

`status`	boolean	Always 0 when an error occurred.
`msg`	string	An error message.
`date`	date	The date on the server, when the envelope was received.
`time`	time	The time on the server, when the envelope was received.

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

`status`	boolean	Always 1 when envelope is correct. This isn't an indicator for whether the commands executed.
`msg`	string	OK
`results`	collection	A collection of results for each of the provided commands.
`date`	date	The date on the server, when the command execution started
`time`	time	The time on the server, when the command execution started

Command

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

command string The command to be executed.

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

If the command fails it will return the following set:

`status`	boolean	Always 0 when an error occurred.
`msg`	string	An error message.

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

status boolean Always 1 when command succeeded.

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

Name	Type	Meaning	Example
`id`	number	Internal ID used by Leaps to reference this address
`gid`	string
`name`	string		“MegaCorp Inc.”
`addr1`	string
`addr2`	string
`postcode`	string
`city`	string
`state`	string
`country`	string	The 2-letter country code	“UK”
`contact`	string	Name of contact person	“Tony Blair”
`email`	string		“tony@megacorp.co.uk”
`phone`	string
`mobile`	string

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.

Name	Type	Example
`id`	number	222
`name`	string	“UNITED KINGDOM”
`locations`	set	{ 125: “London”, 145: “Leeds”, 160: “Heathrow”, 181: “Dover” }

package

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

Name	Type	Meaning	Example
`id`	number	Internal ID used by Leaps to reference this package
`pcs`	number	Number of pieces	1
`packtype`	number	The package type, see GetPackageTypes	20
`description`	string
`shippingmark`	string
`width`	float
`height`	float
`length`	float
`weight`	float
`volume`	float

priceline

Name	Type	Meaning
`title`	string	The name of a fee or some other cost
`amount`	float
`original`	string	The amount in the original currency

sheet

Name	Type	Meaning
`title`	string	Name of a pricesheet
`valid`	boolean	True of this is a valid pricesheet, false if pricesheet doesn't apply
`note`	string	Only if valid is true
`error`	string	Only if valid is false
`total_excl`	float	Total price
`addon`	float
`currency`	string	The currency used, eg. “DKK”
`transittime`	number
`lines`	collection[priceline]

shipment

Name	Type	Meaning	Example
`slino`	string	The SLI number of this shipment
`sender`	address
`receiver`	address
`pickup`	address
`delivery`	address
`notify`	address
`incoterms`	string		“EXW”
`note`	string
`deliverynote`	string
`pickupnote`	string
`confirmationnote`	string
`distributionnote`	string
`status`	string		“Delivered”
`deliverytype`	string		“DD”
`date`	date	When the shipment was created in Leaps, GMT
`time`	time	When the shipment was created in Leaps, GMT
`pickupdate`	date
`pickuptimeearly`	time
`pickuptimelate`	time
`product`	string
`etadate`	date
`awbno`	string
`packages`	collection[package]

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

statusmessage

Name	Type	Meaning
`id` (X)	number	Internal ID used by Leaps to reference this status message
`slino`	string	SLI number of the shipment this status message belongs to
`date`	date	Date when the status message was generated
`time`	time	Time when the status message was generated
`description`	string
`location` (X)	string
`awbno`	string	AWB number of the shipment, if available
`carrier`	string	The carrier for the shipment

Miscellaneous commands

Echo

Input

text string

Output

answer string The text field from the input

Price commands

GetCountriesAndLocations

Retrieves a list of countries and locations.

Input

Name	Type	Meaning
None	-	-

Output

`from_countries`	collection[countryandlocation]
`to_countries`	collection[countryandlocation]

GetCurrencies

Get a list of available currencies.

Input

None

-

-

Output

Name	Type	Meaning	Example
`currencies`	set		{ “DKK”:“DKK”, “EUR”:“EUR”, “SEK”:“SEK” }

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

None

-

-

Output

Name	Type	Meaning	Example
`packtypes`	set		{ 100: “Bag”, 107: “Basket”, 29: “Tube” }

GetProducts

Get list of the available products.

Input

None

-

-

Output

products collection

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

Name	Type	Meaning
None	-	-

Output

Name	Type	Meaning
`weight`	string	Either kg or lb
`volume`	string	Either m3 or ft3

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.

Name	Type	Meaning	Example
`from_country`	number	The ID of a country	3
`from_location`	number	The ID of a location in the from_country, or 0 for no location
`to_country`	number	The ID of a country	4
`to_location`	number	The ID of a location in the to_country, or 0 for no location
`pcs<N>`	number
`packtype<N>`	number	Type of package, one of the values retrieved by the API call GetPackageTypes
`weight<N>`	float	Units should be as returned by the API call GetUnits	12.5
`volume<N>`	float	Units should be as returned by the API call GetUnits	0.0012
`width<N>`	float	Units should be centimeters	50
`height<N>`	float	Units should be centimeters
`length<N>`	float	Units should be centimeters
`addon_cost`	float	Additional fee to add, see `fee_type`	5.5
`fee_type`	string	If `addon_cost` is a flat fee or a percentage	`percent` or `flat`
`currency`	string	The code for a currency, only used if `addon_cost` is set, in which case it is required	`DKK`

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

sheets collection[sheet]

Booking commands

GetBookingsByLastChange

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

Input

Name	Type	Meaning
`changedate`	date	The date of the oldest shipment to retrieve
`changetime`	time	The time of the oldest shipment to retrieve

Output

Name	Type	Meaning
`slinos`	collection	A list of SLI numbers, each is a string

GetBookingBySLIno

Get details about a shipment.

Input

Name	Type	Meaning
`slino`	string	The SLI number of a shipment

Output

Name	Type	Meaning
`shipment`	shipment

GetStatusMessagesBySLIno

Get list of status messages for a shipment.

Input

Name	Type	Meaning
`slino`	string	The SLI number of a shipment

Output

Name	Type	Meaning
`statusmessages`	collection[statusmessage]

GetLabelBySLIno

Get the label for a shipment.

Input

Name	Type	Meaning
`slino`	string	The SLI number of a shipment

Output

Name	Type	Meaning
`label`	string	The label, base 64 encoded
`fromcarrier`	boolean	True if the label is a carrier label

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

Name	Type	Meaning
`slinos`	collection[string]	Only get labels for these SLI numbers
`startdate`	date
`enddate`	date

Output

Name	Type	Meaning
`labels`	collection[string]	The labels, base 64 encoded
`slinos`	collection[string]	List of SLI numbers, in same order as the labels

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

Name	Type	Meaning
`statusmessage`	statusmessage

Output

Name	Type	Meaning
`statusmessage`	statusmessage

Browser not supported