Specyfikacja Internet Shipment Format (ISF)

Zapoznaj się z podstawowymi założeniami oraz pełną specyfikacją standardu Internet Shipment Format (ISF).

Podstawowe założenia

Struktura

Plik ISF zbudowany jest jako zestaw zdarzeń typowych dla handlu internetowego - zamówień oraz zwrotów.

Każde zdarzenie (zamówienie albo zwrot) składa się z:

  • przesyłki składającej się z jednej lub więcej paczek
  • nadawcy
  • odbiorcy
  • płatnika
  • informacji o przesyłce zwrotnej
  • ewentualnych błędów w obsłudze pliku ISF

Każda przesyłka składa się z:

  • danych do śledzenia (numer i link)
  • pojedynczej lub wielu paczek
  • etykiety
  • usług kuriera (priorytet oraz czas)
  • usług dodatkowych
  • usług związanych z odbiorem przesyłki
  • kosztu przesyłki dla nadawcy

Każda paczka składa się z:

  • danych do śledzenia (numer)
  • opisu (opakowanie, waga, wymiary, zawartość, referencje)

Każda przesyłka zawiera informacje niezbędne do wygenerowania etykiety (w zależności od rodzaju przesyłki) oraz miejsce na informacje zwrotne (o ile kurier je obsługuje i wymaga ich dana przesyłka):

  • numer przesyłki
  • numer paczki
  • link do śledzenia paczki
  • etykieta
  • etykieta Return Shipment (RS)

Standardy

W pliku zastosowane zostały następujące standardy:

  • waluta (currency) według ISO 4217 - np. PLN, USD, EUR
  • język (language) według ISO 639-2 - np. pol, eng, deu=ger
  • kraj (country) według ISO 3166-1 alpha-2 - np. PL, US, DE - ten zapis pokrywa się prawie 1:1 z międzynarodowymi końcówkami domen oraz jest podstawą zapisu waluty oraz regionu
  • region (subdivision) według ISO 3166-2 - np. PL-ZP, US-DC, DE-BB
  • czas wygenerowania (generated) według ISO 8601 - np. 2016-05-25T11:08:51+01:00

Protokół ISF (webserwis)

Format komunikacji

Żądanie do webserwis wykonywane jest w formacie JSON z czterema parametrami: 'user', 'isf', 'time' i 'hash'. Parametry przekazywane są metodą HTTP POST.

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

Do skonfigurowania protokołu ISF do obsługi kuriera przez webserwis, sklep musi uzupełnić:

  • Adres URL webserwisu
  • Hasło do generowania klucza
  • Nazwę użytkownika na potrzeby HTTP Authentication (opcjonalne)

Algorytm generowania SHA-256 w webserwisie

  • $isf - oznacza ISF (XML)
  • $time - znacznik czasu
  • $key - tajny klucz znany kurierowi i obsłudze sklepu ("Hasło do generowania klucza")
  • $user - nazwa użytkownika
  • $isfHash - SHA-256 z $isf. Hash jest liczony jako SHA-256 z posklejanych (bez dodatkowych łączników) danych: $user, $isfHash, $key i $time

Przykładowe pliki ISF 1.2

Pobierz i zapoznaj się z przykładowymi zleceniami wysyłki w formacie ISF. Poniższe przykłady pokazują wysyłkę dla odbioru osobistego w punkcie (informuje o tym wartość shipment/pickup/self_pickup ustawione na 'yes' i dane punktu odbioru w receiver/pickup_point).

Specyfikacja techniczna

Poniżej możesz pobrać najnowszą wersję specyfikacji technicznej ISF.