Podstawowe założenia

Struktura

Plik ISF zbudowany jest jako zestaw zdarzeń typowych dla handlu internetowego - zamówień oraz zwrotów. ISF 2.0 składa się z dwóch plików - zdarzenia oraz manifestu, za pomocą którego przewoźnik komunikuje swoje niestandardowe usługi.

Zdarzenie (zamówienie albo zwrot)

• przesyłka
  • paczka (jedna/wiele)
    • numer śledzenia
    • opis (opakowanie, waga, wymiary, zawartość, referencje)
  • dane do śledzenia (numer i link)
  • punkt odbioru
  • placówka nadania
  • etykieta
  • usługi kuriera (priorytet oraz czas)
  • usługi dodatkowe
  • usługi związane z odbiorem przesyłki
  • koszt przesyłki dla nadawcy
• nadawca
• odbiorca
• płatnik
• informacja o przesyłce zwrotnej
• opcjonalnych usług niestandardowe, zdefiniowane w manifeście (additional_params)
• ewentualne błędy w obsłudze pliku ISF

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)

Manifest

• endpoint API kuriera
• dowolna, dodatkowa struktura XML zdefiniowana przez developera
• konfiguracja zmiennych (opcjonalnie)

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

ISF plikowy a ISF (webserwis)

ISF można wdrożyć na dwa sposoby, w zależności od posiadanych zasobów technologicznych. Bardziej zaawansowanym rozwiązaniem jest webserwis - systemy nadawcy i przewoźnika komunikują się ze sobą automatycznie, wymieniając informacje o zdarzeniach. Jeśli jednak z jakiegoś powodu nie ma możliwości stworzenia takiego mechanizmu, komunikacja między sklepem a przewoźnikiem może odbywać się ręcznie. Obydwie strony mogą wygenerować pliki XML i wymieniać się nimi za pomocą innych kanałów komunikacji.

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 manifestu
• Hasło do generowania klucza
• Nazwę użytkownika na potrzeby HTTP Authentication (opcjonalne)

Dodatkowe parametry definiowane za pomocą pliku manifest.xml

Format ISF od wersji 2.0 pozwala na przesyłanie własnych, niestandardowych węzłów, które mogą być wykorzystane przez kuriera w celu wygenerowania etykiety. Do ich uzupełnienia można korzystać ze zmiennych zdefiniowanych przez developera w pliku manifest.xml.

Plik manifest.xml zawiera informacje o endpoint, gdzie ma zostać wysłany ISF, strukturę węzła additionalParams w ISF oraz konfigurację indywidualnych zmiennych. W ISF 2.0 jest on kluczowym elementem poprawnej integracji.

Wsparcie dla odprawy celnej

Format ISF od wersji 2.1 pozwala na przesyłanie danych wymaganych do przeprowadzenia odprawy celnej. Dane te to informacje o towarach w paczce (np. opisy towarów, kod CN/Taric, kraj pochodzenia), kto opłaca cło i podatek oraz informacje o fakturze VAT (nr faktury, data wystawienia oraz sam plik faktury zakodowany w base64).

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

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

Różnice między ISF 2.1 a 2.0

Główną różnicą między ISF 2.1 a 2.0 jest dodanie węzła <custom_declaration> który zawiera wszystkie informacje wymagane przez API kurierów do przeprowadzenia odprawy celnej.

Przykładowe pliki

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

• ISF 2.1 Example Request
• ISF 2.1 Example Response
• ISF 2.0 Example Manifest

Specyfikacja techniczna

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

• Internet Shipment Format (ISF) Technical Specification 2.1