Guides

Basic assumptions

The ISF file is structured as a set of events typical for online commerce – orders and returns. ISF 2.1 consists of two files – an event file and a manifest file, which the carrier uses to communicate its non-standard services.


Event (order or return)

  • shipment
    • package (single/multiple)
      • tracking number
      • description (packaging, weight, dimensions, contents, references)
    • tracking information (number and link)
    • collection point
    • post office
    • label
    • courier services (priority and time)
    • additional services
    • services related to parcel collection
    • shipping cost for the sender
  • sender
  • recipient
  • payer
  • return shipment information
  • optional non-standard services defined in the manifest (additional_params)
    possible errors in handling the ISF file

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):

  • shipment number
  • package number
  • package tracking link
  • label
  • Return Shipment (RS) label

Manifest

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

Example of a manifest.xml file

<manifest type="isf" version="1">
<url>
http://apiotrowski.couriers.iai-shop.com/connectors/api/connector/TMMExpress
</url>
<additional_parameters>
<products>
[iai:foreach_products_list-begin]
<product>
<name>
<![CDATA[ [iai:product_name] ]]>
</name>
<price>[iai:product_price_gross]</price>
<url>
<![CDATA[ [iai:product_url] ]]>
</url>
<weight>[iai:product_weight_kg]</weight>
<quantity>[iai:product_quantity]</quantity>
<product_code>[iai:product_code]</product_code>
</product>
[iai:foreach_products_list-end]
</products>
<order_currency>[iai:order_currency]</order_currency>
<client_province>[iai:client_province]</client_province>
<order_worth>[iai:order_worth]</order_worth>
<is_dangerous>[courier_config:isDangerous]</is_dangerous>
<collection_days_from>[courier_config:collectionDays]</collection_days_from>
</additional_parameters>
<config>
<option type="input" id="collectionDays" name="Przy generowaniu etykiety do daty nadania zawsze dodawaj ustaloną liczbę dni"> </option>
<option type="radio" id="isDangerous" name="Przesyłka zawiera towary niebezpieczne?">
<values>
<value name="Tak">yes</value>
<value name="Nie">no</value>
</values>
</option>
</config>
</manifest>

The following standards have been used in the file:

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 corresponds almost 1:1 with international domain extensions 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 according to ISO 8601 - e.g. 2016-05-25T11:08:51+01:00

ISF Protocol (web service)
Communication format

The request to the web service is made in JSON format with four parameters: “user”, “isf”, “time” and “hash”. The parameters are transmitted using 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 the web service, the store must complete:

  • Manifest URL
  • Password for key generation
  • Username for HTTP Authentication (optional)

SHA-256 generation algorithm in a web service

  • $isf - stands for ISF (XML)
  • $time - timestamp
  • $key - secret key known to the courier and store staff (‘Password for generating the key’)
  • $user - user name
  • $isfHash - SHA-256 of $isf. The hash is calculated as SHA-256 of concatenated (without additional connectors) data: $user, $isfHash, $key and $time

Updated 5 months ago

Did this page help you?