Wstęp

Poprzednia wersja dokumentacji: https://api.globkurier.pl/v1/documentation

1. Rozpoczęcie pracy

API GlobKurier jest oparte o architekturę REST. Odpowiedź zwracana jest w formacie JSON. Komunikacja z produkcyjną końcówką jest szyfrowana w SSL.

Środowiska są rozdzielone. Do korzystania z API testowego wymagane jest posiadanie konta użytkownika produkcyjnego pod warunkiem, że minął dzień od rejestracji bądź aktualizacji profilu (czas propagacji na serwis testowy). Dane testowe ulegają usunięciu na koniec dnia.

Istnieje możliwość wysłania zapytania w formacie JSON z nagłówkiem Content-Type o wartości application/json. W innych przypadkach dla zapytań POST nagłówek ten powinien mieć wartość application/x-www-form-urlencoded.

Dla ułatwienia procesu integracji oraz testowania działania API dokumentacja zawiera interaktywne zapytania.

URL bazowy:

https://api.globkurier.pl/v1

URL testowy:

https://test.api.globkurier.pl/v1

2. Wersje językowe

Język API wybieramy przesyłając w nagłówku żądania accept-language kodu języka w standardzie ISO 639-1.

Obecnie wspierane języki:

pl
en (domyślny)

3. Typy zasobów

Wyróżniamy 3 typy zasobów ze względu na autoryzację:

• nie wymagające autoryzacji (np. pobranie listy krajów)
• wymagające autoryzacji (np. pobranie danych swojego konta) oznaczone w dokumentacji ikoną kłódki
• z opcjonalną autoryzacją (np. wyszukiwarka produktów, która zwróci inne produkty dla gościa, a inne dla zalogowanego użytkownika) oznaczone w dokumentacji ikoną filtra

4. Odkrywanie zasobów

Dostępne metody możemy pozyskać odpytując dowolny zasób metodą HTTP OPTIONS. Odpowiedź będzie zawierała klucze w nagłówku:

Access-Control-Allow-Methods - dozwolone metody HTTP zasobu np. OPTIONS, GET
Access-Control-Allow-Headers - dozwolone nagłówki zasobu np. x-auth-token, accept-language, x-currency
Pozwala to na wcześniejszą weryfikację, czy dany zasób posiada dostęp niewymagający tokenu lub posiadany token uprawnia do niego.
Próba odpytania zasobu niedozwoloną metodą zakończy się statusem błędu 405 Method Not Allowed.

5. Stałe używane w API

Lista zawiera stałe wartości, które należy w określonych przypadkach przekazać w żądaniu, a których nie można pobrać z zasobów API.

Nazwa	Możliwe wartości
Typ nadania	PICKUP, POINT, CROSSBORDER
Typ odbioru	PICKUP, POINT, CROSSBORDER
Etykiety informacyjne	typ transportu: GROUND, AIR dodatkowe informacje o przewoźniku: PACZKOMAT, PACZKA_W_RUCHU
Typ klienta	PERSON, COMPANY
Cel przesyłki	SOLD, GIFT, SAMPLE, NOT_SOLD, PERSONAL_EFFECTS, REPAIR_AND_RETURN
Status zamówienia	NEW_SHIPMENT - nowe IN_PROGRESS - w trakcie przetwarzania przez system IN_TRANSIT - w trakcie realizacji przez przewoźnika DELIVERED - dostarczone CANCELED - anulowane RETURNED_TO_SENDER - zwrócone do nadawcy
Typ dokumentu finansowego	PROFORMA_INVOICE - faktura proforma INVOICE - faktura VAT CORRECTION_INVOICE - faktura korekcyjna SUPPLEMENTARY_INVOICE - faktura uzupełniająca RECEIPT - paragon INVOICE_FOR_RECEIPT - faktura do paragonu INVOICE_WITHOUT_VAT - faktura bez VAT PROFORMA_INVOICE_WITHOUT_VAT - faktura proforma bez VAT
Typ dokumentu transportowego	WAYBILL - list przewozowy PROTOCOL - protokół PROFORMA_INVOICE - faktura proforma AUTHORIZATION - upoważnienie INSTRUCTION_FOR_CUSTOMS_DOCUMENTATION - instrukcja do dokumentacji celnej CUSTOMS_CLEARANCE_CARD - karta odprawy celnej EXPORTER_STATEMENT - oświadczenie eksportera

6. Paginacja w API

Wszystkie zasoby, w których występuje możliwość sterowania paginacją opierają się na poniższym schemacie.

Request

Pole	Opis	Wymagane
limit	Maksymalna liczba wyników dla zadanych filtrów, domyślnie 25, maksymalnie 100.	Nie
offset	Numer pozycji, od której zwracane będą wyniki, numerowany od 0, domyślnie 0.	Nie
filters []	Tablica filtrów. Filtry różnią się w zależności od endpointa.	Nie

Odpowiedź

Pole	Opis
offset	Numer pozycji podany w parametrach żądania, lub domyślny, jeśli w parametrach nie podano pozycji.
limit	Maksymalna liczba wyników podana w parametrach żądania, lub domyślna, jeśli w parametrach nie podano limitu.
total	Całkowita liczba wyników dla zadanych filtrów.
results []	Tablica wyników.

Przykład paginacji

Jeśli chcemy wyświetlić masymalnie 10 pozycji na stronie, aby wyświetlić pierwszą stronę odpytujemy API ustawiając offset = 0 oraz limit = 10. Zwrotnie otrzymujemy informację, że wszystkich wyników total jest 126. Wiemy, że przy dziesięciu wynikach na stronie, mamy 13 stron wyników (ostatnia zawiera 6 pozycji). Aby wyświetlić drugą stronę odpytujemy API ustawiając offset = 10 oraz limit = 10.

7. Odpowiedzi API

API korzysta z następujących statusów odpowiedzi (RFC 2616):

Status HTTP	Opis
200 OK	Poprawna odpowiedź z zawartością kolekcji lub obiektu.
201 Created	Poprawna odpowiedź - kod informuje o zmianach poczynionych na serwerze w postaci utworzenia nowego obiektu.
202 Accepted	Poprawna odpowiedź - zapytanie zostało zaakceptowane, lecz jest jeszcze przetwarzane. W strukturze odpowiedzi znajduje się opis, jaki endpoint należy wywołać, aby uzyskać informacje o przetwarzanym elemencie.
204 No Content	Poprawna odpowiedź bez zawartości - kod informuje że serwer poprawnie przetworzył żądanie lecz odpowiedź nie wymaga zwrócenia dodatkowych informacji.
400 Bad Request	Błędne żądanie - zapytanie klienta zawiera niepoprawne dane. Zwrócona odpowiedź zawiera strukturę komunikatów błędów w postaci informacji ogólnych oraz szczegółów niepoprawnie wypełnionych pól. Na ich podstawie należy skorygować dane żądania i wysłać ponownie.
401 Unauthorized	Błąd autoryzacji - żądanie nie zawiera odpowiedniego tokenu do chronionego zasobu. Należy taki uzyskać i spróbować ponowić żądanie.
403 Forbidden	Odmowa dostępu do zasobu - przesłany token nie posiada odpowiednich uprawnień do chronionego zasobu.
404 Not Found	Nie znaleziono zasobu - żądanie klienta odnosi się do nieistniejącej ścieżki lub identyfikatora zasobu.
405 Method Not Allowed	Niedozwolona metoda – metoda HTTP zawarta w żądaniu nie jest dozwolona dla wskazanego zasobu. Odpowiedź zawiera również listę dozwolonych metod w nagłówku Allow. Dozwolone metody zasobów możemy również odkryć przed ich użyciem.
500 Internal Server Error	Błąd wewnętrzny API - napotkano permanentny błąd uniemożliwiający zrealizowanie żądania. Prosimy o zgłoszenie do działu technicznego pytań o status naprawy.
503 Service Unavailable	API tymczasowo niedostępne - nie udało się zrealizować żądania, należy spróbować ponownie.