KurJerzy API


API
API

Ostatnia aktualizacja: 01.04.2020;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.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)
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/

W celu zapoznania się z dokumentacją API prosimy ściągnąć klienta/wtyczkę do przeglądarki:
https://altair.sirmuel.design/

Aby pobrać dokumentację należy wprowadzić adres API w aplikacji Altair:
https://www.kurjerzy.pl/graphql
następnie wybrać DOC/Dokumentacja po prawej stronie.

Wprowadzanie adresu oraz dostęp do dokumentacji technicznej
Wprowadzanie adresu oraz dostęp do dokumentacji technicznej

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.

api_headers
Ustawienie nagłówka HTTP

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.

W celu złożenia zamówienia z obsługą w punkcie, należy podać kod oraz rodzaj przewoźnika (pola wymagane). Dodatkowo można przekazać dokładny adres punktu nadania/odbioru.
Informacje o punktach uzyskasz wyszukując je po adresie (patrz punkt 2.8).

mutation {
  createShipment(
statusUrl: "https://adres_do_odbioru_powiadomien", 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
name
carrierCode <- pole wymagane
street
zip
city
}
}, 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
name
carrierCode
street
zip
city
} }, 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.

mutation {
  createLabel(
    shipmentIds: [9542]
  ){
    statuses {
      shipmentId,
      status,
      error {
        code
        group
        description
      }
    }
  }
}

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, numer przesyłki, adres do etykiety, trackingu itp.

labelSource – niezmodyfikowane źródło etykiety. Zależnie od przewoźnika posiadają różny format:
UPS: *.gif,
DHL: *.pdf,
INPOST: *.pdf,
GLS: *.pdf,

query {
  shipments (
    ids:[67229]
  ){
    id,
    createdAt,
    status,
    labelRef,
labelSource,
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
}
  }
}
}

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_2020.02.14.xlsx