Dokumentacja API serwisu GlobKurier.pl - wersja 1

Wstęp

Opis

API GlobKurier jest oparte o architekturę REST. Odpowiedź zwracana jest w formacie JSON. Komunikacja z produkcyjną końcówką jest szyfrowana w SSL. Końcówka testowa działa bez szyfrowania.

Środowiska są rozdzielone. Aby skorzystać z API testowego należy utworzyć użytkownika testowego w serwisie testowym albo użyć danych użytkownika produkcyjnego pod warunkiem iż 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:

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

Statusy odpowiedzi

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.

Struktura komunikatów błędów w odpowiedzi

Lista błędów wyświetlona jest pod dwoma kluczami:

Pole Typ Opis
general string[] Lista błędów ogólnych
fields string[] Lista błędów związanych z konkretnym przesłanym polem. Kluczem tablicy jest nazwa pola, a wartością opis błędu

Przykładowa odpowiedź

{
    "general": [
        "Fields postCode or city and street are missing"
    ],
    "fields": {
        "city": "This value is too short. It should have 3 characters or more.",
        "street": "This value is too short. It should have 3 characters or more."
    }
}

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)

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

Przejdź do opisu działania autoryzacji.

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

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.

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

Paginacja w API

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

Parametry żądania

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

Struktura odpowiedzi

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.

Autoryzacja

Cykl autoryzacji

Standardowy cykl użycia autoryzacji:

  • Za pomocą zasobu /auth/login pobieramy token.
  • Odwołując się do chronionego zasobu przekazujemy pobrany token w nagłówku żądania x-auth-token.
  • Ważność tokena autoryzacyjnego to 1 dzień. Istnieją dwa sposoby na przedłużenie ważności autoryzacji:
    • uzyskanie nowego tokena za pomocą zasobu /auth/refresh z użyciem otrzymanego wcześniej tokena
    • ponowna autoryzacja za pomocą /auth/login
  • Odpowiednikiem wylogowania się jest zniszczenie ważnego tokena /auth/logout.

Uzyskanie tokena

Endpoint

POST: /auth/login

Parametry żądania

Pole Opis Wymagane
email Email użytkownika GlobKurier.pl Tak
password Hasło użytkownika GlobKurier.pl Tak

Struktura odpowiedzi

Pole Typ Opis
token string Token, którym autoryzujemy się do chronionych zasobów

Przykładowe żądanie

Pole Wartość
email
password
Nagłówek Wartość
accept-language

Przykładowa odpowiedź

{
    "token": "M5vzf0vVAhRbYZmlZPQoCttpaUgctDIWx6ksFSuggYcqf2nDPWh3k0FfcugLeAt5"
}

Odświeżenie tokena

Endpoint

POST: /auth/refresh

Parametry żądania

Przesyłamy jedynie token w nagłówku x-auth-token żądania.

Struktura odpowiedzi

Pole Typ Opis
token string Nowy token (stary, którego użyliśmy traci ważność)

Przykładowe żądanie

Pole Wartość
Brak
Nagłówek Wartość
accept-language
x-auth-token

Przykładowa odpowiedź

{
    "token": "UgctDIWx6ksFSuggYcqf2nDPCttpaWh3k0FfcugLeAt5M5vzf0vVAhRbYZmlZPQo"
}

Zniszczenie tokena

Endpoint

POST: /auth/logout

Parametry żądania

Przesyłamy jedynie token w nagłówku x-auth-token żądania.

Struktura odpowiedzi

Jeśli przesłany token był ważny otrzymujemy pustą odpowiedź z kodem 204. Jeśli token był nieprawidłowy otrzymujemy odpowiedź 401.

Przykładowe żądanie

Pole Wartość
Brak
Nagłówek Wartość
accept-language
x-auth-token

Składanie zamówienia

Schemat składania zamówienia

Kolejność w schemacie jest przykładowa. Można zastosować inną jeśli odpowiada potrzebom użytkowników.

  1. Autoryzacja:

    • Udzielamy możliwości autoryzacji użytkownika
    • Alternatywna opcja to składanie zamówienia jako użytkownik niezalogowany
  2. Wyszukanie produktu:

    • Pobieramy listę krajów /countries
    • Użytkownik wybiera kraj nadania i odbioru oraz podaje pozostałe parametry do wyszukiwania produktów
    • Wyszukujemy listę dostępnych produktów /products
    • Użytkownik może wybrać nadanie w punkcie lub przyjazd przewoźnika po przesyłkę w zależności od tego na jaki typ nadania pozwala dany produkt. Będzie to miało wpływ na konieczne do wypełnienia pola (możliwość sprawdzenia za pomocą /order/customRequiredFields)
  3. Wybór dodatków do produktu:

  4. Wybór przedziału czasowego nadania jeśli typ nadania wybrany przez klienta to PICKUP:

    • Pobieramy listę dostępnych przedziałów /order/pickupRanges
    • Wybrany przedział przekazujemy w polu pickup podczas zapisu zamówienia
  5. Sprawdzenie dodatkowych pól wymaganych w procesie zamówienia:

    • /order/customRequiredFields możemy wykonywać wielokrotnie - wynik jej działania informuje nas o konieczności przekazadania dodatkowych pól w strukturze zamówienia (nie dotyczy dodatków - pola zależne od kategorii dodatku są ujęte w dokumentacji jw.)
  6. Obliczanie ceny zamówienia:

    • /order/price możemy wykonywać wielokrotnie - na podstawie wyniku jej działania informujemy uzytkownika o aktualnej cenie zamówienia
  7. Dane adresowe:

    • Aby zapewnić maksymalną spójność kodów pocztowych z miastem dla Polski możemy skorzystać z zasobu adresów na bazie kodów pocztowych
    • Jeśli odpowiedź /order/customRequiredFields informuje nas o tym, że wymagany jest wybór stanu/regionu nadawcy/odbiorcy korzystamy z zasobu /states
    • Jeśli użytkownik wybrał metodę nadania w punkcie możemy pobrać listę dostępnych punktów nadawczych/odbiorczych za pomocą /points
  8. Wybór typu płatności:

  9. Częściowa walidacja zamówienia:

    • Korzystając z akcji zasobu /order/validate możemy sprawdzić czy zamówienie zawiera błędy
  10. Zapis zamówienia:

    • Jeśli walidacja nia wskazuje błędów można dokonać zapisu zamówienia /order
  11. Pozostałe akcje po zapisie:

Wyszukiwanie produktu

Endpoint

GET: /products

Parametry żądania

Pole Opis Wymagane
width Szerokość [cm] Tak
height Wysokość [cm] Tak
length Długość [cm] Tak
weight Waga [kg] z maksymalną dokładnością do 2 miejsc po kropce Tak
quantity Liczba paczek/palet w przesyłce Tak
senderCountryId Identyfikator kraju nadawcy. Możliwe wartości można pobrać za pomocą zasobu /countries Tak
receiverCountryId Identyfikator kraju odbiorcy. Możliwe wartości można pobrać za pomocą zasobu /countries Tak
senderPostCode Kod pocztowy nadawcy (tylko dla Polski) Przekazanie kodów pozwala potwierdzić dostępność produktów:
  • na ten sam dzień
  • na kolejny dzień na rano
  • na kolejny dzień do południa
receiverPostCode Kod pocztowy odbiorcy (tylko dla Polski) Przekazanie kodów pozwala potwierdzić dostępność produktów:
  • na ten sam dzień
  • na kolejny dzień na rano
  • na kolejny dzień do południa

Struktura odpowiedzi

Pole Typ Opis
standard Product[] Produkty standardowe
noon Product[] Produkty możliwe do realizacji do południa kolejnego dnia. Dostępność produktu należy potwierdzić wykonując ponownie wycenę z polem senderPostCode oraz receiverPostCode, jeżeli te pola nie były wcześniej przekazane
morning Product[] Produkty możliwe do realizacji rano kolejnego dnia. Dostępność produktu należy potwierdzić wykonując ponownie wycenę z polem senderPostCode oraz receiverPostCode, jeżeli te pola nie były wcześniej przekazane
fast Product[] Produkty możliwe do realizacji od 5 do 10 godzin. Produkty na tej liście pojawiają się po przekazaniu pól senderPostCode oraz receiverPostCode
superfast Product[] Produkty możliwe do realizacji od 3 do 6 godzin. Produkty na tej liście pojawiają się po przekazaniu pól senderPostCode oraz receiverPostCode
Product
Pole Typ Opis
id int Identyfikator
carrierLogoLink string Adres do logotypu przewoźnika
name string Nazwa
carrierName string Nazwa przewoźnika
netPrice float Cena bazowa netto
grossPrice float Cena bazowa brutto
protocolAvailable bool Czy jest dostępna generacja protokołu zbiorczego /order/protocol
collectionTypes CollectionType[] Dostępne dla danego produktu typy nadania
labels string[] Etykiety informacyjne
discountCodeAllowed string Czy można użyć kodu rabatowego
deliveryTime string[] Czas (w godzinach), w jakim przesyłka powinna zostać dostarczona przez kuriera. Może nie być zadefiniowany
detailsLink string Link do struktury oferty
promo string Etykieta promocyjna

Przykładowe żądanie

Pole Wartość
width
height
length
weight
quantity
senderCountryId
receiverCountryId
senderPostCode
receiverPostCode
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

{
    "standard": [
        {
            "id": 657,
            "carrierName": "Paczka w RUCHu",
            "carrierLogoLink": "http://www.globkurier.pl/materialy/kurier/min/20.png",
            "name": "Paczka w RUCHu do 20 kg",
            "netPrice": 6.74,
            "grossPrice": 8.29,
            "collectionTypes": [
                "PICKUP",
                "POINT"
            ],
            "labels": ["GROUND"],
            "protocolAvailable": true,
            "discountCodeAllowed": true,
            "deliveryTime": {
                "minHours": "24:00:00",
                "maxHours": "48:00:00"
            },
            "detailsLink": "TEST",
            "promo": "NOWOŚĆ"
        },
        {...},
        {...}
    ],
    "noon": [
        {
            "id": 400,
            "carrierName": "UPS",
            "carrierLogoLink": "http://www.globkurier.pl/materialy/kurier/min/28.png",
            "name": "Koperta DOX do 12:00 - UPS",
            "netPrice": 33.08,
            "grossPrice": 40.68,
            "collectionTypes": [
                "POINT"
            ],
            "labels": ["GROUND"],
            "protocolAvailable": true,
            "discountCodeAllowed": true,
            "deliveryTime": null,
            "detailsLink": "TEST",
            "promo": null
        },
        {...},
        {...}
    ],
    "morning": [
        {
            "id": 401,
            "carrierName": "UPS",
            "carrierLogoLink": "http://www.globkurier.pl/materialy/kurier/min/23.png",
            "name": "Koperta DOX do 9:00 - UPS",
            "netPrice": 75.38,
            "grossPrice": 92.71,
            "collectionTypes": [
                "PICKUP",
                "POINT"
            ],
            "labels": ["GROUND"],
            "protocolAvailable": true,
            "discountCodeAllowed": true,
            "deliveryTime": null,
            "detailsLink": null,
            "promo": null
        },
        {...},
        {...}
    ]
}

Pobranie dodatków do produktu

Logika dodatków do zaimplementowania po stronie klienta:

  • Dodatek z kategorii INSURANCE jest wymagany w przypadku wybrania dodatku z kategorii CASH_ON_DELIVERY bądź płatności Płatność gotówką przy doręczeniu. Wartość dodatku musi być większa lub równa wartości dodatku CASH_ON_DELIVERY.

  • Dla jednego zamówienia można wybrać maksymalnie jeden dodatek z każdej z grup:

    • dodatki z kategorii INSURANCE
    • dodatki z kategorii CASH_ON_DELIVERY
    • dodatki z kategorii SATURDAY_DELIVERY, ON_TIME_DELIVERY, ON_TIME_DELIVERY_EVENING

Endpoint

GET: /product/addons

Parametry żądania

Pole Opis Wymagane
productId Identyfikator produktu pobrany za pomocą zasobu /products Tak
width Szerokość [cm] Tak
height Wysokość [cm] Tak
length Długość [cm] Tak
weight Waga [kg] z maksymalną dokładnością do 2 miejsc po kropce Tak
quantity Liczba paczek/palet w przesyłce Tak
senderCountryId Identyfikator kraju nadawcy pobrany za pomocą zasobu /countries Tak
receiverCountryId Identyfikator kraju odbiorcy pobrany za pomocą zasobu /countries Tak
senderPostCode Kod pocztowy nadawcy w formacie kraju nadawcy Tak
receiverPostCode Kod pocztowy odbiorcy w formacie kraju nadawcy Tak
insuranceValue Wartość dodatku z kategorii INSURANCE Nie
cashOnDeliveryValue Wartość dodatku z kategorii CASH_ON_DELIVERY Nie

Struktura odpowiedzi

Pole Typ Opis
addons Addon[] Lista dostępnych dodatków
requiredAlternativeAddons [int[]] Lista wymaganych alternatywnych zestawów dodatków do produktu. Tablica zawiera tablice identyfikatorów dodatków, spośród których użytkownik musi wybrać przynajmniej jeden aby zamówienie zostało przyjęte.
Addon
Pole Typ Opis
id int Identyfikator
addonName string Nazwa
description string|null Opis usługi dodatkowej
price float Cena - przeliczona na podstawie parametrów wejściowych
priceDescription string|null Opis w jaki sposób wyliczana jest cena za usługę. Występuje przeważnie w usługach takich jak pobranie COD lub ubezpieczenie, gdzie cena za usługę zależeć może od kwoty jakiej dotyczy usługa. Jeśli cena pochodzi prosto z cennika wartość przyjmuje null
category string Kategoria usługi dodatkowej
minValue float|null Minimalna wartość kwoty/sztuk zawarta w usłudze dodatkowej lub null, jeśli nie dotyczy. Wartość jest sugestią, można zamówić usługę dodatkową przekazując wartość mniejszą ale nie mniejszą niż 1. Sugestia wskazuje, że w ramach podobnych klas usług znajdują się korzystniejsze oferty.
maxValue float|null Maksymalna wartość kwoty/sztuk zawarta w usłudze dodatkowej lub null jeśli nie dotyczy. Gdy wartość ta jest ustawiona, nie można zamówić usługi dodatkowej przekazując wartość większą.
daysToReturn int|null Ilość dni w których następuje zwrot przekazanej wartości. Gdy wartość ta nie jest ustawiona nie następuje zwrot.
isRequired bool Czy dodatek jest wymagany. Jeśli tak, należy przesyłać go jako wybrany na liście usług dodatkowych.
verificationRequired bool Czy wymagana jest dodatkowa weryfikacja czy dany dodatek jest dostępny.

Przykładowe żądanie

Pole Wartość
productId
width
height
length
weight
quantity
senderCountryId
receiverCountryId
senderPostCode
receiverPostCode
insuranceValue
cashOnDeliveryValue
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

{
	"addons": [
		{
			"id": 507,
			"addonName": "Doręczenie do firmy",
			"description": null,
			"price": 0,
			"priceDescription": null,
			"category": "RECEIVER_TYPE_COMPANY",
			"isRequired": false,
			"minValue": null,
			"maxValue": null,
			"daysToReturn": null,
			"verificationRequired": false
		},
		{
			"id": 506,
			"addonName": "Doręczenie do osoby prywatnej",
			"description": null,
			"price": 0.3,
			"priceDescription": null,
			"category": "RECEIVER_TYPE_PRIVATE_PERSON",
			"isRequired": false,
			"minValue": null,
			"maxValue": null,
			"daysToReturn": null,
			"verificationRequired": false
		},
		{
			"id": 25,
			"addonName": "Element niestandardowy do 30kg",
			"description": null,
			"price": 14.89,
			"priceDescription": null,
			"category": "NOT_STANDARD",
			"isRequired": false,
			"minValue": null,
			"maxValue": null,
			"daysToReturn": null,
			"verificationRequired": false
		},
		{
			"id": 20,
			"addonName": "Pobranie COD do 20.000 zł",
			"description": null,
			"price": 0.00,
			"priceDescription": "5,6% wartości kwoty",
			"category": "CASH_ON_DELIVERY",
			"isRequired": false,
			"minValue": 0,
			"maxValue": 20000,
			"daysToReturn": 14,
			"verificationRequired": false
		},
		{
			"id": 32,
			"addonName": "Pobranie COD do 11.000 zł w 3 dni",
			"description": null,
			"price": 9,
			"priceDescription": "5,6% wartości kwoty, nie mniej niż 9,00 PLN",
			"category": "CASH_ON_DELIVERY",
			"isRequired": false,
			"minValue": 0,
			"maxValue": 11000,
			"daysToReturn": 3,
			"verificationRequired": false
		},
		{
			"id": 122,
			"addonName": "Pobranie COD do 2.000 zł w 1 dzień",
			"description": null,
			"price": 12,
			"priceDescription": "12,00 PLN +5,6% wartości kwoty",
			"category": "CASH_ON_DELIVERY",
			"isRequired": false,
			"minValue": 0,
			"maxValue": 2000,
			"daysToReturn": 1,
			"verificationRequired": false
		},
		{
			"id": 27,
			"addonName": "Powiadomienie o doręczeniu (e-mail)",
			"description": null,
			"price": 0,
			"priceDescription": null,
			"category": "MAIL_ON_DELIVERY",
			"isRequired": false,
			"minValue": null,
			"maxValue": null,
			"daysToReturn": null,
			"verificationRequired": false
		},
        {...}
	],
	"requiredAlternativeAddons": [
		[
			507,
			506
		]
	]
}

Weryfikacja kodu rabatowego

Sprawdzenie informacji o danym kodzie rabatowym

Endpoint

GET: /discountCode

Parametry żądania

Pole Opis Wymagane
discountCode Kod rabatowy Tak

Struktura odpowiedzi

Pole Typ Opis
discountCode string Kod rabatowy
discountPercent float Zniżka, do której uprawnia kod rabatowy
description string Opis kodu rabatowego

Przykładowe żądanie

Pole Wartość
discountCode
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Pobranie dostępnych godzin przyjazdu kuriera do nadawcy po przesyłkę

Endpoint

GET: /order/pickupTimeRanges

Parametry żądania

Pole Opis Wymagane
productId Identyfikator produktu pobrany za pomocą zasobu /products Tak
senderCountryId Identyfikator kraju nadawcy pobrany za pomocą zasobu /countries Tak
receiverCountryId Identyfikator kraju odbiorcy pobrany za pomocą zasobu /countries Tak
senderPostCode Kod pocztowy nadawcy w formacie kraju nadawcy Tak
receiverPostCode Kod pocztowy odbiorcy w formacie kraju nadawcy Tak
date Data, dla której sprawdzamy dostępne przedziały godzinowe Tak
weight Waga [kg] z maksymalną dokładnością do 2 miejsc po przecinku Tak
quantity Liczba paczek w przesyłce Tak

Struktura odpowiedzi

Pole Typ Opis
PickupRange[] Lista dostępnych przedziałów godzinowych
PickupRange
Pole Typ Opis
date string Dzień przyjazdu - format Y-m-d
timeFrom string Godzina, od której można spodziewać się przyjazdu - format H:i
timeTo string Godzina, do której można spodziewać się przyjazdu - format H:i

Przykładowe żądanie

Pole Wartość
productId
senderPostCode
senderCountryId
receiverPostCode
receiverCountryId
date
weight
quantity
Nagłówek Wartość
accept-language
GET: 

Przykładowa odpowiedź

[
    {
        "date": "2060-01-01",
        "timeFrom": "08:00",
        "timeTo": "10:00"
    },
    {
        "date": "2060-01-01",
        "timeFrom": "10:00",
        "timeTo": "12:00"
    },
    {...},
    {...}
]

Pobranie płatności

Wszytkie typy platności

Id Nazwa
1 Przelew bankowy
2 Płatność online
3 Konto pre-paid
4 Faktura zbiorcza (przelew bankowy - odroczony termin płatności)
5 Płatność gotówką
6 Płatność gotówką przy doręczeniu
8 Bon
9 Konto pre-paid (faktura zbiorcza)

Endpoint

GET: /order/payments

Parametry żądania

Pole Opis Wymagane
grossOrderPrice Cena za zamówienie. Wartość pobrana za pomocą zasobu /order/price Tak
productId Identyfikator produktu Tak

W przypadku wykorzystania zasobu do sprawdzenia listy dostępnych płatności dla produktu powiązanego z bonem jest wymagany tylko parametr productId. Innym sposobem sprawdzenia możliwości opłacenia zamówienia produktu powiązanego z bonem jest wykorzystanie zasobu /user/couponStats

Struktura odpowiedzi

Pole Typ Opis
Payment[] Lista płatności

Payment

Pole Typ Opis
id int Identyfikator
name string Nazwa
description string Opis
enabled bool Czy jest możliwa do wybrania
default bool Czy powinna być zaznaczona domyślnie

Przykładowe żądanie

Pole Wartość
grossOrderPrice
productId
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

[
    {
        "id": 2,
        "name": "Płatność online",
        "enabled": true,
        "default": true,
        "price": null
    },
    {...},
    {...}
]

Pobranie numerów kont bankowych

Endpoint pozwala pobrać numery kont bankowych do opłat dla różnych walut.

Endpoint

GET: /payments/bankAccountNumbers

Struktura odpowiedzi

Pole Typ Opis
BankAccountNumber[] Dane konta bankowego
BankAccountNumber
Pole Typ Opis
name string Nazwa banku
number string Numer konta bankowego
currency string Waluta

Przykładowe żądanie

Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

[
    {
        "name": "mBank",
        "number": "34 1140 1078 0000 5744 9900 1006",
        "currency": "PLN"
    },
    {...},
    {...}
]

Wycena zamówienia

Endpoint

GET: /order/price

Parametry żądania

Pole Opis Wymagane
productId Identyfikator produktu pobrany za pomocą zasobu /products Tak
length Długość [cm] Tak
width Szerokość [cm] Tak
height Wysokość [cm] Tak
weight Waga [kg] z maksymalną dokładnością do 2 miejsc dziesiętnych Tak
quantity Liczba paczek w przesyłce Tak
userCountryId Identyfikator kraju użytkownika pobrany za pomocą zasobu /countries
  • Należy przekazywać dla niezalogowanego użytkownika tylko wraz z wypełnionym polem userTaxId
  • Nie należy przekazywać, jeśli wysłano token zalogowanego użytkownika.
Nie*
userTaxId Numer identyfikacji podatkowej (NIP) - przekazanie pozwala uwzględnić odpowiednią stawkę podatku dla użytkownika
  • Należy przekazywać dla niezalogowanego użytkownika tylko wraz z wypełnionym polem userCountryId
  • Nie należy przekazywać, jeśli wysłano token zalogowanego użytkownika.
Nie*
senderCountryId Identyfikator kraju nadawcy pobrany za pomocą zasobu /countries Tak
senderPostCode Kod pocztowy nadawcy Zależy od wartości hasPostCodes z zasobu /countries
receiverCountryId Identyfikator kraju odbiorcy pobrany za pomocą zasobu /countries Tak
receiverPostCode Kod pocztowy odbiorcy Zależy od wartości hasPostCodes z zasobu /countries
receiverTaxId Numer identyfikacji podatkowej (NIP) - przekazanie pozwala uwzględnić odpowiednią stawkę podatku dla użytkownika. Wysoce rokomendowane jest przekazanie tego pola, szczególnie jeśli użytkownik posiada taki numer i wybiera płatność Na Koszt Odbiorcy, ponieważ to odbiorca końcowy staje się płatnikiem i faktura wystawiana jest na niego. Jeśli użytkownik nie posiada numeru NIP nie należy go przekazywać. Nie*
paymentId Identyfikator wybranej płatości. Dostępne formy płatności można pobrać z zasobu /order/payments Tak
addonIds Lista identyfikatorów wybranych dodatków Nie
insuranceValue Wartość dodatku z kategorii INSURANCE Nie
cashOnDeliveryValue Wartość dodatku z kategorii CASH_ON_DELIVERY Nie
discountCode Kod rabatowy - nie można przekazać w połączeniu z wyborem płatności Bon z pola paymentId Nie*

Odpytanie zasobu dla produktu powiązanego z bonem zwróci błąd gdyż dla takich produktów nie występuje cena zamówienia, ale ilość dostępnych do zamówienia produktów w ramach przyznanego bonu.

Struktura odpowiedzi

Pole Typ Opis
totalNetPrice float Cena zamówienia netto
netPriceWithoutFuelSurcharge float Cena zamówienia netto bez opłaty paliwowej
totalGrossPrice float Cena zamówienia brutto
productNetPrice float Cena produktu netto
addonsNetPrice float Cena dodatków netto
vatPercent int Procent VAT
discountNetPrice float Kwota netto rabatu
fuelSurcharge float Cena opłaty paliwowej (inna niż 0 tylko dla zalogowanych klintów typu firma)

Przykładowe żądanie

Pole Wartość
productId
length
width
height
weight
quantity
userCountryId
userTaxId
senderCountryId
senderPostCode
receiverCountryId
receiverPostCode
receiverTaxId
paymentId
addonsIds[0]
addonsIds[1]
addonsIds[2]
insuranceValue
cashOnDeliveryValue
discountCode
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

{
    "totalNetPrice": 13.11,
    "netPriceWithoutFuelSurcharge": 11.71,
    "totalGrossPrice": 16.13,
    "productNetPrice": 11.59,
    "addonsNetPrice": 0,
    "vatPercent": 23,
    "discountNetPrice": 0
    "fuelSurcharge": 0
}

Pobranie pól wymaganych warunkowo

Pozwala ustalić czy należy przesłać dodatkowe pola z danymi korzystając z zasobu /order

Endpoint

GET: /order/customRequiredFields

Parametry żądania

Pole Opis Wymagane
productId Identyfikator produktu pobrany za pomocą zasobu /products Tak
senderCountryId Identyfikator kraju nadawcy pobrany za pomocą zasobu /countries Tak
receiverCountryId Identyfikator kraju odbiorcy pobrany za pomocą zasobu /countries Tak
collectionType Typ nadania Tak

Struktura odpowiedzi

Pole Typ Opis
senderAddressPointId bool Punkt nadania przekazywany w gałęzi senderAddress
receiverAddressPointId bool Punkt odbioru przekazywany w gałęzi receiverAddress
declaredValue bool Deklarowana wartość zamówienia przekazywana w głównej gałęzi.
purpose bool Cel przesyłki przekazywany w głównej gałęzi.
pickupDate bool Data nadania przekazywana w gałęzi pickup.
pickupTimeFrom bool Godzina, od której planowany jest przyjazd przewoźnika przekazywana w gałęzi pickup.
pickupTimeTo bool Godzina, od której planowany jest przyjazd przewoźnika przekazywana w gałęzi pickup.
senderStateId bool Stan/region nadawcy przekazywany w głównej gałęzi.
receiverStateId bool Stan/region odbiorcy przekazywany w głównej gałęzi.

Przykładowe żądanie

Pole Wartość
productId
senderCountryId
receiverCountryId
collectionType
Nagłówek Wartość
accept-language
GET: 

Przykładowa odpowiedź

{
	"senderAddressPointId": true,
	"receiverAddressPointId": true,
	"declaredValue": false,
	"purpose": false,
	"pickupDate": false,
	"pickupTimeFrom": false,
	"pickupTimeTo": false,
	"senderStateId": false,
	"receiverStateId": false
}

Częsciowa walidacja zamówienia

Endpoint

POST: /order/validate

Niektóre Parametry żądania

Struktura treści żądania jest taka sama jak w /order
Rożnicą jest, że pola są niewymagane lub na tą chwilę nieobsługiwane przez walidację.
Poniżej znajdują się przykładowe obsługiwane pola z informacją o ich walidacji.

Przykładowe żądanie

Pole Wartość
userAddress[countryId]
userAddress[nip]
content
declaredValue
addons[0][id]
addons[0][value]
addons[0][bankAccountNumber]
addons[0][addressLine1]
addons[0][addressLine2]
addons[1][id]
addons[1][value]
Nagłówek Wartość
accept-language
x-auth-token

Przykładowa odpowiedź

{
    "fields": {
        "userAddress[nip]": "This value is not valid.",
        "userAddress[countryId]": "This value is not valid natural number.",
    }
}

Zapis zamówienia

Endpoint

POST: /order

Parametry żądania

Pole Opis Wymagane
shipment Dane przesyłki (Shipment) Tak
senderAddress Dane nadawcy (Address) Tak
receiverAddress Dane odbiorcy (Address) Tak
userAddress Dane zleceniodawcy (UserAddress) Wymagany jeśli składamy zamówienie jako użytkownik niezautoryzowany.
pickup Dane przyjazdu przewoźnika po przesyłkę (Pickup).
Informację czy dostępny jest ten typ nadania otrzymujemy w wyniku wyszukiwania produktów /products w polu collectionTypePickupAvailable.
Wymagana jeśli przekazaliśmy wartość PICKUP w polu collectionType.
content Zawartość przesyłki Tak
paymentId Identyfikator wybranej formy płatności Tak
agreements[receiveCommercialInfo] Zgoda na przetwarzanie danych osobowych w celach komercyjnych Nie
originId Identyfikator źródła zamówienia Zalecany - prosimy o zgłoszenia zapotrzebowania na spersonalizowany kod źródła
addons Lista wybranych dodatków (Addon[]) Nie
instructions Instrukcje dla przewoźnika
(Dodanie tego pola zwiększa czas obsługi zamówienia gdyż wymaga sprawdzenia przez pracownika BOK)
Nie
declaredValue Deklarowana wartość przesyłki Możliwość sprawdzenia za pomocą zasobu /order/customRequiredFields
purpose Cel przesyłki Możliwość sprawdzenia za pomocą zasobu /order/customRequiredFields
collectionType Typ nadania.
W zależności od wybranego typu nadania należy przekazać strukturę pickup lub punkt nadawczy/odbiorczy w strukturze adres.
Tak
discountCode Kod rabatowy Nie
(nie można łączyć płatności bonem z kodem rabatowym)
referenceNumber Nr referencyjny Nie
Shipment
Pole Opis Wymagane
length Długość przesyłki w cm Tak
width Szerokość przesyłki w cm Tak
height Wysokość przesyłki w cm Tak
weight Waga przesyłki w kg z maksymalną dokładnością do 2 miejsc po kropce Tak
productId Identyfikator produktu pobrany za pomocą zasobu /products Tak
quantity Ilość paczek w przesyłce Tak
Address
Pole Opis Wymagane
name Nazwa/Imię i nazwisko.
Może zawierać następujące znaki specjalne:
spacja . , ' ( ) - @
Tak
city Miasto.
Może zawierać następujące znaki specjalne:
spacja . ' ( ) - & /
Tak
street Ulica.
Może zawierać następujące znaki specjalne:
spacja . ' - & /
Tak
houseNumber Numer domu.
Może zawierać następujące znaki specjalne:
/
Tak
apartmentNumber Numer mieszkania Nie
postCode Kod pocztowy Tak
countryId Identyfikator kraju pobrany za pomocą zasobu /countries Tak
stateId Identyfikator stanu/regionu pobrany za pomocą zasobu /states Możliwość sprawdzenia za pomocą zasobu /order/customRequiredFields
pointId Identyfikator punktu nadania/odbioru pobrany za pomocą zasobu /points Możliwość sprawdzenia za pomocą zasobu /order/customRequiredFields
phone Numer telefonu Tak
email Adres email Wymagany dla adresu email nadawcy.
contactPerson Osoba kontaktowa Nie
nip Numer identyfikacji podatkowej Nie
Address/UserAddress
Pole Opis Wymagane
type Typ klienta Tak
nie Numer identyfikacji podatkowej firmy Wymagane, jeśli wybrany typ klienta to firma
companyName Nazwa firmy Wymagane, jeśli wybrany typ klienta to firma
name Imię Tak
surname Nazwisko Tak
city Miasto Tak
street Ulica Tak
houseNumber Numer domu Tak
apartmentNumber Numer mieszkania Nie
postCode Kod pocztowy W zależności od kraju
countryId Identyfikator kraju pobrany za pomocą zasobu /countries Tak
phone Numer telefonu Tak
email Adres email Tak
Pickup
Pole Opis Wymagane
date Planowana data przyjazdu przewoźnika po przesyłkę Tak
timeFrom Godzina, od której planowany jest przyjazd przewoźnika pobrana za pomocą zasobu /order/pickupRanges Tak
timeTo Godzina, do której planowany jest przyjazd przewoźnika pobrana za pomocą zasobu /order/pickupRanges Tak
Addon
Pole Opis Wymagane
id Identyfikator dodatku pobrany za pomocą zasobu /product/addons Tak
Dla każdego dodatku przekazujemy identyfikator. Poza tym dla określonych kategorii dodatków wymagane jest przesłanie dodatkowych parametrów. Lista znajduje się poniżej.
Kategoria dodatku Pole Opis Wymagane
INSURANCE value Wartość ubezpieczenia Tak
CASH_ON_DELIVERY value Wartość pobrania Tak
bankAccountNumber Numer konta bankowego Tak
name Nazwa klienta do przelewu Tak
addressLine1 Adres do przelewu linia 1 Tak
addressLine2 Adres do przelewu linia 2 Nie
RETURN_OF_DOCUMENTS type Typ dokumentów Nie
quantity Ilość dokumentów Nie
description Opis Nie
SENDER_WAYBILL_ADDRESS name Imię Tak
surname Nazwisko Tak
houseNumber Numer domu Tak
apartmentNumber Numer mieszkania Nie
street Ulica Tak
city Miasto Tak
postCode Kod pocztowy Tak
countryId Identyfikator kraju pobrany za pomocą zasobu /countries Tak
phone Numer telefonu Tak
email Adres E-mail Tak
type Typ klienta Tak

Przykładowe żądanie

Pole Wartość
collectionType
content
paymentId
discountCode
originId
instructions
declaredValue
purpose
agreements[receiveCommercialInfo]
shipment[length]
shipment[width]
shipment[height]
shipment[weight]
shipment[productId]
shipment[quantity]
pickup[date]
pickup[timeFrom]
pickup[timeTo]
senderAddress[name]
senderAddress[city]
senderAddress[street]
senderAddress[houseNumber]
senderAddress[apartmentNumber]
senderAddress[postCode]
senderAddress[countryId]
senderAddress[pointId]
senderAddress[stateId]
senderAddress[phone]
senderAddress[email]
senderAddress[contactPerson]
receiverAddress[name]
receiverAddress[city]
receiverAddress[street]
receiverAddress[houseNumber]
receiverAddress[apartmentNumber]
receiverAddress[postCode]
receiverAddress[countryId]
receiverAddress[pointId]
receiverAddress[stateId]
receiverAddress[phone]
receiverAddress[email]
receiverAddress[contactPerson]
userAddress[email]
userAddress[type]
userAddress[countryId]
userAddress[name]
userAddress[surname]
userAddress[street]
userAddress[houseNumber]
userAddress[apartmentNumber]
userAddress[city]
userAddress[postCode]
userAddress[phone]
userAddress[companyName]
userAddress[nip]
addons[0][id]
addons[0][bankAccountNumber]
addons[0][name]
addons[0][addressLine1]
addons[0][addressLine2]
addons[1][id]
addons[1][value]
addons[2][id]
addons[3][id]
referenceNumber
Nagłówek Wartość
accept-language
x-auth-token

Przykładowa odpowiedź

W odpowiedzi otrzymujemy numer, hash złożonego zamówienia oraz informacje o wycenie złożonego zamówienia lub listę błędow walidacji.

{
    "number": "GK161014996110",
    "hash":  "830f3038d3efey5edfec286e10c83add99d103e4bdc237c50335724c031e395f",
    "price": {
        "totalNetPrice": 123,
        "netPriceWithoutFuelSurcharge": 123,
        "totalGrossPrice": 123,
        "productNetPrice": 123,
        "addonsNetPrice": 0,
        "vatPercent": 0,
        "discountNetPrice": 0,
        "fuelSurcharge": 0
    }
}

Uproszczone składanie zamówienia

Uproszczony formularz składania zamówienia pozwala na złożenie zamówienia bez znajomości ID produktu oraz ID kraju.

Za pomocą nazwy integracji (integrationName) oraz kodu kraju (Kod ISO, bądź kod strefy) automat sam dobierze niezbędne parametry.

Niewymagana jest także znajomość ID dodatków. Wystarczy przekazać ich kategorie, a system sam dobierze wymagane dodatki.

Poniżej znajduje się lista zmienionych pól, które uległy zmianie w stosunku do składania zamówienia.

Endpoint

POST: /order/bestPrice

Parametry żądania

Pole Opis Wymagane
shipment[integrationName] Zamiennik dla pola shipment[productId]. W jego miejsce przekazana powinna zostać nazwa integracji. Tak
senderAddress[country] Zamiennik dla pola senderAddress[countryId]. W jego miejsce przekazany powinien zostać
kod ISO bądź kod strefy.
Tak
receiverAddress[country] Zamiennik dla pola receiverAddress[countryId]. W jego miejsce przekazany powinien zostać
kod ISO bądź kod strefy.
Tak
addons Lista wybranych dodatków (Addon[]).
Różnicą dla pól dodatków jest brak potrzeby przekazywania ID.
W zamian za to wymagane jest podanie kategori np. addons[INSURANCE][value]
Nie
receiverType Typ odbiorcy. Wymagany dla niektórych przewoźników.
Gdy nie przekazany domyślnie posiada wartość PERSON
Nie

Przykładowe żądanie

Pole Wartość
collectionType
content
paymentId
partnerProgramNumber
receiverType
discountCode
originId
instructions
declaredValue
purpose
shipment[length]
shipment[width]
shipment[height]
shipment[weight]
shipment[integrationName]
shipment[quantity]
pickup[date]
pickup[timeFrom]
pickup[timeTo]
senderAddress[name]
senderAddress[city]
senderAddress[street]
senderAddress[houseNumber]
senderAddress[apartmentNumber]
senderAddress[postCode]
senderAddress[country]
senderAddress[pointId]
senderAddress[phone]
senderAddress[email]
senderAddress[contactPerson]
receiverAddress[name]
receiverAddress[city]
receiverAddress[street]
receiverAddress[houseNumber]
receiverAddress[apartmentNumber]
receiverAddress[postCode]
receiverAddress[country]
receiverAddress[pointId]
receiverAddress[phone]
receiverAddress[email]
receiverAddress[contactPerson]
addons[CASH_ON_DELIVERY][value]
addons[CASH_ON_DELIVERY][bankAccountNumber]
addons[CASH_ON_DELIVERY][name]
addons[CASH_ON_DELIVERY][addressLine1]
addons[CASH_ON_DELIVERY][addressLine2]
addons[INSURANCE][value]
referenceNumber
Nagłówek Wartość
accept-language
x-auth-token

Przykładowa odpowiedź

W odpowiedzi otrzymujemy numer, hash złożonego zamówienia oraz informacje o wycenie złożonego zamówienia lub listę błędow walidacji.

{
    "number": "GK161014996110",
    "hash":  "830f3038d3efey5edfec286e10c83add99d103e4bdc237c50335724c031e395f",
    "price": {
        "totalNetPrice": 123,
        "netPriceWithoutFuelSurcharge": 123,
        "totalGrossPrice": 123,
        "productNetPrice": 123,
        "addonsNetPrice": 0,
        "vatPercent": 0,
        "discountNetPrice": 0,
        "fuelSurcharge": 0
    }
}

Szablon przesyłki

Dodanie szablonu przesyłki

Endpoint

POST: /order/productTemplate

Parametry żądania

Pole Opis Wymagane
name Nazwa (max 100 znaków) Tak
content Zawartość przesyłki (max 100 znaków) Tak
shipment Dane przesyłki (Shipment) Tak
senderAddress Address Dane nadawcy
receiverAddress Address Dane odbiorcy
Shipment
Pole Opis Wymagane
length Długość przesyłki w cm Tak
width Szerokość przesyłki w cm Tak
height Wysokość przesyłki w cm Tak
weight Waga przesyłki w kg z maksymalną dokładnością do 2 miejsc po kropce Tak
productId Identyfikator produktu pobrany za pomocą zasobu /products Tak
quantity Ilość paczek w przesyłce Tak

Struktura odpowiedzi

Pole Typ Opis
id int Identyfikator szablonu

Przykładowe żądanie

Pole Wartość
name
content
shipment[length]
shipment[width]
shipment[height]
shipment[weight]
shipment[productId]
shipment[quantity]
senderAddress[name]
senderAddress[city]
senderAddress[street]
senderAddress[houseNumber]
senderAddress[apartmentNumber]
senderAddress[postCode]
senderAddress[countryId]
senderAddress[pointId]
senderAddress[stateId]
senderAddress[phone]
senderAddress[email]
senderAddress[contactPerson]
receiverAddress[name]
receiverAddress[city]
receiverAddress[street]
receiverAddress[houseNumber]
receiverAddress[apartmentNumber]
receiverAddress[postCode]
receiverAddress[countryId]
receiverAddress[pointId]
receiverAddress[stateId]
receiverAddress[phone]
receiverAddress[email]
Nagłówek Wartość
accept-language
x-auth-token

Przykładowa odpowiedź

{"id": "1"}

Pobranie listy szablonów przesyłek

Endpoint

GET: /order/productTemplate

Endpoint udostępnia paginację. Parametry z nią związane są opisane tutaj.

Dostępne filtry

Pole Typ Opis
id int Identyfikator szablonu
productId int Identyfikator produktu - ten sam, który można uzyskać korzystając z wyszukiwarki
name string Ciąg znaków służący do wyszukiwania szablonów po ich nazwie. Wielkość liter nie ma wpływu na wyniki.

Struktura odpowiedzi

Pole Typ Opis
ProductTemplate[] Lista szablonów przesyłek
ProductTemplate
Pole Typ Opis
id int Identyfikator
name string Nazwa
created datetime Czas utworzenia
updated datetime|null Czas ostatniej modyfikacji. Brak daty oznacza, że dane nie były nigdy modyfikowane
content string Zawartość przesyłki
length int Długość [cm]
width int Szerokość [cm]
height int Wysokość [cm]
weight float Waga [kg] z dokładnością do 2 miejsc po przecinku
quantity int Liczba paczek/palet w przesyłce
senderAddress int Dane nadawcy
receiverAddress int Dane odbiorcy
productId int Identyfikator produktu (/products)
productName string Nazwa produktu

Przykładowe żądanie

Pole Wartość
filters[id]
filters[name]
filters[productId]
offset
limit
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź


                    {
                        "offset": 0,
                        "total": 3,
                        "limit": 25,
                        "results": [
                            {
                                "id": 1,
                                "name": "test",
                                "created": "2018-09-01 12:00:00",
                                "updated": null,
                                "content": "content",
                                "length": 2,
                                "width": 3,
                                "height": 4,
                                "weight": 5.25,
                                "quantity": 6,
                                "senderCountryId": 1,
                                "receiverCountryId": 1,
                                "productId": 1,
                                "productName": "Package up to 30kg",
                                "senderAddress": null,
                                "receiverAddress": null
                            },
                            {...},
                            {...}
                        ]
                    }

Edycja szablonu przesyłki

Endpoint

PUT: /order/productTemplate

Parametry żądania

Pole Opis Wymagane
id Identyfikator szablonu Tak
name Nazwa (max 100 znaków) Tak
content Zawartość przesyłki (max 100 znaków) Tak
shipment Dane przesyłki (Shipment) Tak
senderAddress Address Dane nadawcy
receiverAddress Address Dane odbiorcy
Shipment
Pole Opis Wymagane
length Długość przesyłki w cm Tak
width Szerokość przesyłki w cm Tak
height Wysokość przesyłki w cm Tak
weight Waga przesyłki w kg z maksymalną dokładnością do 2 miejsc po kropce Tak
productId Identyfikator produktu pobrany za pomocą zasobu /products Tak
quantity Ilość paczek w przesyłce Tak

Struktura odpowiedzi

Zasób zwraca status 204 po zapisaniu danych.

Przykładowe żądanie

Pole Wartość
id
name
content
shipment[length]
shipment[width]
shipment[height]
shipment[weight]
shipment[productId]
shipment[quantity]
senderAddress[name]
senderAddress[city]
senderAddress[street]
senderAddress[houseNumber]
senderAddress[apartmentNumber]
senderAddress[postCode]
senderAddress[countryId]
senderAddress[pointId]
senderAddress[stateId]
senderAddress[phone]
senderAddress[email]
senderAddress[contactPerson]
receiverAddress[name]
receiverAddress[city]
receiverAddress[street]
receiverAddress[houseNumber]
receiverAddress[apartmentNumber]
receiverAddress[postCode]
receiverAddress[countryId]
receiverAddress[pointId]
receiverAddress[stateId]
receiverAddress[phone]
receiverAddress[email]
Nagłówek Wartość
accept-language
x-auth-token
PUT: 

Usunięcie szablonu przesyłki

Endpoint

DELETE: /order/productTemplate

Parametry żądania

Pole Opis Wymagane
id Identyfikator szablonu Tak

Przykładowe żądanie

Pole Wartość
id
Nagłówek Wartość
accept-language
x-auth-token
DELETE: 

Przykładowa odpowiedź

"OK"

Płatność online

Płatności online mogą być obarczone stałą prowizją 1% od wartości zamówienia. Wartość ta nie pojawia się w momencie wyświetlenia listy płatności z metody pobrania płatności.

Pobranie listy dostępnych metod

Endpoint

GET: /onlinePayment/methods

Struktura odpowiedzi

Pole Typ Opis
OnlinePaymentMethod[] Lista dostępnych metod płatności online
OnlinePaymentMethod
Pole Typ Opis
id int Identyfikator metody płatności online
name string Nazwa metody płatności online
imagePath string Ścieżka do pliku z obrazkiem metody płatności online (np. ikona banku)

Przykładowa odpowiedź

[
   {
      "id" : 34,
      "imagePath" : "http://www.globkurier.pl/images/online-banks/alior.png"
      "name" : "Alior Bank",
   },
   {
      "id" : 26,
      "name" : "Bank BPH"
      "imagePath" : "http://www.globkurier.pl/images/online-banks/bph.png",
   }
]

Przykładowe żądanie

Nagłówek Wartość
accept-language

Generowanie danych formularza dla płatności online za zamówienie

Endpoint

POST: /onlinePayment/generateForm/order

Parametry żądania

Pole Opis Wymagane
onlinePaymentMethodId Identyfikator metody płatności pobrany z zasobu /onlinePayments/methods Tak
orderHash 64 znakowy identyfikator zamówienia uzyskany po jego utworzeniu metodą /order. Zamówienie musi należeć do użytkownika, do którego należy przekazany token. Tak

Struktura odpowiedzi

Pole Typ Opis
url string Adres URL dostawcy płatności
fields Field[] Lista pól formularza
Field
Pole Typ Opis
name string Nazwa pola formularz
value string Wartość pola formularza

Przykładowa odpowiedź

{
  "url": "https://pay.ecard.pl/payment/PS",
  "fields": [
    {
      "name": "ORDERNUMBER",
      "value": null
    },
    {
      "name": "ORDERDESCRIPTION",
      "value": 234234
    },
    {
      "name": "AMOUNT",
      "value": 44444330
    },
    {
      "name": "NAME",
      "value": "Imię"
    },
    {
      "name": "SURNAME",
      "value": "Nazwisko"
    },
    //(...)
    {
      "name": "CURRENCY",
      "value": 985
    },
    {
      "name": "MERCHANTID",
      "value": "173729000"
    },
    {
      "name": "COUNTRY",
      "value": 616
    }
  ]
}

Przykładowe żądanie

Pole Wartość
onlinePaymentMethodId
orderHash
Nagłówek Wartość
accept-language
x-auth-token

Doładowanie prepaid

Endpoint

POST: /onlinePayment/generateForm/prepaidRecharge

Parametry żądania

Pole Opis Wymagane
onlinePaymentMethodId Identyfikator metody płatności pobrany z zasobu /onlinePayments/methods Tak
amount Kwota Tak

Struktura odpowiedzi

Pole Typ Opis
url string Adres URL dostawcy płatności
fields Field[] Kolekcja pól formularza

Przykładowa odpowiedź

{
  "url": "https://pay.ecard.pl/payment/PS",
  "fields": [
    {
      "name": "ORDERNUMBER",
      "value": null
    },
    {
      "name": "ORDERDESCRIPTION",
      "value": 234234
    },
    {
      "name": "AMOUNT",
      "value": 44444330
    },
    {
      "name": "NAME",
      "value": "Imię"
    },
    {
      "name": "SURNAME",
      "value": "Nazwisko"
    },
    //(...)
    {
      "name": "CURRENCY",
      "value": 985
    },
    {
      "name": "MERCHANTID",
      "value": "173729000"
    },
    {
      "name": "COUNTRY",
      "value": 616
    }
  ]
}

Przykładowe żądanie

Pole Wartość
onlinePaymentMethodId
amount
Nagłówek Wartość
accept-language
x-auth-token

Książka adresowa

Dodanie kontaktu do książki adresowej

Endpoint

Nadawcy:

POST: /user/addressBook/sender

Odbiorcy:

POST: /user/addressBook/receiver

Parametry żądania

Pole Opis Wymagane
contact[name] Nazwa (max 150 znaków) Tak
contact[email] E-mail Tak
contact[street] Ulica Tak
contact[houseNumber] Nr budynku Tak
contact[apartmentNumber] Nr lokalu Nie
contact[postCode] Kod pocztowy Tak
contact[city] Miejscowość Tak
contact[ccountryId] Identyfikator kraju pobrany za pomocą zasobu /countries Tak
contact[contactPerson] Osoba kontaktowa Nie
contact[phone] Nr telefonu Tak
contact[tin] NIP Nie

Struktura odpowiedzi

Pole Typ Opis
id int Identyfikator kontaktu

Przykładowe żądanie

Pole Wartość
contact[name]
contact[email]
contact[street]
contact[houseNumber]
contact[apartmentNumber]
contact[postCode]
contact[city]
contact[contactPerson]
contact[phone]
contact[tin]
Nagłówek Wartość
accept-language
x-auth-token

Przykładowa odpowiedź

{"id": "1"}

Pobranie książki adresowej

Endpoint nadawcy

GET: /user/addressBook/senders

Endpoint odbiocy

GET: /user/addressBook/receivers

Parametry żądania

Endpoint udostępnia paginację. Parametry z nią związane są opisane tutaj.

Dostępne filtry

Pole Typ Opis
phrase string Ciąg znaków służący do wyszukiwania rekordów po ich nazwie. Wielkość liter oraz używanie znaków diakrytycznych nie ma wpływu na wynik działania.

Struktura odpowiedzi

Jest zgodna z paginacją

W parametrze results zawierać będzie się lista kontaktów.

Struktura odpowiedzi - kontakt

Pole Typ Opis
id string Identyfikator kontaktu
name string Nazwa kontaktu
email string E-mail
street string Ulica
houseNumber string Nr budynku
apartmentNumber string Nr lokalu
postCode string Kod pocztowy
city string Miasto
countryId integer Identyfikator kraju
contactPerson string Osoba kontaktowa
phone string Telefon
tin string NIP
editable string Informacja, czy użytkownik może zmienić stan wpisu.

Przykładowe żądanie

Pole Wartość
offset
limit
filters[phrase]
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

{
    "offset": 0,
    "total": 1,
    "limit": 25,
    "results": [
        {
            "id": "1",
            "name": "Test Contact",
            "email": "it@globkurier.pl",
            "street": "Testowa",
            "houseNumber": "1",
            "apartmentNumber": "25",
            "postCode": "42-226",
            "city": "Cz\u0119stochowa",
            "phone": "48111222333",
            "contactPerson": "contact person",
            "tin": "9541875594",
            "editable": "true"
        }
    ]
}

Edycja kontaktu w książce adresowej

Endpoint

Nadawcy:

PUT: /user/addressBook/sender

Odbiorcy:

PUT: /user/addressBook/receiver

Parametry żądania

Pole Opis Wymagane
contact[id] Identyfikator kontaktu (/user/addressBook/receiver) Tak
contact[name] Nazwa (max 150 znaków) Tak
contact[email] E-mail Tak
contact[street] Ulica Tak
contact[houseNumber] Nr budynku Tak
contact[apartmentNumber] Nr lokalu Nie
contact[postCode] Kod pocztowy Tak
contact[city] Miejscowość Tak
contact[countryId] Identyfikator kraju pobrany za pomocą zasobu /countries Tak
contact[contactPerson] Osoba kontaktowa Nie
contact[phone] Nr telefonu Tak
contact[tin] NIP Nie

Struktura odpowiedzi

Zasób zwraca status 204 po zapisaniu danych.

Przykładowe żądanie

Pole Wartość
contact[id]
contact[name]
contact[email]
contact[street]
contact[houseNumber]
contact[apartmentNumber]
contact[postCode]
contact[city]
contact[contactPerson]
contact[phone]
contact[tin]
Nagłówek Wartość
accept-language
x-auth-token

Usunięcie kontaktu z książki adresowej

Endpoint

Nadawcy:

DELETE: /user/addressBook/sender

Obiorcy:

DELETE: /user/addressBook/receiver

Parametry żądania

Pole Opis Wymagane
id Identyfikator kontaktu Tak

Przykładowe żądanie

Pole Wartość
id
Nagłówek Wartość
accept-language
x-auth-token
DELETE: 

Przykładowa odpowiedź

"OK"

Użytkownik

Pobranie danych użytkownika

Endpoint

GET: /user/profile

Struktura odpowiedzi

Pole Typ Opis
userNumber int Numer klienta w programie partnerskim
isAccountBlocked bool Czy konto główne klienta jest zablokowane.
Blokada może zostać nałożona z różnych powodów m.in. za nieuregulowane płatności, nadużycia, złamanie regulaminu.
W celu zdjęcia blokady skontaktuj się z Biurem Obsługi Klienta .
cashOnDelivery CashOnDelivery Domyślne dane do płatności za pobraniem
address Address Dane użytkownika
subUserAddress Address Dane konta sub-użytkownika (uzupełnione, jeśli token należy do sub-konta)
taxesArePaidAbroad bool Rozliczanie podatku VAT w kraju innym niż Polska
notifications Notifications Ustawienia wysyłki powiadomień
agreements Agreements Zgody
currency string Domyślna waluta, w jakiej ma zostać wystawiona faktura
Notifications
Pole Typ Opis
sendInvoicesToOtherEmail bool Chcę otrzymywać faktury na osobny adres e-mail
otherEmailForInvoices string Osobny email do faktur
sendDiscountCodes bool Chcę otrzymywać kody rabatowe
sendLabel bool Chcę otrzymywać wiadomości e-mail z etykietami
sendLabelsToOtherEmail bool Chcę otrzymywać etykiety na osobny adres e-mail
otherEmailForLabels string Osobny email do etykiet
sendInfoOnSubAccountOrderCreation bool Chcę otrzymywać powiadomienia o dokonaniu zamówień z subkont
sendInfoOnTrackingStatusUpdate bool Chcę otrzymywać powiadomienia o zmianie statusu zamówienia
sendInfoOnOrderCreation bool Chcę otrzymywać powiadomienia o utworzeniu nowego zamówienia
sendSalesAds bool|null Chcę otrzymywać informacje o promocjach i nowych usługach. Może pojawić się NULL oznaczający, że użytkownik jeszcze się nie określił. Można to również traktować, jako brak zgody.
CashOnDelivery
Pole Typ Opis
bankAccountNumber string Numer konta bankowego
name string Nazwa klienta do przelewu
addressLine1 string Adres do przelewu linia 1
addressLine2 string Adres do przelewu linia 2

Przykładowe żądanie

Pole Wartość
Brak
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

{
    "userNumber": 1234567,
    "isAccountBlocked": false,
    "cashOnDelivery": {
        "bankAccountNumber": "",
        "name": "",
        "addressLine1": "",
        "addressLine2": ""
    },
    "address": {
        "regon": null,
        "nip": null,
        "name": "Imię",
        "surname": "Nazwisko",
        "street": "Testowa",
        "apartmentNumber": "2D",
        "houseNumber": "2",
        "city": "Katowice",
        "postCode": "42-226",
        "countryId": 1,
        "phone": "48111222333",
        "email": "test3@testmail.pl",
        "companyName": null,
        "type": "PERSON"
    },
    "subUserAddress": null,
    "taxesArePaidAbroad": false,
    "notifications": {
        "sendInvoicesToOtherEmail": false,
        "otherEmailForInvoices": null,
        "sendPaperInvoices": false,
        "sendDiscountCodes": true,
        "sendLabel": true,
        "sendInfoOnSubAccountOrderCreation": true,
        "sendInfoOnSubAccountProformaInvoiceCreation": true,
        "sendInfoOnTrackingStatusUpdate": false,
        "sendInfoOnOrderCreation": true
    },
    "agreements": {
        "receiveCommercialInfo": true
    }
}

Pobranie danych bonu użytkownika

Endpoint

GET: /user/couponStats

Parametry żądania

Pole Opis Wymagane
couponId Identyfikator bonu Tak

Struktura odpowiedzi

Pole Typ Opis
isCouponPaymentAvailable bool Informacja o tym czy możliwe jest w danym momencie złożenie zamówienia z użyciem bonu na podany produkt
couponGrantDate string Data przyznania użytkownikowi bonu
globalAllowedProductsQuantity int|null Całkowita ilość możlwych do zamówienia produktów w ramach danego bonu lub null w przypadku braku limitu
globalUsedProductsQuantity int Całkowita ilość zakupionych produktów w ramach bonu
firstDayOfMonthAvailableToOrder int|null Dzień miesiąca, od którego można złożyć zamówienie z użyciem bonu
(Jeśli obowiązują obydwa limity dotyczące dnia miesiąca łączy je warunek OR)
lastDayOfMonthAvailableToOrder int|null Dzień miesiąca, do którego można złożyć zamówienie z użyciem bonu
(Jeśli obowiązują obydwa limity dotyczące dnia miesiąca łączy je warunek OR)
period Period Limit okresowy
Period
Pole Typ Opis
allowedProductsQuantity int|null Limit ilości możlwych do zamówienia produktów w ramach danego bonu w czasie jednego okresu
usedProductsQuantity int Ilość zakupionych produktów w ramach bonu w czasie bieżącego okresu
startDate string Data początku bieżącego okresu
endDate string Data końca bieżącego okresu

Przykładowe żądanie

Pole Wartość
couponId
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

{
	"isCouponPaymentAvailable": true,
	"couponGrantDate": "2015-01-12",
	"globalAllowedProductsQuantity": 12,
	"globalUsedProductsQuantity": 1,
	"firstDayOfMonthAvailableToOrder": null,
	"lastDayOfMonthAvailableToOrder": null,
	"period": {
		"allowedProductsQuantity": 2,
		"usedProductsQuantity": 1,
		"startDate": "2017-03-12",
		"endDate": "2017-04-12"
	}
}

Rejestracja użytkowników

Endpoint

POST: /user

Parametry żądania

Pole Opis Wymagane
password Hasło użytkownika Tak
address Dane zleceniodawcy (Address) Tak
agreements Zgody (Agreements) Tak
taxesArePaidAbroad Deklaracja rozliczania podatku VAT w kraju innym niż Polska. Potwierdzenie wymagane dla klientów zagranicznych o typie COMPANY. Wymagane, jeśli typ klienta to COMPANY i jego kraj jest inny niż Polska
gRecaptchaResponse Kod reCAPTCHA Tak
partnerProgramNumber Numer klienta jako programu partnerskiego Nie
Agreements
Pole Typ Opis Wymagane
receiveElectronicBills bool Zgoda na wystawiania faktur w formie elektronicznej. Tak
processingPersonalData bool Zgoda na przechowywanie i przetwarzanie danych osobowych przez firmę GRUPA ZNATURY SP. Z O.O. operatora GlobKurier.pl oraz potwierdzenie zapoznania się z regulaminem serwisu jak i regulamien przewoźników. Tak
receiveCommercialInfo bool Zgoda na otrzymywanie informacji handlowych od firmy GRUPA ZNATURY SP. Z O.O., operatora GlobKurier.pl, dotyczących jej oferty oraz ofert jej partnerów biznesowych, a także zgodę na przetwarzanie moich danych osobowych przez firmę GRUPA ZNATURY SP. Z O.O., operatora GlobKurier.pl, w celach promocji, reklamy i badania rynku. Nie

Kod reCAPTCHA

W celu weryfikacji człowieczeństwa osoby tworzącej konto API korzysta z mechanizmu captcha za pomoca narzędzia reCAPTCHA. Aby wygenerować kod wymagany do rejestracji, należy dodać następujący nagłówek:

<script src="//www.google.com/recaptcha/api.js?hl=pl" async defer></script>

oraz w formularzu umieścić kod reCAPTCHA i obsłużyć odpowiedź. Przykładowa obsługa może wyglądać następująco:

<script>
    function captchaResponseHandler(response) {
        console.log(response); //zapis i obsługa odpowiedzi
    }
</script>

<div class="g-recaptcha"
     data-sitekey="6LdPuicTAAAAAGBs4H_N5aPjylxnD4yiSQIN3y0n"
     data-callback="saveResponse"></div>

Pełna dokumentacja reCaptcha znajduje się tutaj.

Struktura odpowiedzi

Pole Typ Opis
number int Numer utworzonego klienta
token string Token autoryzacyjny

Przykładowe żądanie

Pole Wartość
password
agreements[receiveElectronicBills]
agreements[processingPersonalData]
agreements[receiveCommercialInfo]
gRecaptchaResponse
taxesArePaidAbroad
address[email]
address[type]
address[countryId]
address[name]
address[surname]
address[street]
address[houseNumber]
address[apartmentNumber]
address[city]
address[postCode]
address[phone]
address[companyName]
address[nip]
partnerProgramNumber
Nagłówek Wartość
accept-language

Przykładowa odpowiedź

W odpowiedzi otrzymujemy numer utworzonego konta klienta oraz aktywny token autoryzacyjny.

{
    "number": "3747813",
    "token": "1a10a42dcb5065478c6f49f68493f5ddeb31cadcfacbe5ad25aa1cd3564b895e"
}

Edycja użytkownika

Endpoint

PUT: /user

Parametry żądania

Pole Opis Wymagane
address Dane użytkownika (Address).
Pole countryId jest nieobsługiwane.
Tak
notifications Powiadomiania (Notifications) Tak
agreements Zgody (Agreements) Tak
cashOnDelivery Domyślne dane do płatności za pobraniem (CashOnDelivery) Tak
currency Waluta, w jakiej wystawiona ma zostać faktura
Możliwe waluty to: PLN, EUR
Nie

Struktura odpowiedzi

Zasób zwraca status 204 po zapisaniu danych.

Przykładowe żądanie

Pole Wartość
address[email]
address[countryId]
address[type]
address[name]
address[surname]
address[street]
address[houseNumber]
address[apartmentNumber]
address[city]
address[postCode]
address[phone]
address[nip]
address[companyName]
cashOnDelivery[bankAccountNumber]
cashOnDelivery[name]
cashOnDelivery[addressLine1]
cashOnDelivery[addressLine2]
notifications[sendInvoicesToOtherEmail]
notifications[otherEmailForInvoices]
notifications[sendPaperInvoices]
notifications[sendDiscountCodes]
notifications[sendLabel]
notifications[sendLabelsToOtherEmail]
notifications[otherEmailForLabels]
notifications[sendInfoOnSubAccountOrderCreation]
notifications[sendInfoOnSubAccountProformaInvoiceCreation]
notifications[sendInfoOnTrackingStatusUpdate]
notifications[sendInfoOnOrderCreation]
agreements[receiveCommercialInfo]
currency
Nagłówek Wartość
accept-language
x-auth-token

Pobranie informacji o firmie

Endpoint służy do pobrania informacji o firmie, w celu weryfikacji ich poprawności, przez użytkownika przed założeniem konta. W odpowiedzi zwrócony zostanie obiekt Address zawierający wszystkie uzyskane informacje uzyskane z systemu GUS lub VEIS.

Endpoint

GET: /user/company

Parametry żądania

Pole Opis Wymagane
countryId Identyfikator kraju pobrany za pomocą zasobu /countries Tak
tin Numer identyfikacji podatkowej (lub Europejski numer VAT dla klientów UE) Tak

Przykładowe żądanie

Pole Opis Wymagane
countryId
tin
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Lista faktur użytkownika

Endpoint

GET: /user/invoices

Struktura odpowiedzi

Pole Typ Opis
Invoice[] Lista faktur
Invoice
Pole Typ Opis
number string Identyfikator
orderDate string Data zamówienia
priceGross float Cena brutto
priceNet float Cena netto
paymentDueDate string Termin zapłaty
link string Link do faktury
amountToPay float Kwota pozostała do zapłaty

Przykładowe żądanie

Pole Opis Wymagane
Brak
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

[
    {
        "number": "1/GK/K/01/2017",
        "orderDate": "2017-01-31",
        "priceGross": 65.33,
        "priceNet": 53.11,
        "paymentDueDate": "2017-01-31",
        "link": "http://api.globkurier.pl/v1/invoice?hash=104745b285bedbb667c59b135d9b9a74770af9bf",
        "amountToPay": 0
    },
    {...},
    {...}
]

Wyświetlenie faktury

Link do strony, pod którą dostępna do pobrania będzie wybrana faktura

Endpoint

GET: /invoice

Parametry żadania

Pole Typ Opis
hash string Hash faktury

Przykładowe żądanie

Pole Wartość
hash
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Statystyki konta płatności

Endpoint

GET: /user/stats

Struktura odpowiedzi

Pole Typ Opis
FinancialAccountStats[] Statystki finansowe konta
FinancialAccountStats
Pole Typ Opis
excessPayment float Nadpłata - środki powstałe jako nadwyżka wpłat klienta mogące zostać przeznaczone na inne działania, takie jak opłata bieżących należności lub mogące zostać mu zwrócone. W ten rodzaj środków nie wlicza się operacji prepaid.
receivablePayment float Należności - środki oczekujące na uregulowanie w tym te, do których minął okres odroczenia. W ten rodzaj środków nie wlicza się operacji prepaid.
prepaidBalance float Saldo prepaid - wypadkowa wpłat i wypłat dostępnymi metodami prepaid.
deferredBalance float Saldo płatności odroczonych - łączna kwota wpłat będąca w okresie odroczenia. Po minięciu terminu odroczenia wejdą one w stan należności.
packageCountInCurrentMonth int Liczba paczek zamawianych w bieżącym miesiącu.

Przykładowe żądanie

Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

{
    "excessPayment": 0,
    "receivablePayment": 1818.27,
    "prepaidBalance": -11.98,
    "deferredBalance": 0,
    "packageCountInCurrentMonth": 0
}

Pobranie listy metod płatności

Metoda zachowuje się podobnie do pobierania płatności.

Zwraca listę dostępnych metod płatności dla zalogowanego użytkownika

Endpoint

GET: /user/payment/methods

Struktura odpowiedzi

Typ Opis
Payment[] Lista płatności

Przykładowe żądanie

Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

[
    {
        "id": 2,
        "name": "Płatność online",
        "enabled": true,
        "default": true,
        "price": null
    },
    {...},
    {...}
]

Pobranie wybranej metody płatności

Zwraca informacje o metodzie płatności zapisanej przez użytkownika

Endpoint

GET: /user/payment/default

Struktura odpowiedzi

Pole Typ Opis
paymentId integer ID wybranej metody płatności
onlinePaymentId integer ID metody płatności online

Przykładowe żądanie

Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

{
    "paymentId": 2,
    "onlinePaymentId": 1
}

Zapisanie wybranej metody płatności

Endpoint

POST: /user/payment/default

W odpowiedzi zwracany jest kod 201 lub informacja o błędach dla każego z pól

Pole Typ Opis
paymentId integer ID metody platności
onlinePaymentId integer ID metody płatnośći online

Przykładowe żądanie

Pole Opis Wymagane
paymentId
onlinePaymentId
Nagłówek Wartość
accept-language
x-auth-token

Usunięcie wyboru metody płatności

Endpoint

DELETE: /user/payment/default

W odpowiedzi zwracany jest jest kod 204 jeśli zapytanie jest prawidłowe.

Przykładowe żądanie

Nagłówek Wartość
accept-language
x-auth-token
DELETE: 

Inne

Pobranie listy krajów

Endpoint

GET: /countries

Struktura odpowiedzi

Pole Typ Opis
Country[] Lista krajów
Country
Pole Typ Opis
id int Identyfikator
name string Nazwa
isoCode string Kod kraju, bazujący na standardzie ISO 3166-1 alfa-2 z dodanym identyfikatorem regionu np. GB3: Wielka Brytania - Szkocja
isUEMember bool Czy jest członkiem Unii Europejskiej
isRoadTransportAvailable bool Czy jest dostępny transport drogowy
hasStates bool Czy można skorzystać z zasobu /states w celu pobrania listy stanów/regionów
hasPostCodes bool Czy w danym kraju obowiązują kody pocztowe
postCodeFormat string|null Dozwolone formaty kodu pocztowego lub null jeśli nie obowiązują.
Separator: , (przecinek).
  • a litera
  • ? cyfra
postCodeSamples string|null Przykłady poprawnych kodów pocztowych pod względem formatu lub null jeśli nie obowiązują.
Separator: , (przecinek).
  • a litera
  • ? cyfra

Przykładowe żądanie

Pole Opis Wymagane
Brak
Nagłówek Wartość
accept-language
GET: 

Przykładowa odpowiedź

[
    {
        "id": 101,
        "name": "Angola",
        "isoCode": "AO",
        "isUEMember": false,
        "isRoadTransportAvailable": false,
        "hasStates": false,
        "hasPostCodes": false,
        "postCodeFormat" : null,
        "postCodeSamples" : null
    },
    {
        "id": 28,
        "name": "Szkocja",
        "isoCode": "GB3",
        "isUEMember": true,
        "isRoadTransportAvailable": true,
        "hasStates": false,
        "hasPostCodes": true,
        "postCodeFormat" : "a? ?aa, a?? ?aa, a?a ?aa, aa? ?aa, aa?? ?aa, aa?a ?aa",
        "postCodeSamples" : "A1 2BC, D34 5EF, G6H 7IJ, KL8 9MN, OP12 3QR, ST4U 5VW"
    },
    {...},
    {...}
]

Pobranie polskich adresów

Zwraca zakresy polskich adresów na bazie przesłanych parametrów. Funkcjonalność wspierająca automatyczne uzupełnianie miasta na bazie kodu pocztowego. Można wyszukiwać adres podając kod pocztowy lub miasto i ulicę.

Endpoint

GET: /addresses

Parametry żądania

Pole Opis Wymagane
city Miasto Wymagane, gdy pole street jest wypełnione
street Ulica Wymagane, gdy pole city jest wypełnione
postCode Kod pocztowy w formacie 00-000 Wymagane, gdy pole city i street są niewypełnione

Struktura odpowiedzi

Pole Typ Opis
Address[] Lista adresów
Address
Pole Typ Opis
postCode string Kod pocztowy
state string Województwo
city string Miasto
street string Ulica z opcjonalnym zakresem numerów domów

Przykładowe żądanie

Pole Wartość
city
street
postCode
Nagłówek Wartość
accept-language
GET: 

Przykładowa odpowiedź

[
    {
        "postCode": "42-110",
        "state": "śląskie",
        "city": "Popów",
        "street": "ul. Popów 48"
    },
    {...},
    {...}
]

Pobranie stanów/regionów

Funkcjonalność wykorzystujemy jeśli wywołanie /customRequiredFields wskazuje iż konieczne jest podanie stanu nadawcy lub odbiorcy w procesie zapisu/walidacji zamówienia.

Endpoint

GET: /states

Parametry żądania

Pole Opis Wymagane
countryId Identyfikator kraju pobrany za pomocą zasobu /countries Tak

Struktura odpowiedzi

Pole Typ Opis
State[] Lista stanów/regionów
State
Pole Typ Opis
id int Identyfikator
code string Kod krajowy
isoCode string Kod ISO
name string Nazwa
localName string Nazwa w lokalnym języku

Przykładowe żądanie

Pole Wartość
countryId
Nagłówek Wartość
accept-language
GET: 

Przykładowa odpowiedź

[
    {
        "id": 49,
        "code": "AK",
        "isoCode": "US-AK",
        "name": "Alaska",
        "localName": "Alaska"
    },
    {...},
    {...}
]

Pobranie punktów nadania/odbioru

Endpoint

GET: /points

Parametry żądania

Pole Opis Wymagane
id Identyfikator punktu nadania/odbioru Nie
productId Identyfikator produktu pobrany za pomocą zasobu /products Tak
isCashOnDeliveryAddonSelected Czy został wybrany dodatek z kategorii CASH_ON_DELIVERY.
Pole niedostępne jeśli podano id.
Tak, jeśli nie podano id
city Miasto, jeśli podano zwrócone zostaną punkty z danego miasta.
Pole niedostępne jeśli podano id.
Nie
postCode Kod pocztowy, jeśli podano zwrócone zostaną punkty o podanym kodzie pocztowym lub w jego okolicach.
Pole niedostępne jeśli podano id.
Nie

Struktura odpowiedzi

Pole Typ Opis
Point[] Lista punktów
Point
Pole Typ Opis
id int Identyfikator
address string Adres (ulica nr budynku/nr mieszkania)
city string Miasto
postCode string Kod pocztowy
openingHours string Godziny otwarcia
cashOnDeliveryAvailable bool Czy jest dostępna usługa pobrania

Przykładowe żądanie

Pole Wartość
id
productId
isCashOnDeliveryAddonSelected
city
postCode
Nagłówek Wartość
accept-language
GET: 

Przykładowa odpowiedź

[
    {
        "id": "197550",
        "address": "Elektronowa 1",
        "city": "Zielona Góra",
        "postCode": "65-900",
        "openingHours": null,
        "cashOnDeliveryAvailable": true
    },
    {...},
    {...}
]

Pobranie zamówienia

Endpoint

GET: /order

Parametry żądania

Pole Opis Wymagane
number Numer zamówienia Tak

Struktura odpowiedzi

Pole Typ Opis
number string Numer
creationDate string Data utworzenia
status string Status zamówienia
purpose string Cel przesyłki
content string Zawartość zamówienia
instructions string Instrukcje dla przewoźnika
paymentId string Identyfikator płatności (/order/payments)
originId string Identyfikator źródła zamówienia
discountCode string Kod rabatowy użyty w zamówieniu
declaredValue float Deklarowana wartość
pricing Pricing Koszta zamówienia
senderAddress Address Dane nadawcy
receiverAddress Address Dane odbiorcy
userAddress UserAddress Dane zamawiającego
shipment Shipment Dane przesyłki
addons Addon[] Lista wybranych dodatków
pickup Pickup[] Dane odbioru przesyłki przez przewoźnika jeśli został wybrany taki typ nadania
financialDocuments FinancialDocument[] Lista dokumentów finansowych
transportDocuments TransportDocument[] Lista dokumentów transportowych
hash string Hash
referenceNumber string Nr referencyjny
links Link[] Linki zasobów do możliwych działań
Pricing
Pole Typ Opis
priceGross float Cena brutto
priceNet float Cena netto
vatPercent int Procent VAT
Addon

Lista dodatków wybranych w zamówieniu zwracana jest w strukturze podobnej do tej dla zapisu zamówienia, ale rozszerzoną o dodatkowe informacje dla niektórych dodatków.

Kategoria dodatku Pole Opis
CASH_ON_DELIVERY status Status środków pieniężnych z pobrania
CashOnDeliveryStatus
Pole Typ Opis
name string Nazwa statusu
description string Opis
returnDate string Data zwrotu środków z pobrania
CashOnDeliveryStatus - możliwe wartości
Nazwa statusu Opis
WAITING_FOR_DELIVERY Przesyłka oczekuje na doręczenie do adresata
WAITING_FOR_TRANSFER Środki z pobrania są przygotowywane do zwrócenia
COMPLETED Środki z pobrania zostały zatwierdzone do zwrotu
CANCELED Zwrot środków z pobrania został anulowany
FinancialDocument
Pole Typ Opis
type string Typ dokumentu finansowego
link string URL do dokumentu finansowego
name string Nazwa
TransportDocument
Pole Typ Opis
type string Typ dokumentu
link string URL dokumentu
name string Nazwa
downloaded datetime|null Czas pierwszego pobrania pliku przez użytkownika, format Y-m-d H:i:s. Jeśli plik nie został pobrany pole ma wartość null.
Pole Typ Opis
href string URL zasobu
title string Opis akcji
type string Typ żądania HTTP

Przykładowe żądanie

Pole Wartość
number
Nagłówek Wartość
accept-language
x-auth-token
GET: 

Przykładowa odpowiedź

{
    "purpose": null,
    "number": "GK160705888685",
    "creationDate": "2016-07-05 11:37:00",
    "status": "CANCELED",
    "pricing": {
        "priceGross": 231.49,
        "priceNet": 188.2,
        "vatPercent": 23
    },
    "senderAddress": {
        "name": "Imię",
        "surname": "Nazwisko",
        "street": "Testowa",
        "apartmentNumber": "2",
        "houseNumber": "1",
        "city": "Częstochowa",
        "postCode": "42-226",
        "countryId": 1,
        "phone": "48111222333",
        "email": "test@testmail.pl",
        "contactPerson": "Osoba kontaktowa",
        "pointId": null,
        "stateId": null
    },
    "receiverAddress": {
        "name": "Imię",
        "surname": "Nazwisko",
        "street": "Inna",
        "apartmentNumber": "3D",
        "houseNumber": "1",
        "city": "Częstochowa",
        "postCode": "42-226",
        "countryId": 1,
        "phone": "48111222333",
        "email": "test2@testmail.pl",
        "contactPerson": "Inna osoba kontaktowa",
        "pointId": null,
        "stateId": null
    },
    "userAddress": {
        "regon": null,
        "nip": null,
        "name": "Imię klienta",
        "surname": "Nazwisko",
        "street": "Testowa",
        "apartmentNumber": "Test2",
        "houseNumber": "Test1",
        "city": "Katowice",
        "postCode": "42-226",
        "countryId": 1,
        "phone": "48111222333",
        "email": "test3@testmail.pl",
        "companyName": "",
        "type": "PERSON"
    },
    "shipment": {
        "productId": 683,
        "name": "TEST With addons"
        "length": 1,
        "width": 1,
        "height": 1,
        "weight": 1,
        "quantity": 1,
        "carrier": {
            "id": 91,
            "name": "TEST With addons",
            "logo": "/images/kurier/min/91.png"
        }
    },
    "content": "Części samochodowe",
    "instructions": "",
    "paymentId": 6,
    "originId": 24,
    "discountCode": null,
    "declaredValue": null,
    "pickup": {
        "date": "2016-07-05",
        "timeFrom": "08:00:00",
        "timeTo": "18:00:00"
    },
    "addons": [
        {
            "category": "NOT_STANDARD",
            "addonName": "Opłata za element niestandardowy do 30kg",
            "id": 340
        },
        {
            "value": 243.49,
            "bankAccountNumber": "PL15175000120000000032303161",
            "name": "Test",
            "addressLine1": "address line 1",
            "addressLine2": "address line 2",
            "status": {
                "name": "WAITING_FOR_DELIVERY",
                "description": "Parcel is waiting for delivery",
                "returnDate": null
            },
            "category": "CASH_ON_DELIVERY",
            "addonName": "COD do 5000zł",
            "id": 342
        },
        {
            "value": 321,
            "category": "INSURANCE",
            "addonName": "Ubezpieczenie do 5000zł",
            "id": 348
        },
        {
            "addonName": "Indywidualne dane na liście przewozowym",
            "name": "Imię",
            "surname": "Nazwisko",
            "city": "Miasto",
            "street": "Ulica",
            "houseNumber": "2",
            "apartmentNumber": "1",
            "postCode": "41-100",
            "phone": "132123123",
            "email": null,
            "countryId": 1,
            "category": "SENDER_WAYBILL_ADDRESS",
            "id": 350
        }
    ],
    "financialDocuments": [
        {
            "type": "INVOICE",
            "link": "https://api.globkurier.pl/v1/invoice?hash=104745b285bedbb667c59b135d9b9a74770af9b0",
            "name": "Faktura VAT"
        }
    ],
    "transportDocuments": [
        {
            "type": "WAYBILL",
            "link": "https://api.globkurier.pl/v1/order/labels?orderHashes[0]=dz2745b285bedbb667c59b135d9b9a74770af9b0104745b285bedbb667c59b1a",
            "name": "List przewozowy",
            "downloaded": "2016-07-05 13:45:00"
        },
        {
            "type": "PROTOCOL",
            "link": "https://api.globkurier.pl/v1/order/protocol?orderHashes[0]=dz2745b285bedbb667c59b135d9b9a74770af9b0104745b285bedbb667c59b1a",
            "name": "Protokół przekazania towaru",
            "downloaded": null
        }
    ],
    "links": [
        {
            "href": "/order/status/cancel",
            "title": "Cancel an order",
            "type":"PUT"
        }
    ],
    "hash": "dz2745b285bedbb667c59b135d9b9a74770af9b0104745b285bedbb667c59b1a"
}

Pobranie listy zamówień do protokołu

Zwraca listę pogrupowanych zamówień, na podstawie których jest możliwość wygenerowania protokołu. Domyślnie nie trzeba przekazywać żadnych filtrów, aby mieć możliwość ich wygenerowania na podstawie otrzymanej za pierwszym razem listy.

Endpoint

GET: /order/protocol/pickups

Parametry żądania

Pole Opis Wymagane
date Data nadania, dla której chcemy przygotować protokół. Zwracana na liście otrzymanej przy pierwszym wykonaniu Nie
carrier ID przewoźnika. Zwracany na liście otrzymanej przy pierwszym wykonaniu Nie
city Miasto nadania przesyłki. Zwracane na liście otrzymanej przy pierwszym wykonaniu. Nie

Struktura odpowiedzi

W odpowiedzi otrzymujemy listę pogrupowanych zamówień względem przewoźnika, daty nadania oraz adresu nadawcy przesyłki.

Przykładowe żądanie

Pole Wartość
date
carrier
city
Nagłówek Wartość
accept-language
GET: 

Pobranie protokołu

Informację czy dla danego produktu jest możliwe wykorzystanie tego zasobu API zwraca w zasobie /products.

Endpoint

GET: /order/protocol

Parametry żądania

postProductTemplate
Pole Opis Wymagane
orderHashes Tablica z hashami zamówień (hash zwracany w zasobie /order). Zamówienia muszą należeć do użytkownika, do którego należy przekazany token. Tak

Struktura odpowiedzi

W odpowiedzi otrzymujemy binarny plik typu pdf. Odwołanie się do zasobu przez przeglądarkę powinno zainicjować proces pobierania pliku.

Przykładowe żądanie

Pole Wartość
orderHashes[]
Nagłówek Wartość
accept-language
GET: 

Pobranie etykiet

Zasób odpowiada za pobieranie etykiet (pojedyńczej oraz zbiorczych).

Etykiety zbiorcze nie są dostępne dla każdego przewoźnika (informacja o tym, dla których zamówień jest dostępna znajdzie się w zasobie do pobierania listy zamówień, który zostanie dodany do API - do tego czasu w integracji można zaimplementować pobieranie pojedyńczych etykiet).

Endpoint

GET: /order/labels

Parametry żądania

Pole Opis Wymagane
orderHashes Tablica z hashami zamówień (hash zwracany w zasobie /order). Zamówienia muszą należeć do użytkownika, do którego należy przekazany token. Tak
format Format etykiety, możliwe wartości:
  • A4 - format A4 (domyślny)
  • ZEBRA_PRINTER - format dla drukarek Zebra
Nie

Struktura odpowiedzi

W odpowiedzi otrzymujemy binarny plik typu pdf. Odwołanie się do zasobu przez przeglądarkę powinno zainicjować proces pobierania pliku.

Przykładowe żądanie

Pole Wartość
orderHashes[]
format
Nagłówek Wartość
accept-language
GET: 

Pobranie statusów przesyłki

Endpoint

GET: /order/tracking

Parametry żądania

Pole Opis Wymagane
orderNumber Numer zamówienia Tak

Struktura odpowiedzi

Pole Typ Opis
Status[] Lista statusów
Status
Pole Typ Opis
type string Typ
date string Data utworzenia
location string Opcjonalnie podawana jest lokalizacja, jeśli status związany jest z konkretnym miejscem
name string Nazwa

Przykładowe żądanie

Pole Wartość
orderNumber
Nagłówek Wartość
accept-language
GET: 

Przykładowa odpowiedź

[
    {
        "type": "REGISTERED",
        "date": "2015-11-25 13:23:00",
        "location": null,
        "name": 'Zarejestrowana'
    },
    {
        "type": "PICKED_UP",
        "date": "2015-12-01 09:00:00",
        "location": "Katowice",
        "name": "Odebrana przez przewo\u017anika"
    },
    {
        "type": "DELIVERED_TO_MAGAZINE",
        "date": "2015-12-01 12:00:00",
        "location": "Katowice",
        "name": "Dostarczona do magazynu"
    },
    {
        "type": "DELIVERED_TO_RECEIVER",
        "date": "2015-12-02 12:00:00",
        "location": "Warszawa",
        "name": "Dostarczono do odbiorcy"
    }
]

FAQ

Czy istnieje konto testowe z którego można korzystać podczas pisania integracji?

Nie posiadamy globalnego konta testowego, posiadamy natomiast środowisko testowe na którym można utworzyć dowolne konto pod adresem http://test.api.globkurier.pl/v1 (dane na środowisku testowym są resetowane każdej nocy).

Czy mogę raz wyszukane ID produktu używać wielokrotnie w procesie zamówienia?

Tak, lecz nie zalecamy takiego zabiegu, ponieważ oferta produktowa może zostać zmieniona.

W jakich metodach płatności trzeba spełnić dodatowe warunki, aby móc z nich korzystać?

Czy jestem w stanie wygenerować wszystkie dokumenty związane z zamówieniem korzystając z środowiska testowego?

Niestety nie, listy przewozowe (etykiety) i protokoły przesyłane są z API przewoźników, dlatego nie ma możliwości ich uzyskać w środowisku testowym.

Chciałbym przeprowadzić testy na produkcji na pobieranie dokumentów (np. etykiet). Czy jest możliwość bezpiecznej anulacji bez kosztów?

Tak, w przypadku takiej sytuacji proszę od razu po dokonaniu takiego zamówienia i otrzymaniu dokumentów przesłać na kontakt@globkurier.pl numer zamówienia wraz z prośbą o anulowanie.

Po zintegrowaniu ceny usług nie zgadzają się z moimi cenami ustalonymi w kontrakcie z GlobKurier. Co może być przyczyną?

Przyczyn takiej sytuacji może być kilka, prosimy o sprawdzenie:

  • czy w żądaniu wyceny/składania zamówienia przekazywany jest TOKEN (czy użytkownik jest zalogowany)?
  • czy w żądaniu wyceny/składania zamówienia nie ma przekazywanych żadnych płatnych dodatków? (np. ubezpieczenie, COD itd.)
Jeśli odpowiedzi na powyższe pytania odpowiedzi brzmią „TAK” i problem nadal występuje prosimy o kontakt z nami.