Basic information
File structure
An ISF file is made of a collection of events related to online trade - orders and returns.
Each event (order or return) consists of:
- a shipment containing one or more parcels
- sender information
- recipient information
- payee information
- return to sender information
- error information (if any occur)
Each shipment consists of the following elements:
- tracking number and link
- parcels (one or more)
- shipment label
- courier service type (i.e. priority, time of delivery)
- additional service information
- services related to shipment collection
- sender cost
Each parcel consists of:
- tracking information
- parcel details (packaging type, weight, dimensions, contents, references)
Each shipment contains information neccessary to print a shipping label, appropriate to the shipment type, as well as gives the ability to include return information (if required by courier):
- shipment number
- parcel number(s)
- tracking link
- label
- return shipment (RS) label
Standards used
The following open data standards are used for some ISF elements:
- currency, according to ISO 4217 - e.g. GBP, USD, EUR
- language, according to ISO 639-2 - e.g. eng, pol, deu=ger
- country, according to ISO 3166-1 alpha-2 - e.g. GB, US, DE
- subdivision (region), according to ISO 3166-2 - e.g. PL-ZP, US-DC, DE-BB
- time (generated), according to ISO 8601 - e.g. 2016-05-25T11:08:51+01:00
ISF protocol (web service)
To enable handling orders via the ISF web service, a shop needs to configure the following:
- web service URL
- secret key password
- user name (optional)
Web service hash algorithm
$isf - ISF data (XML)
$time - current timestamp
$key - secret key, known to the courier and the shop ("Secret key")
$user - user name
$isfHash - $isf hashed with SHA-256
- the request hash is calculated as SHA-256 from concatenated data (with no extra characters in between): $user, $isfHash, $key and $time
- request should be formatted as JSON and sent as POST
Example:
$isfHash = hash('sha256', $isf);
$time = time();
$requestHash = hash('sha256', $user . $isfHash . $key . $time);
$contents = array(
'user' => $user,
'isf' => $isf,
'time' => $time,
'hash' => $requestHash
);
Sample ISF 1.2 files
Full technical specification
Older versions