Ostatnia aktualizacja: 14.03.2023; 13:00
Żeby otrzymywać powiadomienia o aktualizacji serwisu oraz dokumentacji prosimy o przesłanie wiadomości za pośrednictwem formularza kontaktowego.
1. Wprowadzenie
2. Uproszczony proces składania zamówienia:
2.1. Zalogowanie oraz pobranie TOKEN w celu Autoryzacji kolejnych zapytań
2.2. Pobranie dostępnych produktów
2.3. Dodanie nowego zamówienia do koszyka oraz uzyskanie w odpowiedzi jego ID
2.4. Przekazanie zamówienia do procesowania
2.4.1. Zamówienia z odprawą celną dla Anglii, Szkocji, Walii
2.5. Pobranie godzin odbioru
2.6. Złożenie nowego zlecenia odbioru
2.7. Pobranie danych o zamówieniu, numer przesyłki, adres do etykiety, trackingu itp.
2.8. Pobranie punktów nadania/odbioru przesyłek
2.9. Powiadomienia WebHook
2.10. Komunikacja z nadawcą i odbiorcą
2.11. Generowanie protokołu odbioru
2.12. Pobieranie dostępnych usług
2.13. Dodawanie sub-klienta (podpięcie)
2.14. Kwotowanie
2.15. Pobieranie danych o kliencie
3. Przykładowy klient API w PHP
4. Lista krajów obsługiwanych przez produkty eksport/import
1. Wprowadzenie
KurJerzy API jest realizowane w technologii GraphQL.
https://graphql.org/learn/queries/
Dokumentacja API:
https://www.kurjerzy.pl/graphql/doc
Klient IDE API wraz z dokumentacją:
https://www.kurjerzy.pl/graphql/ide
Wtyczka instalowana do przeglądarki wraz z dokumentacją:
https://altair.sirmuel.design/
Dokumentacja API w aplikacji Altair:
https://www.kurjerzy.pl/graphql
następnie wybrać DOC/Dokumentacja po prawej stronie.
2.1. Zalogowanie oraz pobranie TOKEN w celu Autoryzacji kolejnych zapytań.
W polu email oraz password przekazujemy dane logowania do serwisu www.kurjerzy.pl.
mutation {
createToken(
email:"test@kurjerzy.pl",
password:"test"
) {
token,
expire,
expireHuman
}
}
Po uzyskaniu odpowiedzi należy ustawić nagłówek HTTP:
Header key: Authorization
Header value: Bearer wartość_tokena” aby operować na zasobach wymagających autoryzacji.
2.2. Pobranie dostępnych produktów
Podczas pobierania można odfiltrować rodzaje produktów koperta/paczka/paleta:
(TYPE_LETTER, TYPE_PARCEL, TYPE_PALLET)
query{
products (packageType: TYPE_LETTER) {
id
name
type
params {
widthMax
lengthMax
heightMax
weightSales
}
}
}
2.3. Dodanie nowego zamówienia do koszyka oraz uzyskanie w odpowiedzi jego ID
Uwaga: Wartość “name2” dla Nadawcy oraz Odbiorcy dostępna jest wyłącznie dla produktów kuriera UPS i DPD.
W celu złożenia zamówienia z obsługą w punkcie, należy podać kod punktu (pole wymagane). Dodatkowo można przekazać dokładny adres punktu nadania/odbioru oraz kod przewoźnika.
Informacje o punktach uzyskasz wyszukując je po adresie (patrz punkt 2.8).
Pole checkSaldo sprawdza czy na saldzie znajduje się wystarczająca ilość środków na pokrycie aktualnego zamówienia (uwzględnia również znajdujące się w koszyku zamówienia).
mutation {
createShipment(
checkSaldo: 1, # pole niewymagane (domyślnie 0)
statusUrl: "https://adres_do_odbioru_powiadomien",
refer: “REF123”
productId: 3,
sender: {
name: "Jan Konwalski",
name2: "Firma NoName",
email: "jan.kowalski@kurjerzy.pl",
street: "Kwiatowa",
number: "1/108",
zip: "80374",
city: "Gdansk",
phone: "777777777",
country: "PL",
state: "",
point {
code <- pole wymagane
}
},
recipient: {
name: "Janusz Moczywas",
name2: "Firma NoName",
email: "janusz.moczywas@kurjerzy.pl",
street: "Wojska Polskiego",
number: "43",
zip: "80345",
city: "Gdansk",
phone: "123456789",
country: "PL",
state: "",
point {
code <- pole wymagane
}
},
params: {
packageType: TYPE_PARCEL,
weight: 0.5,
length: 115,
width: 100,
height: 10,
declareValue: 1000,
content: "test",
packingType: TYPE_STANDARD,
count: 1
},
services: {
cod: 1,
codValue: 777.77,
codAccountNumber: "95249000050000453063614755",
codOneDay: 0,
smsSenderNotification: 1,
smsRecipientNotification: 1,
warrantyDeliveryNextDay: 0,
rod: 0
}){
status,
shipment {
id,
number,
numberParcel
},
error {
code
group
description
}
}
}
2.4. Przekazanie zamówienia do procesowania
Uwaga: Proces wykonuje się asynchronicznie, w odpowiedzi otrzymuje się tylko potwierdzenie/status że zadanie zostało dodane do kolejki procesowania.
Sygnaturę można przekazać dla zamówień poza EU. Przekazany podpis zostanie przypisany do unikalnych danych nadawcy zamówień wskazanych identyfikatorami shipmentIds.
mutation {
createLabel(
shipmentIds: [9542],
signature: "data:image/png;base64,iVBORw0KG...” <-podpis base64
){
statuses {
shipmentId,
status,
error {
code
group
description
}
}
}
}
2.4.1. Zamówienia z odprawą celną do Angli, Szkocji, Walii
Zleceniodawca: osoba prywatna
Cel wysyłki: prezent lub przedmioty o łącznej wartości poniżej 39 GBP
Pola wymagane:
clearance: {
sender: "individual"
value: "gift"
purpose: "opis"
checkIe: false
items: [
{
name: "ITEM 1"
quantity: "1"
price: "100"
currency: "PLN"
country: "PL"
tariffCode: "9608 10 00 00"
}
]
}
Zleceniodawca: osoba prywatna
Cel wysyłki: sprzedaż lub towary o wartości przekraczającej 135 GBP
Pola wymagane:
clearance: {
sender: "individual"
value: "above_1000"
transport: "1000"
purpose: "opis"
checkIe: false
items: [
{
name: "ITEM 1"
quantity: "1"
price: "100"
currency: "PLN"
country: "PL"
tariffCode: "9608 10 00 00"
}
]
}
Zleceniodawca: firma
Cel wysyłki: bezpłatne próbki lub przedmioty o łącznej wartości poniżej 39 GBP
Pola wymagane:
clearance: {
sender: "company"
value: "gift"
purpose: "opis"
checkIe: false
items: [
{
name: "ITEM 1"
quantity: "1"
price: "100"
currency: "PLN"
country: "PL"
tariffCode: "9608 10 00 00"
}
]
}
Zleceniodawca: firma
Cel wysyłki: sprzedaż lub towary o wartości nie przekraczającej 135 GBP
Pola wymagane:
clearance: {
sender: "company"
value: "under_1000"
transport: "1000"
eori: "1234567890"
vat: "1234567890"
purpose: "opis"
checkIe: false
items: [
{
name: "ITEM 1"
quantity: "1"
price: "100"
currency: "PLN"
country: "PL"
tariffCode: "9608 10 00 00"
}
]
}
Zleceniodawca: firma
Cel wysyłki: sprzedaż lub towary o wartości przekraczającej 135 GBP
Pola wymagane:
clearance: {
sender: "company"
value: "above_1000"
transport: "1000"
eori: "1234567890"
eoriRecipient: "1234567890"
regon: "1234567890"
purpose: "opis"
checkIe: false
items: [
{
name: "ITEM 1"
quantity: "1"
price: "100"
currency: "PLN"
country: "PL"
tariffCode: "9608 10 00 00"
}
]
}
Przykład:
mutation {
createShipment(
productId: 6,
sender: {
name: "TEST API EXPORT",
email: "test@test.pl",
street: "Dąbrowszczaków",
number: "1/108",
zip: "80-374",
city: "Gdańsk",
phone: "XXXXXXXXX",
country: "PL",
state: ""
},
recipient: {
name: "TEST API ODBIORCA GB",
email: "test@test.pl",
street: "Poplarwood gardens ",
number: "12",
zip: "BD100HQ",
city: "Bradford",
phone: "+48XXXXXXXXX",
country: "GB"
},
params: {
packageType: TYPE_PARCEL,
weight: 10,
length: 5,
width: 10,
height: 10,
declareValue: 1000,
content: "test",
packingType: TYPE_STANDARD,
count: 1
},
services: {
cod: 0,
codOneDay: 0,
smsSenderNotification: 0,
smsRecipientNotification: 0,
warrantyDeliveryNextDay: 0,
rod: 0
},
refer: "TEST!",
clearance: {
sender: "company"
value: "under_1000"
purpose: "TESTY"
checkIe: false
transport: "1000"
eori: "1234567890"
vat: "1234567890"
items: [
{
name: "ITEM 1"
quantity: "1"
price: "100"
currency: "PLN"
country: "PL"
tariffCode: "123456789Q"
},
{
name: "ITEM 2"
quantity: "1"
price: "100"
currency: "PLN"
country: "PL"
tariffCode: "777777777Q"
}
]
}
)
{
error {
code
group
description
},
status,
shipment {
…
}
}
}
2.5. Pobranie godzin odbioru
Aby pobrać dostępne godziny odbioru należy wykonać zapytanie podając adres nadania. Waga to ciężar najcięższej paczki. Aby uzyskać najdokładniejsze daty należy podać wszystkie dane dla zlecenia odbioru.
query { collectionDates ( params: { productId: 3 countryFrom: "PL" countryTo: "PL" zip: "18400" city: "Olecko" street: "Dąbrowszczaków" number: "1" count: 1 weight: 1 } ){ date } }
2.6. Złożenie nowego zlecenia odbioru
W parametrach można podać adres oraz datę i godziny odbioru, w przypadku ich braku system jako adres odbioru pobierze adres nadawcy z pierwszego zamówienia na liście shipmentIds, a date i godziny ustali automatycznie (najbliższy możliwy termin).
Uwaga: Proces wykonuje się asynchronicznie, w odpowiedzi otrzymuje się tylko potwierdzenie/status że zadanie zostało dodane do kolejki procesowania.
mutation {
createCollection(
shipmentIds: [67229]
address: {
name: "Antoni Kowalski",
email: "test@kurjerzy.pl",
street: "Dąbrowszczaków",
number: "1/108",
city: "Gdańsk",
zip: "80257"
country: "PL",
phone: "000000000"
},
date: "2019-05-23",
hourFrom: "09:00",
hourTo: "15:00"
){
status,
collection {
id,
status,
numberCollection,
date,
hourFrom,
hourTo
},
error {
code
group
descritpion
}
}
}
2.7. Pobranie danych o zamówieniu, numeru przesyłki, adresu do pobrania etykiety, trackingu itp.
labelZpl – etykieta w formacie ZPL,
labelRef – etykieta w fomracie PDF,
labelSource – niezmodyfikowane źródło etykiety. Zależnie od przewoźnika posiadają różny format:
AMBRO: *.pdf,
DHL: *.pdf,
DPD: *.pdf,
FEDEX: *.pdf,
GLS: *.pdf,
INPOST: *.pdf,
ORLEN: *.pdf,
UPS: *.gif,
query {
shipments (
ids:[67229]
){
id,
createdAt,
status,
labelRef,
labelSource,
labelZpl,
senderAddress {
point{
code
carrierCode
name <- jeśli podano przy tworzeniu zamówienia
street <- jeśli podano przy tworzeniu zamówienia
zip <- jeśli podano przy tworzeniu zamówienia
city <- jeśli podano przy tworzeniu zamówienia
}
},
collections {
id,
status,
numberCollection,
date,
hourFrom,
hourTo
}
tracking {
booked
collected
inDelivery
delivered
deliveredPoint
returned
statuses
}
}
}
2.8. Pobranie punktów nadania/odbioru przesyłek
Żeby pobrać dostępne punkty kuriera należy wpisać adres lokalizacji, w której chce się szukać, promień poszukiwań oraz kod przewoźnika.
Aktualnie dostępne dla: Inpost, DHL, UPS.
query {
points (
address: {
city: "Gdańsk",
street: "Dąbrowszczaków",
number: "1"
},
radius: 10,
carrier: "inpost"
) {
code,
lat,
lng,
name,
desc,
street,
zip,
city ,
openingHours,
payment
}
}
2.9. Powiadomienia WebHook
Jeśli przy składaniu zamówienia zostanie podany adres statusUrl to zostaną wysłane na niego powiadomienia o zakończeniu asynchronicznego procesowania zamówienia lub zlecenia odbioru.
Jeśli pierwsza próba zakończy się niepowodzeniem, system ponowi wysyłkę komunikatu 6 razy w odstępie czasowym 10 minut.
Pod wskazanym adresem należy udostępnić endpoint, który na request wysłany przez nasz system odpowie kodem HTTP 200.
Należy się spodziewać poniższych powiadomień metodą POST:
1. Dla zamówienia – zakończenie procesowania:
‘status' = 'shipment_processed'
'shipment_id' = 12345
'description' = 'Zamówienie zostało złożone.'
2. Dla zamówienia dla którego został zlecony odbiór – po zakończeniu jego procesowania, każdy shipment zostanie poinformowany o zakończeniu procesowania dla niego odbioru:
‘status' = 'collection_for_shipment_processed'
'shipment_id' = 12345
'description' = 'Zlecenie odbioru dla zamówienia zostało złożone.'
3. Dla zamówienia odebranego przez kuriera:
'status' = 'shipment_collected'
'shipment_id' = 12345
'description' = 'Zamówienie zostało odebrane od nadawcy.'
4. Dla zamówienia – brak środków na koncie / zerowe, ujemne saldo:
'status' = 'insufficient_funds'
'shipment_id' = 12345
'description' = 'Brak środków na koncie.'
Uwaga: W celu zachowania bezpieczeństwa należy filtrować adres IP otrzymanego requestu z informacją WebHook.
Nasz adres IP: 46.248.174.6
2.10. Komunikacja z nadawcą i odbiorcą
Istnieje możliwość wyłączenia wszystkich powiadomień email/sms wysyłanych przez nasz serwis do nadawcy oraz odbiorcy. W tym celu prosimy o kontakt za pośrednictwem formularza kontaktowego.
2.11. Generowanie protokołu odbioru
W celu wygenerowania zbiorczego protokołu odbioru należy przekazać listę identyfikatorów przetworzonych odbiorów lub listę identyfikatorów zamówień, dla których ma być zwrócony.
Uwaga: zwrócone zostaną tylko odbiory ze statusem “sprocesowany”(STATUS_PROCESSED).
Zwrócony zostanie url do pliku zdalnego w formacie PDF.
query {
collections (shipmentIds: [68709,68711,68712,68713]) {
reportUrl,
collections {
numberCollection,
status,
hourFrom
hourTo
date
address {
street,
number
city,
zip,
}
}
}
}
2.12. Pobieranie dostępnych usług
W celu pobrania dostępnych usług należy przekazać: rodzaj przesyłki, relacje między krajami, oraz czy wykorzystuje się punkt nadawczy i/lub odbiorczy.
query {
servicesAvailable (params: {
packageType: TYPE_PARCEL,
countryFrom: "PL",
countryTo: "PL",
pointFrom: false,
pointTo: false
}) {
code,
name
}
}
2.13. Dodawanie sub-klienta (podpięcie)
W celu podpięcia swojej grupy rabatowej pod wskazanego klienta należy przekazać jego uprzednio wygenerowany token.
Uwaga. Aby aktywować usługę prosimy o kontakt za pośrednictwem formularza kontaktowego.
mutation {
addSubClient(
customerToken: "token klienta"
)
{
statuses {
customerId
status
error {
code
group
description
}
}
}
}
2.14. Kwotowanie
W celu uzyskania wyceny przyszłego zamówienia, należy przesłać zestaw informacji o destynacji, kodach pocztowych oraz dodatkowych usługach.
query{
rate(
sender: {
zip: "80-257",
country: "PL"
},
recipient: {
zip: "80-374",
country: "PL",
},
params: {
packageType: TYPE_PARCEL,
weight: 21,
width: 10,
length: 10,
height: 10,
declareValue: 100,
packingType: TYPE_STANDARD
},
services: {
cod: 1,
codValue: 100,
smsSenderNotification: 1,
smsRecipientNotification: 1
},
){
carrierCode
productId <- wybrany ID należy przekazać w mutacji createShipment
totalNetto
total
}
}
2.15. Pobieranie danych o kliencie
W celu pobrania informacji o kliencie (w tym o wartości sald 23% i 0%) należy wykonać zapytanie:
query{
me{
email,
name,
street,
number,
zip,
city,
phone,
balance,
balanceFreeTax
}
}
3. Przykładowy klient API w PHP
Do dokumentacji został dołączony przykładowy klient API w języku PHP zrealizowany w frameworku CodeIgniter. Pokazane są w nim przykładowe zapytania do API.
Klasa klienta api znajduje się w application -> libraries -> KurJerzyApi.php
Przykładowego klienta możesz pobrać tutaj.
4. Lista krajów obsługiwanych przez produkty eksport/import
W pliku znajduje się zestawienie krajów, które dostępne są w ramach danego produktu (per productID): produkt-kraj_2022_09_06.xlsx