Basic information

Structure

The ISF file is structured as a set of events typical of e-commerce - orders and returns. ISF 2.0 consists of two files - an event and a manifest, through which the carrier communicates its customized services.

Event (order or return).

shipment
- package (one/multiple)
  - tracking number
  - description (packaging, weight, dimensions, contents, references).
- tracking data (number and link).
- collection point
- shipping facility
- label
- courier services (priority and time).
- additional services
- shipment pick-up services
- cost of shipment for the sender
sender
recipient
payer
return shipment information
optional custom services, defined in the manifest (additional_params).
possible errors in ISF file handling.

Each shipment contains the information necessary to generate a label (depending on the type of shipment) and space for feedback (if the courier supports it and the shipment requires it):

parcel number
parcel number
parcel tracking link
label
Return Shipment (RS) label.

Manifest

courier API endpoint.
any additional XML structure defined by the developer.
variable configuration (optional)

Standards

The following standards are used in the file:

currency (currency) according to ISO 4217 - e.g. PLN, USD, EUR.
language according to ISO 639-2 - e.g. pol, eng, deu=ger
country according to ISO 3166-1 alpha-2 - e.g. PL, US, DE - this notation coincides almost 1:1 with international domain endings and is the basis for currency and region notation.
region (subdivision) according to ISO 3166-2 - e.g. PL-ZP, US-DC, DE-BB
generation time (generated) according to ISO 8601 - e.g. 2016-05-25T11:08:51+01:00

File-based ISF vs. ISF (webservice)

ISF can be implemented in two ways, depending on your technological resources. The more advanced solution is a webservice - the sender's and carrier's systems communicate with each other automatically, exchanging information about events. However, if for some reason it is not possible to create such a mechanism, communication between the store and the carrier can be done manually. Both parties can generate XML files and exchange them through other communication channels.

ISF protocol (webservice)

Communication format

The request to the webservice is made in JSON file format with four parameters: 'user', 'isf', 'time' and 'hash'. The parameters are passed via the HTTP POST method.

$isfHash = hash('sha256', $isf);
$time = time();
$requestHash = hash('sha256', $user . $isfHash . $key . $time);
$contents = array(
    'user' => $user,
    'isf' => $isf,
    'time' => $time,
    'hash' => $requestHash
);

To configure the ISF protocol for courier service via webservice, the store must complete:

Manifest URL.
Password for key generation.
User name for HTTP Authentication (optional).

Additional parameters defined via manifest.xml file.

The ISF format as of version 2.0 allows you to upload your own custom nodes that can be used by the courier to generate the label. Developer-defined variables in the manifest.xml file can be used to populate them.

The manifest.xml file contains information about the endpoint where the ISF is to be sent, the structure of the additionalParams node in the ISF, and the configuration of individual variables. In ISF 2.0, it is a key element for correct integration.

Support for customs clearance

The ISF format as of version 2.1 allows you to upload data required for customs clearance. This data includes information about the goods in the package (e.g., goods descriptions, CN/Taric code, country of origin), who pays customs duty and tax, and VAT invoice information (invoice number, date of issue, and the invoice file itself encoded in base64).



  
    recipient
    
        
            PL
            85016120
            2.2
            
                5
                5
            
            2
            
                Product 1
                Towar 2
            
        
    
    
        FVVV/11/PL/2109
        2021-09-13
        SWRvU2VsbCBJU0YgMi4xIGV4YW1wbGUgcmVxdWVzdA==

SHA-256 generation algorithm in webservice

$isf - means ISF (XML).
$time - timestamp
$key - the secret key known to the courier and the store staff ("Key generation password").
$user - username.
$isfHash - SHA-256 of $isf. Hash is calculated as SHA-256 from cobbled together (without additional hyphens) data: $user, $isfHash, $key and $time

Differences between ISF 2.1 and 2.0

The main difference between ISF 2.1 and 2.0 is the addition of the <custom_declaration> node, which contains all the information required by the courier API for customs clearance.

Sample files

Download and review sample shipping orders in ISF format. The following examples show shipping for personal pickup at point (indicated by the shipment/pickup/self_pickup value set to 'yes' and the pickup point data in receiver/pickup_point)'.

Technical Specification

Below you can download the latest version of the ISF technical specification.

Internet Shipment Format (ISF) Technical Specification 2.1