       Dokumentacja
Polkurier WebService API

                                             wersja dokumentu: 1.11
Spis treci

   Historia zmian.................................................................................................................................................................3
   Informacje ogólne...........................................................................................................................................................4
   Wymagania...................................................................................................................................................................... 4
   Struktura danych.............................................................................................................................................................5
   Metody API......................................................................................................................................................................6

       Metoda: heartbeat ­ Sprawdzanie dostpnoci API...............................................................................................6
       Metoda: test_auth_api ­ Sprawdzanie poprawnoci autoryzacji...........................................................................7
       Metoda: available_carriers - lista dostpnych przewoników................................................................................8
       Metoda: order_valuation ­ wycena przesylki........................................................................................................10
       Metoda: order_valuation_v2 ­ wycena przesylki...................................................................................................12
       Metoda: create_order ­ nowa przesylka................................................................................................................14
       Metoda: get_label - pobieranie pliku etykiety.........................................................................................................19
       Metoda: get_protocol ­ pobieranie protokolu zdawczo-odbiorczego.................................................................20
       Metoda: get_status ­ status przesylki...................................................................................................................21
       Metoda: cancel_order ­ anulowanie przesylki......................................................................................................22
       Metoda: pickup_courier ­ godziny podjazdu kuriera dla danego dnia................................................................23
       Metoda: get_courier_pickup_time ­ Zwraca dni i godziny podjazdu kuriera......................................................24
       Metoda: get_countries ­ lista krajów obslugiwanych przez danego kuriera......................................................25
       Metoda: get_supported_countries_v2 - Zwraca list wszystkich obslugiwanych krajów..................................26
       Metoda: get_courier_point ­ lista punktów kurierskich / paczkomatów............................................................27
       Metoda: get_orders ­ szczególy zamówienia ­ lista zamówie.........................................................................29
       Metoda: is_multi_pickup_available ­ Dostpno zbiorczego podjazdu kuriera...............................................34
       Metoda: create_multi_order_pickup ­ Zamówienie zbiorczego podjazdu kuriera.............................................35
       Metoda: get_addresses ­ Lista adresów z ksiki adresowej.............................................................................36
       Metoda: save_address ­ Zapis adresów do ksiki adresowej...........................................................................38
       Metoda: delete_address ­ Usuwanie adresów z ksiki adresowej...................................................................39
       Metoda: get_bank_accounts ­ Lista kont bankowych do zwrotu pobrania........................................................40
       Metoda: delete_bank_account ­ Usuwanie konta bankowego............................................................................41
       Metoda: save_bank_account ­ Zapisuje konto bankowe do zwrotu pobrania...................................................42
       Metoda: get_pack_templates ­ Lista szablonów paczek.....................................................................................43
       Metoda: save_pack_template ­ Zapisuje szablon paczek...................................................................................45
       Metoda: delete_pack_template ­ Usuwanie szablonu paczek............................................................................46
       Metoda: find_city ­ Wyszukiwanie miejscowoci po kodzie pocztowym...........................................................47
       Metoda: get_map_token ­ Wygenerowanie tokenu mapy punktów....................................................................48
       Wywietlenie mapy punktów kurierskich i paczkomatów....................................................................................49
   Definicje.........................................................................................................................................................................52

              Rodzaj przesylek SHIPMENT_TYPE...............................................................................................................52

              Typy przesylek PACK_TYPE...........................................................................................................................52

              Typ zwrotu pobrania codtype, COD_TYPE.....................................................................................................52

                                                                           1
Sposób zwrotu pobrania return_cod..............................................................................................................52
Status zlecenia ORDER_STATUS...................................................................................................................52
Status pobrania COD_STATUS.......................................................................................................................52
Status operacji na pobraniu COD_OPERATION_REASON............................................................................53
Uslugi dodatkowe ADDITIONAL_SERVICE....................................................................................................53

                                                             2
Historia zmian

       Data     Wersja                                                            Informacje o zmianach
19.06.2018        1.0   Utworzenie dokumentu
17.07.2020        1.1   Dodanie metody kurier48_post_offices oraz inpost_points_machines
15.06.2021        1.2   Metoda available_carriers - dodano do response atrybut: foreign_shipments
29.07.2022        1.3   Metoda create_order ­ dodano dodatkowe uslugi: COURIER_WITH_LABEL, WEEK_COLLECTION
                        Metoda order_valuation ­ do request dodano atrybut courierservice
03.01.2023        1.4   Dodano now metod: get_orders
                        Metoda kurier48_post_offices zostala zdeprecjonowana i zastpiona metod pocztex_post_offices. Dodano
12.09.2024        1.5   dodatkowe filtry.
26.09.2024        1.6   Medota create_order. Zdeprecjonowana nazwa atrybutu ,,machinename"dla kolekcji ,,sender" oraz ,,recipient".
22.05.2025        1.7   Nowa nazwa atrybutu dla punktu nadania oraz punktu odbioru: point_id
28.11.2025        1.8   Metoda get_orders . Zdeprecjonowana nazwa atrybutu ,,machinename"dla kolekcji ,,sender" oraz ,,recipient".
07.01.2026        1.9   Nowa nazwa atrybutu dla punktu nadania oraz punktu odbioru: point_id
06.01.2026       1.10   Metoda create_order ­ dodano dodatkowe uslugi:
12.03.2026       1.11   SMS_NOTIFICATION_RECIPIENT, SMS_NOTIFICATION_RECIPIENT_WITH_NAME, LABELLESS
                        HANDLE_WITH_CARE, DOSTAWA_DO_RAK_WLASNYCH, CHECK_CONTENT,
                        PHONE_NOTIFICATION_RECIPIENT
                        Metoda get_orders ­ dodano atrybuty odpowiedzi: price_net, is_paid, has_invoice, unpaid_amount, items,
                        individual_pricing, waybills, COD.return_details
                        Metoda get_orders ­ dodano atrybuty zapytania: items
                        Metoda get_orders ­ zdeprecjonowane atrybuty odpowiedzi: label (zastpione przez waybills), courierservice
                        (zastpione przez items)
                        Metody inpost_parcel_machines, pocztex_post_offices, inpost_points_machines zostaly zdeprecjonowane i
                        zastpiona metod get_courier_point
                        Do response metody order_valuation dodano nowe atrybuty: promotion_nett, promotion_gross, rebate_nett,
                        rebate_gross, available, unavailable_message
                        Dodano metod heartbeat
                        Dodano metod test_auth_api
                        Dodano metod get_supported_countries_v2
                        Dodano metod get_courier_pickup_time
                        Dodano metod get_courier_point
                        Dodano metod is_multi_pickup_available
                        Dodano metod create_multi_order_pickup
                        Dodano metod get_addresses
                        Dodano metod save_address
                        Dodano metod delete_address
                        Dodano metod get_bank_accounts
                        Dodano metod save_bank_account
                        Dodano metod delete_bank_account
                        Dodano metod get_pack_templates
                        Dodano metod save_pack_template
                        Dodano metod delete_pack_template
                        Dodano metod get_map_token
                        Dodano pole is_cover_address do danych adresu nadawcy zwracanych get_addresses, save_address

                        Dodano parametry: id, limit oraz page do zapytania metody get_courier_point

                        Dodano atrybut countryiso do encji COURIER_POINT zwracanej przez metod get_courier_point

                        Dodano atrybut courier oraz services do metody get_pack_templates

                        Dodano parametr courier oraz services do metody save_pack_template

                        Dodano metody statyczne mapy punktów: getCourierMapProvider oraz getAvailableProviders
                        Dodano metod order_valuation_v2
                        Metoda order_valuation zostala zdeprecjonowana i zastpiona metod order_valuation_v2

                        Dodano atrybut additional_fields do atrybutu additional_data zwracanego przez metod
                        available_carriers

                        Dodano atrybut additional_fields do metody create_order

                        Dodano parametry courier, cod_min, cod_max, date_from, date_to, search do metody get_orders

                        3
Informacje ogólne

Polkurier WebService API to usluga internetowa przeznaczona dla klientów serwisu polkurier.pl, która umoliwia
pelne zautomatyzowanie procesu skladanie zlece na przewóz przesylek kurierskich za porednictwem
przewoników dostpnych w ofercie serwisu internetowego polkurier.pl
Korzystanie z uslugi umoliwia peln integracj z systemami produkcyjnymi, magazynowymi oraz sklepami
internetowymi. Zapytania do Polkurier WebService API zbudowane s w formacie JSON i umoliwiaj dalsze
przetwarzanie po stronie klienta w ramach systemu wdroonego przez klienta.

Wymagania

Do korzystania z Polkurier WebService API klient musi posiada aktywne konto w serwisie polkurier.pl, podpisana
umow z wlacicielem serwisu oraz klucz dostpu tzw.: token. W celu uzyskania klucza naley wygenerowa go
samodzielnie w panelu klienta w zakladce ustawienia - Token API.
Usluga internetowa ,,Polkurier WebService API" dostpna jest pod adresem: https://api.polkurier.pl
rodowisko testowe:
https://api-sandbox.polkurier.pl
W celu uzyskania dostpu do rodowiska testowego prosimy o kontakt na e-mail: api@polkurier.pl
Wszystkie pytania oraz uwagi prosz kierowa na adres e-mail api@polkurier.pl

                                                                           4
Struktura danych

Podstawowa struktura kolekcji request w formacie JSON

{
    "authorization":{
        "login": "ID KONTA",
        "token": "XXXXXXXXXXXXXX"
    },
    "apimethod": "...",
    "data":{...}

}

Podstawowa struktura kolekcji response serwera w formacie JSON

{
    "status": "success / error",
    "response": "dane w zalenoci od uytej metody lub komunikat bldu"

}

Atrybut ,,authorization" w zapytaniu jest zawsze wymagany do wszystkich metod dostpnych w
serwisie.

Elementy zasobu authorization posiadaj nastpujce atrybuty:

Atrybut              Typ     Opis

login                String  id konta w serwisie polkurier.pl

token                String  klucz dostpu

Atrybut ,,apimethod" informuje Polkurier WebService API któr metod chcemy uy. Lista dostpnych
metod oraz struktura zapytania zostala opisana w dalszej czci dokumentu.

Atrybut `data' sluy do zdefiniowania niezbdnych danych na potrzeby uytej metody.

W przypadku odpowiedzi pozytywnej kiedy nie wystpily adne bldy atrybut `status' zwróci warto
,,success", w przypadku wystpienia bldu atrybut "status" przyjmie warto "error", opis bldu
zostanie zwrócony w "response".

W dalszej czci dokumentacji poslugujemy si nastpujcym typami danych:

Nazwa        Typ JSON Opis

Date         String       Data (sam komponent daty tj. dzie miesic i rok) w formacie ISO 8601 (np. 2023-01-03)

DateTime     String       Pelna data i godzina w formacie ISO 8601 (np. 2023-01-03T09:06:31+02:00)

Time         String       Godziny w formacie HH:MM lub HH:MM:SS (np. 09:00)

Array<T>     Array        Tablica elementów typu T np. Array<String> == tablica stringów

Enum<T>      String       Jedna z wartoci zdefiniowanych przez T np. Enum<COD_STATUS> MUSI zawiera jedn z
                          wartoci z tabeli COD_STATUS

Enum [...]   String       Jedna z wartoci zdefiniowanych w nawiasach klamrowych [...] np. Enum[A, B, C] MUSI
                          zawiera jedn z tych wartoci np. B

Map<K, V>    Object       Mapa, hash, tablica asocjacyjna, gdzie indeks jest typu K, a warto typu V. np. Map<String,

                          Bool> koresponduje np. z {"foo": true, "bar": false} w danych JSON

OBJECT_TYPE  Object       Obiekt strukturze opisanej tabeli o takiej samej nazwie

Object<T>    Object       Obiekt strukturze opisanej tabeli o nazwie T

NULL         NULL         Pusta warto np. null

                                                5
Metody API

Metoda: heartbeat ­ Sprawdzanie dostpnoci API
Metoda pozwala na sprawdzenie czy API jest on-line.

Metoda nie wymaga autoryzacji ­ atrybut authorization moe zosta pominity.

Elementy zapytania posiadaj atrybuty:
Metoda nie przyjmuje parametrów.

Elementy zwrócone posiadaj nastpujce atrybuty:

Atrybut     Typ                              Opis

time        DateTime                         Aktualny czas serwera

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "heartbeat",
    "data": {}

}

Przykladowa odpowied:

{
    "status":"success",
    "response": {
        "time": "2024-01-03T14:21:42+01:00"
    }

}

                                                   6
Metoda: test_auth_api ­ Sprawdzanie poprawnoci autoryzacji
Metoda pozwala na sprawdzenie poprawnoci danych autoryzacyjnych.
Elementy zapytania posiadaj atrybuty:
Metoda nie przyjmuje parametrów.

Elementy zwrócone posiadaj nastpujce atrybuty:

Atrybut        Typ                 Opis
authorization  Bool                Zwraca true jeli dane dostpowe s prawidlowe

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "test_auth_api",
    "data": {}

}

Przykladowa odpowied:

{
    "status":"success",
    "response": {
        "authorization": true
    }

}

                                                7
Metoda: available_carriers - lista dostpnych przewoników

Metoda pozwala na pobrania listy dostpnych przewoników w serwisie polkurier.pl za
porednictwem WebService API wraz z dostpnymi uslugami.

Elementy zasobu ,,data" metody available_carriers posiadaj nastpujce atrybuty:

Atrubut            Typ        Wymagane Opis

additional_data    Bool       Nie             Warto ,,true" spowoduje zwrócenie dodatkowych informacji

                                              o dostpnych uslugach.

returncarrier      String     Nie             Znajc list kodów dostpnych przewoników moemy uy

                                              atrybutu z ,,servicecode"(kod przewonika). Po podaniu

                                              kodu WebService API zwróci tylko dane wybranego

                                              przewonika któremu kod jest przypisany

Warto ,,additional_data" zwraca dodatkow kolekcj atrybutów dostpnych dla danego
przewonika. Tablica zawiera nazw atrybutu oraz tablic z dwiema wartociami

      available (bool)
      description (string)

Atrybut ,,available" okrela dostpno uslugi dla przewonika. Wyjtkiem jest atrybut ,,pickup"
(data i godziny podjazdu kuriera) który zwraca kolekcj atrybutów gdzie zamiast atrybutu
,,available" dla daty i godzin podjazdu wystpuje atrybut ,,required" (bool).

Atrybut ,,description" zwraca krótki opis atrybutu

Elementy additional_data zwrócone przez metod available_carriers posiadaj nastpujce

kolekcje:

Kolekcja                Opis

COD                     Pobranie

insurance               Kwota ubezpieczenia przesylki

shipmenttype            Typy przesylek jakie moemy nada wybranym przewonikiem. Rodzaje przesylek w

                        tabeli Rodzaj przesylek. W przypadku wybrania typu przesylki nie obslugiwanego przez

                        przewonika lub podanie bldnej nazwy zostanie zwrócony bld.

courierservice          Lista uslug w tabeli Uslugi dodatkowe

pickup                  Atrybut zawierajcy tablic w wartociami wymaganymi oraz informacj czy opcja

                        "nocourierorder" ­ informujca czy moemy samodzielnie poinformowa kuriera o

                        potrzebie odebrania przesylek jest dostpna
                               pickupdate ­ data podjazdu kuriera
                               pckuptimefrom - godzina "od" oczekiwania na podjazd kuriera
                               pickuptimeto - godzina "do" oczekiwania na podjazd kuriera

additional_fields       Kolekcja dodatkowych parametrów zamówienia specyficznych dla przewonika:

                            string name -- nazwa pola do ustawienia w polu additional_fields w

                                  metodzie create_order

                            string label -- Nazwa pola do wywietlenia w formularzu

                            string description -- Opcjonlany dodatkowy opis do wywietlenia w

                                  formularzu

                            Enum[SELECT, TEXT] type -- typ pola do wywietlenia w formularzu

                                   TEXT -- pole do wpisania tekstu (np. HTML <input type="text">)

                                   SELECT -- pole do wyboru wartoci z listy (np. HTML <select>)

                            Array<object> options -- lista wartoci dla pola typu SELECT, kolekcja

                                  obiektów:

                                   string value -- warto opcji

                                   string label -- etykieta do wywietlenia

                            bool required -- czy pole wymagane

                                              8
Struktura kolekcji request metody available_carriers w formacie JSON

{
    "authorization":{},
    "apimethod": "available_carriers",
    "data":{
        "additional_data": true,
        ,,returncarrier": ,,UPS"
    }

}

Struktura kolekcji response metody available_carriers w formacie JSON

{
    "status": "sukces",
    "response": [{
        "servicecode": "UPS",
        "name": "UPS -Standard",
        "foreign_shipments": false
        "additional_data": {
            "COD":{
                 "available": true,
                 "description": "Pobranie"
            },
            "insurance":{
                 "available": true,
                 "description": "Ubezpieczenie"
            },
            "courierservice":{
                 "ROD":{
                     "available": true,
                     "description": "Zwrot dokumentów"
                 }
            },
            "shipmenttype": {
                 "envelope": {
                 "available": true,
                 "description": "Koperta"
            },
            "box": {
                 "available": true,
                 "description": "Paczka"
            },
            "palette": {
                 "available": false,
                 "description": "Paleta"
            }
        },
        "pickup": {
            "pickupdate": {
            "status": true,
            "description": "data podjazdu kuriera"
        },
        "pickuptimefrom": {
            "status": true,
            "description": "godzina "od" oczekiwania na podjazd kuriera"
        },
        "pickuptimeto": {
            "status": true,
            "description": "godzina "do" oczekiwania na podjazd kuriera"
        },
        "nocourierorder": {
            "available": true,
            "description": "moliwo zamówienia kuriera samodzielnie przez telefon"
        },
         "additional_fields": [
              {

                                                                           9
                "name": "external_transport_security",
                "label": "Sposób zabezpieczenia towaru",
                "description": "",
                "type": "SELECT",
                "options": [

                    {
                        "value": "LACK_OF_SECURING_FEATURES",
                        "label": "Brak zabezpiecze"

                    },
                    {

                        "value": "TAPE",
                        "label": "Tama zwykla"
                    },
                    ...
               ]

            }
    }]
}

               10
Metoda: order_valuation ­ wycena przesylki

Zdeprecjonowane ­ prosimy uywa metody order_valuation_v2

Wycena wysylki w oparciu o podane podstawowe parametry przesylki (bez uslug dodatkowych).
Metoda zwraca ceny dla dostpnych w systemie firm kurierskich. W wycenie pomijani s przewonicy
dla których nie mona wyceni przesylki ze wzgldu na przekroczone parametry przesylki np.: waga
paczki, lub brak uslugi np.: paleta. Metoda udostpnia wycen przesylek wielopakowych. Metoda
zwraca sumaryczn cen netto i brutto dla danego przewonika

Elementy zasobu ,,data" metody order_valuation posiadaj nastpujce atrybuty:

Atrbut                      Typ                        Wymagane  Opis
returnvaluations            String                     Nie       Po podaniu kodu przewonika metoda
                                                                 wraca tylko wycen wybranego
shipmenttype                Enum<SHIPMENT_TYPE>        TAK       przewonika. Jeeli atrybut pozostanie
packs                       Array<ORDER_PACK>          TAK       pusty metoda zwróci wycen wszystkich
COD                         Float                      NIE       dostpnych przewoników
codtype                     Enum<COD_TYPE>             NIE       Rodzaj przesylki. Rodzaje przesylek w tabeli
return_cod                  Enum<return_cod>           NIE
                                                                 Rodzaj przesylek. Domylna warto ,,box"
insurance                   Float                      NIE       Tablica z paczk lub paczkami. Struktura w
postcode_recipient          String                     NIE       tabeli pack
postcode_sender             String                     NIE       Warto pobrania COD w PLN. Warto
recipient_country           String                     NIE       dziesitna po kropce
courierservice              Array<ADDITIONAL_SERV      NIE       Czas zwrotu pobrania. Lista kodów w tabeli
                            ICE, Bool>
                                                                 kody codtype. Domylna warto ,,S"
                                                                 Sposób zwrotu pobrania. Lista kodów w
                                                                 tabeli Sposób zwrotu pobrania Domylna

                                                                 warto ,,BA"
                                                                 Warto ubezpieczenia przesylki w PLN.
                                                                 Warto dziesitna po kropce
                                                                 Kod pocztowy odbiorcy
                                                                 Kod pocztowy nadawcy
                                                                 Kod kraju odbiorcy w formacie alpha-2
                                                                 format. Domylana warto PL
                                                                 Tablica z kodami uslug dodatkowych

Struktura odpowiedzi:

Nazwa                  Typ     Opis
                               ID kuriera
servicecode            String  Nazwa kuriera
                               Cena uslugi netto
servicename            String  Cena uslugi brutto
                               Promocyjna cena uslugi netto
netprice               Float   Promocyjna cena uslugi brutto
                               Warto przyznanego rabatu netto
grossprice             Float   Warto przyznanego rabatu brutto
                               Czy kurierem mona wysla zlecenie
promotion_nett         Float   Czy kurier jest dostpny
                               Dodatkowy komunikat o niedostpnoci przewonika jesli atrybut available
promotion_gross        Float   ma warto false

rebate_nett            Float

rebate_gross           Float

shipment               Bool

available              Bool

unavailable_message String

Struktura kolekcji request metody order_valuation w formacie JSON

{
    "authorization": {...},
    "apimethod": "order_valuation",
    "data": {

                                                   11
        "returnvaluations": "",
        "shipmenttype": "box",
        "packs": [{

            "length": 10,
            "width": 20,
            "height": 30,
            "weight": 5,
            "amount": 1,
            "type": "ST"
        }],
        "COD": 100,
        "codtype":"S" ,
        "return_cod":"BA" ,
        "insurance": 100,
        "postcode_recipient": "63-400",
        "postcode_sender": "63-400",
        ,,recipient_country": "PL",
        "courierservice": {
            "ROD": false,
            "COURIER_WITH_LABEL": false,
            "WEEK_COLLECTION": false
        }
    }
}

Struktura kolekcji response metody order_valuation w formacie JSON

{
    "status": "success",
    "response": [{
        "servicecode": "UPS",
        "servicename": "UPS - Standard",
        "netprice": 1.00,
        "grossprice": 1.23
    },{
        "servicecode": "UPS_ES",
        "servicename": "UPS - Express Saver",
        "netprice": 2.00,"grossprice":2.46
    },
    {...}]

}

                                                                          12
Metoda: order_valuation_v2 ­ wycena przesylki

Wycena wysylki w oparciu o podane podstawowe parametry przesylki oraz uslugi dodatkowe. Metoda
zwraca ceny dla dostpnych w systemie firm kurierskich. W wycenie pomijani s przewonicy dla
których nie mona wyceni przesylki ze wzgldu na przekroczone parametry przesylki np.: waga
paczki, lub brak uslugi np.: paleta. Metoda udostpnia wycen przesylek wielopakowych. Metoda
zwraca sumaryczn cen netto i brutto dla danego przewonika

Elementy zasobu ,,data" metody order_valuation_v2 posiadaj nastpujce atrybuty:

Atrbut                      Typ                    Wymagane  Opis
returnvaluations            String                 Nie
                                                             Po podaniu kodu przewonika metoda
                                                             wraca tylko wycen wybranego
                                                             przewonika. Jeeli atrybut pozostanie
                                                             pusty metoda zwróci wycen wszystkich
                                                             dostpnych przewoników

Pozostale atrybuty s identyczne jak w metodzie create_order i zostaly szczególowo opisane w tabeli
,,order_request".

Wszystkie atrybuty poza shipmenttype s opcjonalne. Im wicej danych zostanie przekazane bardziej precyzyjna
bdzie wycena.

Struktura odpowiedzi:

Nazwa                  Typ          Opis
                                    ID kuriera
servicecode            String       Nazwa kuriera
                                    Cena uslugi netto
servicename            String       Cena uslugi brutto
                                    Promocyjna cena uslugi netto
netprice               Float        Promocyjna cena uslugi brutto
                                    Warto przyznanego rabatu netto
grossprice             Float        Warto przyznanego rabatu brutto
                                    Czy kurierem mona wysla zlecenie
promotion_nett         Float        Czy kurier jest dostpny
                                    Dodatkowy komunikat o niedostpnoci przewonika jesli atrybut available
promotion_gross        Float        ma warto false

rebate_nett            Float

rebate_gross           Float

shipment               Bool

available              Bool

unavailable_message String

Struktura kolekcji request metody order_valuation_v2 w formacie JSON

{
   "authorization":{...},
   "apimethod": "order_valuation_v2",
   "data": {
          "shipmenttype": "palette",
          "packs": [{
              "length": 120,
              "width": 80,
              "height": 100,
              "weight": 120,
              "amount": 1,
              "type": "ST"
          }],
          "sender_": {
              "postcode": "63-400"
          },
          "recipient": {
              "postcode": "8051",
              "country": "DE"
          },
          "courierservice": {

                                               13
              "WEEK_COLLECTION": 0,
              "SMS_NOTIFICATION_RECIPIENT_WITH_NAME": 1
          }
   }
}

Struktura kolekcji response metody order_valuation w formacie JSON

{
   "status": "success",
   "response": [
       {
          "servicecode": "RABEN_EXPORT",
          "serviceName": "Raben Eksport",
          "netprice": 165.18,
          "grossprice": 203.17,
          "conditional_price_nett": 0,
          "conditional_price_gross": 0,
          "promotion_nett": 0,
          "promotion_gross": 0,
          "rebate_nett": 0,
          "rebate_gross": 0,
          "shipment": true,
          "available": true,
          "unavailable_message": ""
       },
       ...
   ]

}

                                                                          14
Metoda: create_order ­ nowa przesylka

Glównym elementem Polkurier WebService API s przesylki. Na definicj przesylki skladaj si:

 kod przewonika
 rodzaj przesylki
 dane nadawcy i odbiorcy
 paczka (jedna lub wicej), która bdzie fizycznie przesylana
 opcjonalnie uslugi dodatkowe
 dodatkowe atrybuty np.:

          o ubezpieczenie przesylki

          o pobranie (COD)
 termin odbioru przesylki przez kuriera jeeli jest wymagany

Poprawne wypelnienie wszystkich elementów pozwoli na szybkie i bezbldne zloenie zlecenia oraz
pobranie listu przewozowego.

Elementy zasobu ,,data" metody create_order posiadaj nastpujce atrybuty:

Tabela: order_request

Atrybut       Typ                             Wyma Opis

                                              gane

shipmenttype  Enum<SHIPMENT_TYPE>             TAK 1 Rodzaj przesylki. Lista w tabeli Rodzaj
                                                          przesylek.

courier       String                          TAK Kod przewonika którym chcemy nada

                                                    przesylk. Pelna lista dostpnych

                                                    przewoników oraz ich kody dostpna w

                                                    metodzie available_carriers

courierservice Map<ADDITIONAL_SERVICE, Bool> NIE Lista uslug dodatkowych. Lista w tabeli

                                                    Uslugi dodatkowe.

description   String                          TAK Opis zawartoci przesylki (maksymalnie 30

                                                    znaków)

sender        ORDER_SENDER                    TAK Kolekcja z danymi nadawcy. Szczególy w

                                                    tabeli sender

recipient     ORDER_RECIPIENT                 TAK Kolekcja z danymi odbiorcy. Szczególy w

                                                    tabeli recipient

cover_address COVER_ADDRESS                   NIE Dodatkowy adres umoliwiajcy ukrycie

                                                    Twojego rzeczywistego adresu nadawczego

                                                    na licie przewozowym

packs         Array<ORDER_PACK>               TAK Kolekcja z wymiarami paczki/paczek.

                                                    Szczególy w tabeli packs

pickup        ORDER_PICKUP                    TAK2 Kolekcja z terminem podjazdu kuriera

                                                    Szczególy w tabeli pickup

COD           ORDER_COD                       NIE Tablica z kolekcj atrybutów pobrania.

                                                    Szczególy w tabeli COD. Dla przesylek bez

                                                    pobrania kolekcja moe zosta pominity

insurance     Float                           NIE Warto ubezpieczenia. Warto w PLN.
                                                          Warto dziesitna po kropce. Dla przesylek

                                                    bez ubezpieczenia atrybut moe zosta

                                                    pominity

additional_fields Object<string, string>      NIE Mapa pól dodatkowych specyficznych dla

                                                    przewonika. List wymaganych pól oraz ich

                                                    wartoci mona pobra za pomoc metody

                                                    available_carriers z parametrem

                                                    additional_data=TRUE

1 - lista dostpnych rodzajów przesylek dla poszczególnych przewoników do pobrania za pomoc metody available_carriers

2 - lista atrybutów wymaganych oraz dostpnych do pobrania za pomoc metody available_carriers

                                          15
Elementy kolekcji ,,sender" metody create_order posiadaj nastpujce atrybuty:

Tabela: sender

Encja ORDER_SENDER

Atrybut            Typ     Dlugo  Wymagane  Opis
                           35     NIE       Nazwa firmy nadawcy
company            String  35     TAK       Imi i nazwisko nadawcy
                           40     TAK       Ulica nadawcy
person             String  5      TAK       Numer domu nadawcy
                           5      NIE       Numer mieszkania nadawcy
street             String  6      TAK       Kod pocztowy nadawcy
                           35     TAK       Miejscowo nadawcy
housenumber        String  100    TAK       Adres e-mail nadawcy
                           15     TAK       Nr telefonu nadawcy
flatnumber         String  2      NIE       Kraj nadawcy. Kraj w formacie alpha-2 format.
                                            Domylana warto PL
postcode           String  10     NIE1      Kod punktu nadawczego

city               String

email              String

phone              String

country            String

point_id           String

Elementy kolekcji ,,recipient" metody create_order posiadaj nastpujce atrybuty:

Tabela: recipient

Encja ORDER_RECIPIENT

Atrybut            Typ     Dlugo  Wymagane  Opis
                           35     NIE       Nazwa firmy odbiorcy
company            String  35     TAK       Imi i nazwisko odbiorcy
                           40     TAK       Ulica odbiorcy
person             String  5      TAK       Numer domu odbiorcy
                           5      NIE       Numer mieszkania odbiorcy
street             String  6      TAK       Kod pocztowy odbiorcy
                           35     TAK       Miejscowo odbiorcy
housenumber        String  100    TAK       Adres e-mail odbiorcy
                           15     TAK       Nr telefonu odbiorcy
flatnumber         String  2      NIE       Kraj odbiorcy. Kraj w formacie alpha-2 format.
                                            Domylana warto PL
postcode           String  10     NIE1      Kod punktu odbioru

city               String

email              String

phone              String

country            String

point_id           String

Elementy kolekcji ,,cover_address" metody create_order posiadaj nastpujce atrybuty:

Tabela: cover_address

Encja COVER_ADDRESS

Atrybut            Typ     Dlugo  Wymagane  Opis
                           35     NIE       Nazwa firmy nadawcy
company            String  35     NIE       Imi i nazwisko nadawcy
                           40     NIE       Ulica nadawcy
person             String  5      NIE       Numer domu nadawcy
                           5      NIE       Numer mieszkania nadawcy
street             String  6      NIE       Kod pocztowy nadawcy
                           35     NIE       Miejscowo nadawcy
housenumber        String  100    NIE       Adres e-mail nadawcy
                           15     NIE       Nr telefonu nadawcy
flatnumber         String

postcode           String

city               String

email              String

phone              String

                                  16
Elementy kolekcji ,,pickup" metody create_order posiadaj nastpujce atrybuty:

Tabela pickup

Encja ORDER_PICKUP

Atrybut                Typ    Wymagane  Opis
pickupdate             Date   TAK1,2    Data podjazdu kuriera.
pickuptimefrom         Time   TAK1,2    godzina "od" oczekiwania na podjazd kuriera
pickuptimeto           Time   TAK1,2    godzina "od" oczekiwania na podjazd kuriera

nocourierorder         Bool   NIE       Samodzielne zamówienie kuriera przez telefon lub dostarczenie

                                        do punktu nadawczego. Domylna warto FALSE. Dostpno

                                        opcji dla poszczególnych przewoników do pobrania za
                                        pomoc metody available_carriers

multiPickup            Bool   Nie       Czy podjazd zbiorczy. Jeli true to dla zlecenia NIE zostanie

                                        zamówiony odbiór przesylek przez kuriera. Odbiór przesylek

                                        naley zamówi za pomoc metody create_multi_order_pickup.

                                        Dostpno zbiorczego podjazdu dla danego zlecenia mona
                                        sprawdzi za pomoc metody is_multi_pickup_available

1 ­ kiedy warto atrybutu nocourierorder == true lub multiPickup == true pole jest pomijane.

2 ­ obowizek wypelnienia dla poszczególnych przewoników do pobrania za pomoc metody available_carriers

Elementy kolekcji ,,COD" metody create_order posiadaj nastpujce atrybuty:

Tabela COD

Atrybut                Typ              Wymagane Opis

codtype                Enum<COD_TYPE>   NIE              Czas zwrotu pobrania. Lista kodów w tabeli kody

                                                         codtype. Domylna warto ,,S"

codamount              Float            NIE              Warto pobrania. Warto w PLN. Warto

                                                         dziesitna po kropce

codbankaccount Int                      TAK 1            Numer konta bankowego

return_cod             Enum<return_cod> NIE              Sposób zwrotu pobrania. Lista kodów w tabeli

                                                         Sposób zwrotu pobrania Domylna warto ,,BA"

1) w przypadku kiedy atrybut return_cod przyjmie warto PO numer konta jest pomijany i nie jest wymagany

Elementy kolekcji ,,packs" posiadaj nastpujce atrybuty:

Tabela packs

Encja ORDER_PACK

Atrybut         Typ                Wymagane              Opis
                                   TAK                   Warto w centymetrach.
length          Int                TAK                   Warto w centymetrach.
                                   TAK                   Warto w centymetrach.
width           Int                TAK                   Waga w kilogramach. Warto dziesitna po kropce
                                   NIE                   Ilo. Domylna warto 1 nie wiksza ni 99
height          Int                NIE                   Lista dostpnych opcji w tabeli Typy przesylek. Domylna

weight          Float                                    warto ,,ST"

amount          Float

type            Enum<PACK_TYPE>

Struktura kolekcji request metody create_order w formacie JSON

{
    "authorization": {...},
    "apimethod": "create_order",
    "data": {
        "shipmenttype": "box",
        "courier": "UPS",
        "courierservice": {[
            "ROD": false,
            "COURIER_WITH_LABEL": false,
            "WEEK_COLLECTION": false
        ]},
        "description": "testowa paczka",
        "sender": {
            "company": "",
            "person": "Jan Kowalski",

                                        17
            "street": "Kurierska ",
            "housenumber": "1",
            "flatnumber": "",
            "postcode": "63-400",
            "city": "Ostrów Wielkopolski",
            "email": "test@test.pl",
            "phone": "123456789",
            "country": "PL",
            "point_id": ""
        },
        "recipient": {
            "company": "",
            "person": "Jan Nowak",
            "street": "Poznaska",
            "housenumber": "123",
            "flatnumber": "1",
            "postcode": "60-001",
            "city": "Pozna",
            "email": "test@test.pl",
            "phone": "123456789",
            "country": "PL",
            "point_id": ""
        },
        "packs": [{
            "length": 10,
            "width": 10,
            "height": 10,
            "weight": 5,
            "amount": 1,
            "type": "NST"
        }],
        "pickup": {
            "pickupdate": "2018-05-15",
            "pickuptimefrom": "10:00",
            "pickuptimeto": "14:00",
            "nocourierorder": false
        },
        "COD": {
            "codtype": "S",
            "codamount": 5000,
            "codbankaccount": "66116022020000000249765498",
            "return_cod": "BA"
        },
        "insurance": 5000,
         "additional_fields": {
            "external_transport_security": "TAPE"
         }
    }
}

Po poprawnym zloeniu zamówienia serwer zwróci ponisz kolekcj

Atrubut         Typ     Opis

order_number    String  Numer zlecenia zloonego w serwisie polkurier.pl

label           Array<String> Tablica z numerem/numerami listów przewozowych

price_gross     Float   Cena netto nadania przesylki

price_net       Float   Cena brutto nadania przesylki

url_tracktrace  String  Adres URL do ledzenia statusu przesylki

unpaid_amount   Float   Nieoplacona warto zlecenia (brutto)

is_paid         Bool    Czy zamówienie jest w pelni oplacone

Struktura kolekcji response metody create_order w formacie JSON

{
    "status": "success",
    "response": {
        "order_number": "1234-10",

                              18
        "label": ["13299300045383"],
        "price_gross": 10.00,
        "price_net": 12.23,
        "url_tracktrace": "https://inpost.pl/sledzenie-przesylek?number=13299300045383",
        "unpaid_amount": 0.0,
        "is_paid": true
    }
}

Struktura kolekcji response metody create_order z komunikatem o bldzie w formacie JSON

{
    "status": "error",
    "response": "Dlugo paczki przekracza dopuszczaln warto (270)."

}

                                                                          19
Metoda: get_label - pobieranie pliku etykiety

Metoda umoliwia pobranie etykiety do zlecenia lub zlece zloonych w serwisie polkurier.pl. Metoda
pozwala na pobranie etykiet dla zlece zloonych przez API oraz nadanych poprzez formularz
zamówienia w serwisie polkurier.pl. Metoda zwraca plik PDF zakodowany w formacie base64. W
przypadku dodania wicej ni jeden numer zlecenia zostanie zwrócony plik PDF z etykietami
wybranych zlece polczonych w jeden dokument. Metoda zwróci tylko etykiety do zlece
posiadajcych wygenerowany numer listu przewozowego.

Elementy kolekcji `data' metody get_label posiadaj nastpujce atrybuty:

      Atrybut          Typ                     Wymagane  Opis
      orderno          Array<String>           TAK       Tablica numerów zlece zloonych w serwisie
                                                         polkurier.pl

Struktura odpowiedzi:

Atrybut                Typ                     Opis
                                               Zawarto pliku zakodowana w Base64
file                   String

Struktura kolekcji request metody get_label w formacie JSON

{
    "authorization":{},
    "apimethod":"get_label",
    "data":{
        "orderno":["1234-1","1234-2"]
    }

}

Struktura kolekcji response metody get_label w formacie JSON

{
    "status":"success",
    "response":{
        "file":"JVBERi0xLjQKMyAwIG9iago8PC9U..."
    }

}

                                               20
Metoda: get_protocol ­ pobieranie protokolu zdawczo-odbiorczego

Metoda umoliwia pobranie protokolu zdawczo-odbiorczego do zloonego zlecenia lub zlece.
Metoda zwraca plik PDF zakodowany w formacie base64. Metoda zwróci tylko protokól do zlece
posiadajcych wygenerowany numer listu przewozowego.

Elementy kolekcji data metody get_protocol posiadaj nastpujce atrybuty:

      Atrybut          Typ            Wymagane  Opis
      orderno          Array<String>  TAK       Kolekcja numerów zlece zloonych w serwisie
                                                polkurier.pl

Struktura odpowiedzi:

Atrybut                Typ            Opis
                                      Zawarto pliku zakodowana w Base64
file                   String

Struktura kolekcji request metody get_protocol w formacie JSON

{
    "authorization": {...},
    "apimethod": "get_protocol",
    "data": {
        "orderno": ["1234-1", "1234-2"]
    }

}

Struktura kolekcji response metody get_protocol w formacie JSON

{
    "status": "success",
    "response": {
        "file": "JVBERi0xLjQKJeLjz9...
    }

}

                                      21
Metoda: get_status ­ status przesylki

Metoda zwraca status przesylki nadanej poprzez serwis polkurier.pl.

Elementy kolekcji data metody get_status posiadaj nastpujce atrybuty:

Atrybut         Typ                    Wymagane  Opis
orderno         string                 TAK       Numer zlecenia

Struktura kolekcji request metody get_status w formacie JSON

{
    "authorization": {...},
    "apimethod": "get_status",
    "data": {
        "orderno": "1234-1"
    }

}

Zwrócone elementy kolekcji metody get_status posiadaj nastpujce atrybuty:

Atrybut         Typ                              Opis
url             String                           Link do strony monitorowania statusu przesylki po stronie
                                                 przewonika
status_date     DateTime                         Data i godzina aktualizacji statusu
status          String                           Opis statusu
status_code     Enum<ORDER_STATUS>               Kod statusu. Lista statusów w tabeli Lista statusów
delivered_date  Date
                                                 Data dostarczenia przesylki. Do czasu dostarczanie przyjmuje
                                                 warto null. Warto zaktualizowana w momencie dostarczenia
                                                 przesylki do adresata

Struktura kolekcji response metody get_status w formacie JSON

{
    "status": "success",
    "response": {
        "url":"https://tracktrace.dpd.com.pl/parcelDetails?

p1=13299300045383&ID_kat=3&ID=33&Mark=18",
        "status_date": "2018-06-12T23:51:12+02:00",
        "status": "Dostarczone",
        "status_code": "D",
        "delivered_date": "2018-06-12"

    }
}

                                                 22
Metoda: cancel_order ­ anulowanie przesylki

Metoda umoliwia anulowanie przesylki. Metoda dostpna jest dla przesylek ze statusem ,,oczekuje"
oraz ,,zatwierdzona". Dla przesylek w transporcie, anulowane lub zwrot metoda jest nie aktywna i jej
wywolanie zwróci bld

Elementy kolekcji data metody cancel_order posiadaj nastpujce atrybuty:

Atrybut       Typ     Opis
orderno       String  Numer zlecenia zloonego w serwisie polkurier.pl

Struktura kolekcji request metody cancel_order w formacie JSON

{
    "authorization": {...},
    "apimethod": "cancel_order",
    "data": {
        "orderno": "1234-1"
    }

}

Zwrócone elementy kolekcji metody cancel_order posiadaj nastpujce atrybuty:

Atrybut       Typ     Opis
cancellation  Bool    Warto true jest potwierdzeniem anulowania zlecenia

Struktura kolekcji response metody cancel_order w formacie JSON

{
    "status": "success",
    "response": {
        "cancellation": true
    }

}

Struktura kolekcji response metody cancel_order w formacie JSON z informacj o bldzie przy próbie
anulowania, wczeniej anulowanego zlecenia:

{
    "status": "error",
    "response": "Zamówienie 1234-1 zostalo ju anulowane"

}

                                             23
Metoda: pickup_courier ­ godziny podjazdu kuriera dla danego dnia

Metoda zwraca godziny podjazdu dla wybranego przewonika w danym dniu.

Elementy kolekcji ,,data" metody pickup_courier posiadaj nastpujce atrybuty:

Atrybut     Typ     Opis
pickupdate  Date    Data planowanego nadania przesylki
courier     String  Kod przewonika dla którego pobieramy godziny podjazdu
shipfrom    String  Kod pocztowy nadawcy
parcel      String  Rodzaj przesylki któr nadajemy. List rodzajów w tabeli Rodzaj przesylek

Struktura kolekcji request metody pickup_courier w formacie JSON

{
    "authorization": {...},
    "apimethod": "pickup_courier",
    "data": {
        "pickupdate": "2018-06-01",
        "courier": "UPS",
        "shipfrom": "63-400",
        "parcel": "box"
    }

}

Atrybut     Typ     Opis
pickupdate  Bool
                    Warto true oznacza moliwo zamówienia przewonika na dat podan w
time        Array   zapytaniu. W przypadku wartoci false naley wybra inn dat
                    Tablica z zakresem godzin które mona poda podczas skladania zlecenia.
                    Jeeli ,,pickupdate" ma warto true, a tablica" time" jest pusta oznacza
                    e przewonik wymaga zdefiniowania wylcznie daty podjazdu bez
                    wyszczególniania godzin.

Struktura kolekcji response metody pickup_courier w formacie JSON

{
    "status": "success",
    "response": {
        "pickupdate": true,
        "time":[
            {"timefrom": "09:00", "timeto": "12:00"},
            {"timefrom": "10:00", "timeto": "13:00"},
            {"timefrom": "11:00", "timeto": "14:00"},
            {"timefrom": "12:00", "timeto": "15:00"},
            {"timefrom": "13:00", "timeto": "16:00"}
        ]
    }

}

W przypadku braku moliwoci zamówienia kuriera dla wskazanej daty serwer zwróci bld.

Struktura kolekcji response metody pickup_courier w formacie JSON z informacj o braku moliwoci
zamówienia kuriera dla wybranej daty:

{
    "status": "error",
    "response": "Przekroczono ostateczny termin zamówienia kuriera lub brak moliwoci

zamówienia kuriera. Prosz wybra inn dat"
}

                    24
Metoda: get_courier_pickup_time ­ Zwraca dni i godziny podjazdu kuriera

Metoda zwraca daty i godziny podjazdu dla wybranego przewonika dla 5 najbliszych dni roboczych.

Elementy zwrócone metody get_courier_pickup_time posiadaj nastpujce atrybuty:

Nazwa          Typ     Wymagany Opis

courier        String  Tak            Kod przewonika dla którego pobieramy godziny
                                      podjazdu

shipfrom       String  Nie            Kod pocztowy nadawcy

shipto         String  Nie            Kod pocztowy odbiorcy

parcel         String  Tak            Rodzaj przesylki któr nadajemy. List rodzajów w tabeli
                                      Rodzaj przesylek

Elementy zwrócone metody get_courier_pickup_time posiadaj nastpujce kolekcje:

Nazwa          Typ     Opis

pickupdate     Date    Data w formacie ISO

time           Array   Tablica z zakresem godzin które mona poda podczas skladania

                       zlecenia.

time.timefrom  Time    Minimalna godzina odbioru w formacie HH:MM

time.timeto    Time    Maksymalna godzina odbioru w formacie HH:MM

Struktura kolekcji request metody get_courier_pickup_time w formacie JSON

{
    "authorization": {...},
    "apimethod": "get_courier_pickup_time",
    "data": {
        "courier": "DPD",
        "shipfrom": "63-400",
        "shipmenttype": "box"
    }

}

Struktura kolekcji response metody get_courier_pickup_time w formacie JSON

{
    "status": "success",
    "response": [
        {
            "pickupdate": "2024-01-03",
            "time": [
                 {"timefrom": "11:00", "timeto": "13:00"},
                 {"timefrom": "12:00", "timeto": "14:00"}
            ]
        },
        ...

]

                                  25
Metoda: get_countries ­ lista krajów obslugiwanych przez danego kuriera

Metoda zwraca kolekcj pastw z kodami w formacie alpha-2 format dostpnych dla adresatów
zagranicznych. W kolekcji jako klucz podany zostal kod kraju który podajemy podczas skladania
zlecenia, natomiast wartoci jest nazwa kraju.

Elementy kolekcji "data" metody get_countries posiadaj nastpujce atrybuty:

Atrybut   Typ     Opis
couriers  string
                  Kod przewonika z dostaw po za granicami kraju którym nadajemy przesylk
                  UPS_EX ­ UPS Export
                  DPDEXP ­ DPD Export
                  Pelna lista dostpnych przewoników oraz ich kody dostpna w metodzie
                  available_carriers

Struktura kolekcji request metody get_countries w formacie JSON

{
    "authorization": {...},
    "apimethod": "get_countries",
    "data": {
        "couriers": "UPS_EX"
    }

}

Struktura kolekcji response metody get_countries w formacie JSON

{
    "status": "success",
    "response": {
        "CZ": "Czechy",
        "SK": "Slowacja",
        "AT": "Austria",
        "DE": "Niemcy",
        ...
    }

}

                  26
Metoda: get_supported_countries_v2 - Zwraca list wszystkich obslugiwanych krajów

Metoda zwraca kolekcj wszystkich pastw z kodami w formacie alpha-2 format dostpnych dla
adresatów zagranicznych.

Metoda nie przyjmuje adnych parametrów wejciowych.

Elementy zwrócone metody get_supported_countries_v2 posiadaj nastpujce atrybuty:

Nazwa       Typ     Opis

id          String  Kod alpha-2 kraju

name        String  Nazwa kraju w jzyku polskim

is_ue       Bool    Czy kraj jest czlonkiem Unii Europejskiej

is_default  Bool    Czy kraj jest domylnym krajem nadania lub odbioru

provinces   Array   Kolekcja jednostek administracyjnych, np. stanów

id          String  Kod np. TX - Texas

name        String  Nazwa w jzyku polskim

Struktura kolekcji request metody get_supported_countries_v2 w formacie JSON

{
    "authorization": {...},
    "apimethod": "get_supported_countries_v2",
    "data": {}

}

Struktura kolekcji response metody get_supported_countries_v2 w formacie JSON

{
    "status": "success",
    "response": [{
        "id": "AF",
        "name": "Afganistan",
        "is_ue": false,
        "is_default": false,
        "provinces": []
    }, {
        "id": "US",
        "name": "Stany Zjednoczone Ameryki",
        "is_ue": false,
        "is_default": false,
        "provinces": [{
            "id": "AL",
            "name": "Alabama"
        }, {
            "id": "AK",
            "name": "Alaska"
        }, ...]},
        ...
    ]

}

                          27
Metoda: get_courier_point ­ lista punktów kurierskich / paczkomatów

Metoda zwraca kolekcj wszystkich punktów kurierskich / paczkomatów z cechami które informuj
czy w danym punkcie mona nada przesylk, odebra lub nada przesylk pobraniow.

Metoda zastpuje metody: inpost_parcel_machines, pocztex_post_offices, inpost_points_machines

Elementy kolekcji "data" metody get_courier_point posiadaj nastpujce atrybuty:

Atrybut       Typ             Wymagane Opis

couriers      Array<String> Tak          Lista przewoników jakich musi obslugiwa punkt (jeden lub
                                         wicej). Przyklad: ["INPOST_PACZKOMAT"]

id            String          Nie        Wyszukiwanie po ID punktu. Zwrócony zostanie tylko jeden

                                         wynik lub pusta tablica w przypadku jeli nie zostanie

                                         znaleziony punkt o danym ID.

searchquery   String          Nie        Fraza wysukiwania. Moe to by ID punktu lub cz adresu.
                                         Zwrócone zostanie pierwsze 1000 wyników.

functions     Array<COURIE Nie           Lista funkcji, jakie musi obslugiwa punkt (Zero lub wicej) z
              R_POINT_FU                 tabeli COURIER_POINT_FUNCTION.
              NCTION>                    Przyklad: ["collect", "cod"]

limit         Int             Nie        Ilo wyników na stron. Jeli parametr zostanie pominity to

                                         zwrócone zostan wszystki wyniki.

                                         Uwaga: Ze wzgldu na du ilo punktów, i objcto
                                         zwróconego zbioru danych zalecemy stosowanie
                                         stronicowania.

page          Int             Nie        Strona wyników jeli przekazano parametr limit

Elementy zwrócone metody get_courier_point posiadaj nastpujce kolekcje:

Encja COURIER_POINT

Atrybut               Typ          Opis

id                    String       ID / Kod punktu do podania podczas skladania zlecenia

type                  String       Informacja o typie punktu specyficzna dla przewonika

provider              String       Przewonik, którego obsluguje punkt

city                  String       Miasto lokalizacji punktu

zip                   String       Kod pocztowy lokalizacji punktu

street                String       Ulica lokalizacji punktu

description           String       Opis lokalizacji punktu

latitude              Float        Szeroko geograficzna lokalizacji punktu

longitude             Float        Dlugo geograficzna lokalizacji punktu

cod                   Bool         Czy punkt obsluguje pobrania

available             Bool         Czy punkt jest dostpny do obslugi przesylek

status                String       Status punktu

send                  Bool         Czy punkt obsluguje nadanie przesylki

collect               Bool         Czy punkt obsluguje odbiór przesylki

openingHours          String       Opis godzin otwarcia / dostpnoci punktu

visible               Bool         Czy punkt jest widoczny

requireApp            Bool         Czy punkt wymaga aplikacji mobilnej obslugi zlecenia

                                         28
   requireAppMessage        String         Dodatkowy opis jeli punkt wymaga aplikacji mobilnej do obslugi
   functions                               zlecenia

   countryiso               Array<COURIER_ Lista funkcji, jakie obsluguje punkt z tabeli Tabela funkcji punktu
                            POINT_FUNCTIO
                            N>

                            String         Kod ISO karaju, w którym znajduje si punkt

Funkcje punktów kurierskich / paczkomatów

   Tabela funkcji punktu
   Enum COURIER_POINT_FUNCTION

   Nazwa                    Opis

   cod                      obsluga pobra

   send                     moliwo nadania przesylki

   collect                  moliwo odbioru przesylki

Struktura kolekcji request metody get_courier_point w formacie JSON

{

   "authorization": {...},

   "apimethod": "get_courier_point",

   "data": {

      "couriers": ["INPOST_PACZKOMAT"],

      "functions": ["cod", "collect"]

   }

}

Struktura kolekcji response metody get_courier_point w formacie JSON

{
    "status": "success",
    "response": [
        {
            "id": "ADA01M",
            "type": "parcel_locker",
            "name": "",
            "provider": "INPOST_PACZKOMAT",
            "city": "Adamów",
            "zip": "21-412",
            "street": "Kociuszki 27",
            "description": "Przy sklepie Lewiatan ",
            "latitude": 51.73834,
            "longitude": 22.26405,
            "cod": true,
            "available": true,
            "status": "Operating",
            "send": true,
            "collect": true,
            "openingHours": "24\/7",
            "visible": true,
            "address": "21-412 Adamów, Kociuszki 27",
            "requireApp": false,
            "requireAppMessage": "",
            "functions": [
                 "cod",
                 "collect",
                 "send"
            ]
        },
        ...
    ]

}

                                           29
Metoda: get_orders ­ szczególy zamówienia ­ lista zamówie

Metoda zwraca list zamówie lub szczególy wybranego zamówienia zloonego w serwisie
POLKURIER.PL. Metoda domylnie zwraca list 100 przesylek posortowane od najnowszego do
najstarszego. Szczególy pojedynczego zamówienia zwracane s po przekazaniu numeru zamówienia

w atrybucie ,,orderno"

Elementy kolekcji ,,data" metody get_orders posiada atrybuty:

Atrybut    Typ     Wy Opis
orderno    String
status     String  mag
                   any
courier    String
cod_min    String  Nie Numer zamówienia. Zwraca szczególy zamówienia. W przypadku
cod_max    String          podania numeru zamówienia.
date_from  Date
date_to    Date    Nie Filtr z jakich statusach zostanie zwrócona lista przesylek. Lista
search     String          dostpnych kodów w tabeli Lista statusów
                            Atrybut pomijany w momencie przekazania numeru zamówienia w atrybucie
pagesize   Int              ,,orderno".

page       Int     Nie Pozwala na wyfiltrowanie zamówie po ID przewonika. Dostpne ID
                           przewoników mona pobra za pomoc metody available_carriers
packs      Bool
                   Nie Pozwala wyfiltrowa zamówienia z minimaln kwot pobrania.
items      Bool
                   Nie Pozwala wyfiltrowa zamówienia z maksymaln kwot pobrania.
files      Bool
                   Nie Pozwala wyfiltrowa zamówienia zloone po wskazanej dacie.

                   Nie Pozwala wyfiltrowa zamówienia zloone do wskazanej daty.

                   Nie Wyszukiwanie po frazie. Pozwala na wyszukiwanie zamówie po
                           numerze zamówienia, numerze listu przewozowego lub adresie
                           odbiorcy.

                   Nie Ilo zamówie na licie. Maksymalnie 100
                            Atrybut pomijany w momencie przekazania numeru zamówienia w atrybucie
                            ,,orderno".

                   Nie Okrela stron wyników, która powinna zosta zwrócona.
                            Atrybut pomijany w momencie przekazania numeru zamówienia w atrybucie
                            ,,orderno".

                   Nie Warto ,,true" spowoduje zwrócenie dodatkowych informacji o
                           paczkach w przesylce.
                            Atrybut pomijany w momencie przekazania numeru zamówienia w atrybucie
                            ,,orderno".

                   Nie Warto ,,true" spowoduje zwrócenie dodatkowych informacji o
                           wycenie.
                            Atrybut pomijany w momencie przekazania numeru zamówienia w atrybucie
                            ,,orderno".

                   Nie Warto ,,true" spowoduje zwrócenie listy zalczonych plików.
                            Atrybut pomijany w momencie przekazania numeru zamówienia w atrybucie
                            ,,orderno".

Struktura kolekcji request metody get_orders dla pobrania szczególów pojedynczego zamówienia w
formacie JSON

{
    "authorization": {...},
    "apimethod": "get_orders",
    "data": {
        "orderno": "123456-1"
    }

}

Struktura kolekcji response metody get_orders dla pojedynczego zamówienia w formacie JSON

{
    "status":"success",
    "response": {
        "number": "123456-1",
        "date": "2021-01-01T13:43:15+0200",

                   30
"description": "Testowa",
"courier": "INPOST_PACZKOMAT",
"status": "Potwierdzone",
"status_code": "P",
"price_gross": 10.00,
"price_net": 12.30,
"is_paid": true,
"has_invoice": false,
"unpaid_amount": 0.0,
"url": "https://inpost.pl/pl/pomoc/znajdz-przesylke?parcel=111111111111111111111111",
"status_date": "2021-01-02T12:00:00+0200",
"label": [

    "111111111111111111111111"
],
"waybills": [{

    "number": "111111111111111111111111",
    "is_default": true
}],
"delivered_date": "2021-01-03T12:00:00+0200",
"insurance": 100.00,
"sender": {
    "company": "",
    "person": "Jan Kowalski",
    "street": "Kaliska 35A",
    "postcode": "63-400",
    "city": "Ostrów Wielkopolski",
    "phone": "123456789",
    "email": "test@test.pl",
    "country": "PL",
    "point_id": "POP-OWI1"
},
"recipient": {
    "company": "",
    "person": "Jan Nowak",
    "street": "Testowa 1",
    "postcode": "52-340",
    "city": "Wroclaw",
    "phone": "123456789",
    "email": "test@test.pl",
    "country": "PL",
    "point_id": "OWI04N"
},
"COD": {
    "codtype": "S"
    "codamount": 100.00
    "codbankaccount": "AABBBBBBBBCCCCCCCCCCCCCCCC"
    "return_cod": "BA",
    "status": "PAID",
    "return_details": [{

        "reason": "CUSTOMER_MONEY_BOX_FEE",
        "description": "Oplata manipulacyjna za wyplat ze skarbonki",
        "document_number": "00/000/KOM",
        "invoice_number": ["0/00/000/POL"],
        "date": "2023-10-25T15:07:15+02:00",
        "amount": 30.0
    }, {
        "reason": "CUSTOMER_PAID",
        "description": "Wyplacone",
        "document_number": "251023-00000-3",
        "date": "2023-10-25T00:00:00+02:00",
        "amount": 70.0
    }]
},
"pickup": {
    "pickupdate": null,
    "pickuptimefrom": null,

                                                                   31
            "pickuptimeto": null,
            "nocourierorder": true
        },
        "packs": [{
            "length": 10,
            "width": 10,
            "height": 10,
            "weight": 10,
            "amount": 1,
            "type": "ST",
            "price_net": 1.00,
            "price_gross": 1.23
        }],
        "courierservice": [
            "Pobranie (COD)",
            "Ubezpieczenie przesylki"
        ],
        "items": [{
            "description": "Paczka nr 1",
            "amount": 1,
            "price": 8.0,
            "value_nett": 8.0,
            "value_gross": 9.84,
            "type": "PACK"
        }, {
            "description": "Pobranie",
            "amount": 1,
            "price": 1.0,
            "value_nett": 1.0,
            "value_gross": 1.23,
            "type": "SERVICE"
        }, {
            "description": "Ubezpieczenie przesylki",
            "amount": 1,
            "price": 1.0,
            "value_nett": 1.0,
            "value_gross": 1.23,
            "type": "SERVICE"
        }]
    }
}

Opis zwracanych atrybutów  Typ                         Opis
       Atrybut             String                      Numer zamówienia
       number              DateTime                    Data zloenia zamówienia w formacie ISO
       date                String                      Opis zawartoci
       description         String                      Kod kuriera w API
       courier             String                      Nazwa kuriera do wywietlenia
       courier_name        Enum<SHIPMENT_TY
       shipmenttype        PE>                         Opis statusu przesylki
                           String                      Kod statusu przesylki
       status              String                      Cena brutto calej przesylki
       status_code         Float                       Cena netto calej przesylki
       price_gross         Float                       Czy zlecenie jest w pelni oplacone
       price_net           Bool                        Czy do zlecenia wystawiono faktur
       is_paid             Bool                        Warto zlecenia pozostala do zaplaty (brutto)
       has_invoice         Float                       Adres URL do strony przewonika z histori
       unpaid_amount       String                      statusów przesylki
       url                                             Data ostatniego statusu przesylki listu
                           String                      przewozowego
       status_date                                     Tablica z numerami listów przewozowych dla
                           Array<string>               przesylki
       label

                           32
delivered_date                     DateTime          Zdeprecjonowane ­ prosimy uywa atrybutu
insurance                          Float             waybills
sender                                               Data dostarczenia przesylki
sender.company                     String            Kwota ubezpieczenia przesylki
sender.person                      String
sender.street                      String            Nazwa firmy nadawcy
sender.postcode                    String            Imi i nazwisko nadawcy
sender.city                        String            Ulica
sender.phone                       String            Kod pocztowy
sender.email                       String            Miasto
sender.country                     String            Numer telefonu
sender.point_id                    String            Adres e-mail
recipient                                            Kod kraju w formacie alpha-2 format
recipient.company                  String            Kod punktu nadawczego
recipient.person                   String
recipient.street                   String            Nazwa firmy odbiorcy
recipient.postcode                 String            Imi i nazwisko odbiorcy
recipient.city                     String            Ulica
recipient.phone                    String            Kod pocztowy
recipient.email                    String            Miasto
recipient.country                  String            Numer telefonu
recipient.point_id                 String            Adres e-mail
COD                                                  Kod kraju w formacie alpha-2 format
COD.codtype                        Enum              Kod punktu odbiorcy

COD.codamount                      Float             Czas zwrotu pobrania. Lista kodów w tabeli
COD.codbankaccount                 String            kody codtype.
                                                     Warto pobrania. Warto w PLN
COD.return_cod                     Enum<return_cod>  Numer konta bankowego na które zostanie
                                                     przelane pobranie
COD.status                         Enum<COD_STATUS>  Sposób zwrotu pobrania. Lista kodów w tabeli
COD.return_details                 Array             Sposób zwrotu pobrania .
                                                     Status pobrania z tabeli COD_STATUS
COD.return_details.reason          Enum<COD_OPERATI  Tablica operacji na kwocie pobrania (wyplaty,
COD.return_details.invoice_number  ON_REASON>        kompensaty itp)
                                   Array<string>     Typ operacji z tabeli COD_OPERATION_REASON

COD.return_details.description     String            Numery powizanych faktur jeli operacja
                                                     dotyczyla faktury
COD.return_details.document_numbe String             Opis operacji
                                                     Numer dokumentu powizanego z operacj np.
r                                                    numer kompensaty jeli operacja zostal
                                                     wykonana kompensata lub numer wyplaty jeli
COD.return_details.date            DateTime          operacja dotyczy wyplaty do klienta
COD.return_details.amount          Float             Data operacji
pickup                                               Kwota operacji
pickup.pickupdate                  String
pickup.pickuptimefrom              String            data podjazdu kuriera
pickup.pickuptimeto                String            godzina "od" oczekiwania na podjazd kuriera
pickup.nocourierorder              Bool              godzina "do" oczekiwania na podjazd kuriera
packs                                                Samodzielne zamówienie kuriera przez telefon
packs[].length                     Int               Tablica z paczkami
packs[].width                      Int               Dlugo paczki
packs[].height                     Int               Szeroko paczki
packs[].weight                     Float             Wysoko paczki
packs[].amount                     Int               Waga paczki
packs[].type                       Enum<PACK_TYPE>   Ilo paczek
                                                     Rodzaj przesylki. Lista dostpnych opcji w tabeli
packs[].price_net                  Float             Typy przesylek PACK_TYPE
packs[].price_gross                Float             Cena netto paczki
courierservice                                       Cena brutto paczki
                                                     Tablica z nazwami uslug dodatkowych dla
                                                     przesylki

                                             33
      items                                 String             Zdeprecjonowane ­ prosimy uywa atrybutu
      items[].description                                      items
                                                               Tablica ze szczególow wycen zlecenia
                                                               Opis uslugi / paczki

      items[].amount                        Int                Ilo
      items[].price                         Float              Cena jednostkowa netto
      items[].value_nett                    Float              Warto netto
      items[].value_gross                   Float              Warto brutto
      items[].type                                             Typ elementu SERVICE ­ usluga, PACK - paczka
                                            Enum [SERVICE,
      individual_pricing                    PACK]              Dodatkowe informacje o ofercie spedycji
                                                               (widoczne tylko jeli atrybut courier ma
      individual_pricing.offer_sent_date    DateTime           warto INDIVIDUAL_PRICING)
      individual_pricing.offer_valid_date   DateTime           Data wyslania oferty przez dzial spedycji
      individual_pricing.customer_confirme  DateTime           Data wanoci oferty
      d_date                                                   Data zatwierdzenia oferty przez klienta
      individual_pricing.customer_remarks   String
      waybills                                                 Dodatkowe uwagi klienta
      waybills[].number                     String             Tablica z informacjami o listach przewozowych
      waybills[].is_default                 Bool               Numer listu przewozowego
                                                               Czy domylny list przewozowy

W przypadku podania bldnego numeru zamówienia API zwróci odpowied w formacie JSON

{"status":"error","response":"Nie znaleziono zlecenia [123456-1]"}

Struktura kolekcji request metody get_orders dla pobrania listy zamówie w formacie JSON

{
    "authorization": {...},
    "apimethod": "get_orders",
    "data": {
        "packs": true,
        "pagesize": 100,
        "page": 1
    }

}

Struktura kolekcji response metody get_orders dla listy zamówie w formacie JSON. Struktura

danych zamówie identyczna jak dla pojedynczego zamówienia.

{

   "status": "success",

   "response": {

      "totalrows": 100,

      "totalpages": 1,

      "currentpage": 1,

      "pagesize": 100,

      "result": [{

          "number": "123456-1",

          "date": "2021-01-01T13:43:15+0200",

          "description": "Testowa",

          ...

      ]}

   }

}

Opis zwracanych atrybutów

      Atrybut              Typ       Opis

      totalrows            Int       Ilo wszystkich zamówie

      totalpages           Int       Ilo stron

      currentpage          Int       Aktualna strona response

      pagesize             Int       Maksymalna ilo zamówie do pobrania

      result               Array     Tablica z zamówieniami. Struktura danych zamówie identyczna jak dla

                                     pojedynczego zamówienia

                                                      34
Metoda: is_multi_pickup_available ­ Dostpno zbiorczego podjazdu kuriera

Metoda zwraca czy dla zlecenia dostpny jest zbiorcze zamówienie podjazdu

Elementy zapytania metody is_multi_pickup_available posiadaj atrybuty:

Atrybut         Typ                            Opis

senderPostCode  String                         Kod pocztowy nadawcy

shipmentType    Enum<SHIPMENT_TYPE> Rodzaj przesylki z tabeli SHIPMENT_TYPE

courier         String                         Kod kuriera. Kod mona uzyska z danych zwracanych przez metod
                                               available_carriers

packs           Array<ORDER_PACK>              Tablica paczek w zamówieniu. Struktura zostala opisana w tabeli
                                               ORDER_PACK

Elementy zwrócone metody get_courier_point posiadaj nastpujce kolekcje:

Atrybut                                 Typ          Opis

isMultiPickupAvailable                  Bool         Numer zamówienia

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "is_multi_pickup_available",
    "data": {
       "senderPostCode": "63-400",
       "courier": "DPD",
        "packs": [{
            "length": 10,
            "width": 20,
            "height": 30,
            "weight": 5,
            "amount": 1,
            "type": "ST"
        }]
    }

}

Przykladowa odpowied:

{
    "status":"success",
    "response": {
        "isMultiPickupAvailable": true
    }

}

                                               35
Metoda: create_multi_order_pickup ­ Zamówienie zbiorczego podjazdu kuriera

Metoda zamawia zbiorczy odbiór przesylek dla zlece z ustawion opcj pickup.multiPickup na
true podczas tworzenia zlecenia metod create_order.

Aby pobra list zlece oczekujcych na zamówienie zbiorczego podjazdu naley uy metody
get_orders z atrybutem status o wartoci PZ. Przyklad:

{
    "authorization": {...},
    "apimethod": "get_orders",
    "data": {
       "status": "PZ"
    }

}

Elementy zapytania posiadaj atrybuty:

Atrybut         Typ                                  Opis
                                                     Data odbioru przesylek przez kuriera
pickupdate      Date                                 Minimalna godzina odbioru przesylek przez kuriera
                                                     Maksymalna godzina odbioru przesylek przez kuriera
pickuptimefrom  Time                                 Numery zlece

pickuptimeto    Time

orders          Array<String>

Elementy zwrócone posiadaj nastpujce atrybuty:

Atrybut         Typ                                  Opis

success         Array<String>                        Numery zlece, dla których poprawnie udalo si zamówi

                                                     odbiór przez kuriera.

failed          Map<String, String>                  Numery zlece, dla których wystpil bld, gdzie indeks to

                                                     numer zlecenia, a warto to komunikat bldu

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "is_multi_pickup_available",
    "data": {
       "pickupdate": "2024-01-03",
       "pickuptimefrom": "10:00",
        "pickuptimeto": "15:00",
       "orders": ["1234-56", "1234-78"]
    }

}

Przykladowa odpowied:

{
    "status":"success",
    "response": {
        "success": ["1234-56"],
        "failed": {
            "1234-78": "Przykladowy komunikat bldu"
        }
    }

}

                                               36
Metoda: get_addresses ­ Lista adresów z ksiki adresowej
Metoda pozwala na pobranie adresów zapisanych w ksice adresowej,

Elementy zapytania posiadaj atrybuty:

    Atrybut  Typ                        Wymagany          Opis
                                        Nie               Typ adresu. Jeli atrybut zostanie pominity to
    type     Enum<ADDRESS_BOOK_TYPE>                      zwrócone zostan wszystkie adresy z ksiki
                                                          adresowej

Elementy zwrócone posiadaj nastpujce atrybuty:

    Encja ADDRESS_BOOK_ADDRESS

Atrybut      Typ                        Opis

id           String                     ID adresu

name         String                     Nazwa wywietlana na licie w ksice adresowej

company      String                     Nazwa firmy

person       String                     Imi i nazwisko

city         String                     Miejscowo

postcode     String                     Kod pocztowy

street       String                     Nazwa ulicy

housenumber  String                     Numer budynku

flatnumber   String                     Numer mieszkania

email        String                     Adres e-mail

phone        String                     Numer telefonu

country      String                     Kod ISO alpha-2 kraju np. PL

province     String                     Dwuliterowy kod stanu jeli kraj posiada (np. dla USA lub Kanady)

type         Enum<ADDRESS_BOOK_TYPE> Typ adresu SENDER ­ adres nadawcy, RECIPIENT ­ adres odbiorcy

default      Bool                       Czy domylny adres danego typu

is_cover_address Bool                   Czy jest to adres dla uslugi ,,Inny adres nadawcy na etykiecie"

Enum ADDRESS_BOOK_TYPE

Kod          Opis

SENDER       Adres nadawcy

RECIPIENT Adres odbiorcy

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "get_addresses",
    "data": {}

}

Przykladowa odpowied:

{
    "status":"success",
    "response": [{
        "id": "ASGB6",
        "name": "Domylny",
        "company": "",
        "person": "Jan Kowalski",
        "city": "Ostrów wielkopolski",
        "postcode": "63-400",

                                        37
        "email": "test@example.com",
        "phone": "123456789",
        "country": "PL",
        "province": "",
        "type": "SENDER",
        "default": true,
        "is_cover_address": false,
        "street": "Kaliska",
        "housenumber": "35A",
        "flatnumber": ""
    }, ...]
}

                                                                          38
Metoda: save_address ­ Zapis adresów do ksiki adresowej
Metoda pozwala na zapis nowego lub zmian istniejcego adresu w ksice adresowej.

Elementy zapytania posiadaj atrybuty:

Atrybut  Typ                            Wymagany        Opis
                                        TAK             Dane adresu do zapisania. Jeli znajdzie si w
data     ADDRESS_BOOK_ADDRESS
                                                        nich atrybut id to adres o tym ID zostanie
                                                        zmodyfikowany. W przeciwnym wypadku dodany
                                                        zostanie nowy adres.
                                                        Jeli w danych adresu zostanie ustawiony

                                                        atrybut default na true to adres zostanie
                                                        ustawiony jako domylny.

Elementy zwrócone posiadaj nastpujce atrybuty:
Zwrócona zostanie struktura encji ADDRESS_BOOK_ADDRESS

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "save_address",
    "data": {
        "id": "ASGB6",
        "name": "Domylny",
        "company": "",
        "person": "Jan Kowalski",
        "city": "Ostrów wielkopolski",
        "postcode": "63-400",
        "email": "test@example.com",
        "phone": "123456789",
        "country": "PL",
        "province": "",
        "type": "SENDER",
        "default": true,
        "is_cover_address": false,
        "street": "Kaliska",
        "housenumber": "35A",
        "flatnumber": ""
    }

}

Przykladowa odpowied:

{
    "status":"success",
    "response": {
        "id": "ASGB6",
        "name": "Domylny",
        "company": "",
        "person": "Jan Kowalski",
        "city": "Ostrów wielkopolski",
        "postcode": "63-400",
        "email": "test@example.com",
        "phone": "123456789",
        "country": "PL",
        "province": "",
        "type": "SENDER",
        "default": true,
        "is_cover_address": false,
        "street": "Kaliska",
        "housenumber": "35A",
        "flatnumber": ""
    }

}

                                        39
Metoda: delete_address ­ Usuwanie adresów z ksiki adresowej
Metoda pozwala na usunicie adresu w ksice adresowej.

Elementy zapytania posiadaj atrybuty:

Atrybut  Typ                           Wymagany              Opis
                                       TAK                   Typ adresu do usunicia
type     Enum<ADDRESS_BOOK_TYPE>       Tak                   ID adresu do usunicia

id       String

Elementy zwrócone posiadaj nastpujce atrybuty:
Metoda nie zwraca adnych danych. Status success oznacza prawidlowe usunicie adresu.

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "delete_address",
    "data": {
        "id": "ASGB6",
        "type": "SENDER",
    }

}

Przykladowa odpowied:

{
    "status":"success",
    "response": {}

}

                                       40
Metoda: get_bank_accounts ­ Lista kont bankowych do zwrotu pobrania
Metoda pozwala na pobranie listy kont bankowych do zwrotu pobrania

Elementy zapytania posiadaj atrybuty:
Metoda nie przyjmuje adnych parametrów.

Elementy zwrócone posiadaj nastpujce atrybuty:

    Encja BANK_ACCOUNT

Atrybut  Typ                             Opis

id       String                          ID konta

number   String                          Numer konta bankowego IBAN

name     String                          Nazwa do wywietlenia na licie

default  Bool                            Czy domylne

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "get_bank_accounts",
    "data": {}

}

Przykladowa odpowied:

{
    "status":"success",
    "response": [{
        "id": "ASGB6",
        "number": "49124036372427136214491645",
        "name": "Moje konto bankowe",
        "default": true
    }, ...]

}

                                                 41
Metoda: delete_bank_account ­ Usuwanie konta bankowego
Metoda pozwala na usunicie konta bankowego do zwrotu pobrania.

Elementy zapytania posiadaj atrybuty:

Atrybut  Typ                             Wymagany  Opis
                                         Tak       ID konta do usunicia
id       String

Elementy zwrócone posiadaj nastpujce atrybuty:
Metoda nie zwraca adnych danych. Status success oznacza prawidlowe usunicie konta.

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "delete_bank_account",
    "data": {
        "id": "ASGB6"
    }

}

Przykladowa odpowied:

{
    "status":"success",
    "response": {}

}

                                         42
Metoda: save_bank_account ­ Zapisuje konto bankowe do zwrotu pobrania
Metoda pozwala na zapis nowego lub aktualizacj istniejcego konta bankowego do zwrotu pobrania

Elementy zapytania posiadaj atrybuty:

Atrybut  Typ           Wymagany                      Opis

data     BANK_ACCOUNT  TAK                           Dane konta do zapisania. Jeli znajdzie si w nich atrybut id
                                                     to konto o tym ID zostanie zmodyfikowane. W przeciwnym
                                                     wypadku dodane zostanie nowe konto.
                                                     Jeli w danych konta zostanie ustawiony atrybut default
                                                     na true to konto zostanie ustawione jako domylny.

Elementy zwrócone posiadaj nastpujce atrybuty:
Zwrócona zostanie struktura encji BANK_ACCOUNT

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "save_bank_account",
    "data": {
        "number": "49124036372427136214491645",
        "name": "Moje konto bankowe",
        "default": true
    }

}

Przykladowa odpowied:

{
    "status":"success",
    "response": {
        "id": "ASGB6",
        "number": "49124036372427136214491645",
        "name": "Moje konto bankowe",
        "default": true
    }

}

                                                 43
Metoda: get_pack_templates ­ Lista szablonów paczek
Metoda pozwala na pobranie listy zdefiniowanych szablonów paczek

Elementy zapytania posiadaj atrybuty:
Metoda nie przyjmuje adnych parametrów.

Elementy zwrócone posiadaj nastpujce atrybuty:

    Encja PACK_TEMPLATE

Atrybut    Typ                           Opis

id         String                        ID szablonu

name       String                        Nazwa wywietlana na licie

shipmenttype Enum<SHIPMENT_TYPE>         Typ przesylki z tabeli SHIPMENT_TYPE

length     Int                           Dlugo w cm

width      Int                           Szeroko w cm

height     Int                           Wysoko w cm

weight     Float                         Waga w kg

COD        Float                         Warto pobrania. Jeli 0 to bez pobrania.

insurance  Float                         Warto ubezpieczenia. Jeli 0 to bez ubezpieczenia.

description String                       Domylny opis przesylki

type       Enum<PACK_TYPE>               Typ paczki z tabeli PACK_TYPE. Domylnie ST

courier    String | NULL                 ID kuriera. Dostpne ID kurierów mona pobrac metod
                                         available_carriers

services   Array<ADDITIONAL_SERVICE>     Tablica domylnie wlczonych uslug dodatkowych

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "get_bank_accounts",
    "data": {}

}

Przykladowa odpowied:

{
    "status":"success",
    "response": [{
        "id": "ASGB6",
        "name": "BOX",
        "shipmenttype": "box",
        "length": 10,
        "width": 12,
        "height": 8,
        "weight": 1,
        "COD": 0,
        "insurance": 0,
        "description": "Test Box",
        "type": "ST",
        "courier": "DHL",
         "services": [
              "LABELLESS",
              "ROD"
          ]
    }, ...]

}

                                                                          44
Metoda: save_pack_template ­ Zapisuje szablon paczek
Metoda pozwala na zapis nowego lub aktualizacj istniejcego szablonu paczek

Elementy zapytania posiadaj atrybuty:

Atrybut  Typ            Wymagany                 Opis
                                                 Dane szablonu do zapisania. Jeli znajdzie si w nich atrybut
data     PACK_TEMPLATE  TAK                      id to szablon o tym ID zostanie zmodyfikowany. W
                                                 przeciwnym wypadku dodany zostanie nowy szablon.

Elementy zwrócone posiadaj nastpujce atrybuty:
Zwrócona zostanie struktura encji PACK_TEMPLATE

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "save_bank_account",
    "data": {
        "name": "BOX",
        "shipmenttype": "box",
        "length": 10,
        "width": 12,
        "height": 8,
        "weight": 1,
        "COD": 0,
        "insurance": 0,
        "description": "Test Box",
        "type": "ST",
         "courier": "DHL",
         "services": [
            "LABELLESS",
            "ROD"
         ]
    }

}

Przykladowa odpowied:

{
    "status":"success",
    "response": {
        "id": "ASGB6",
        "name": "BOX",
        "shipmenttype": "box",
        "length": 10,
        "width": 12,
        "height": 8,
        "weight": 1,
        "COD": 0,
        "insurance": 0,
        "description": "Test Box",
        "type": "ST",
         "courier": "DHL",
         "services": [
            "LABELLESS",
            "ROD"
         ]
    }

}

                                       45
Metoda: delete_pack_template ­ Usuwanie szablonu paczek
Metoda pozwala na usunicie szablonu paczek.

Elementy zapytania posiadaj atrybuty:

Atrybut  Typ                              Wymagany       Opis
                                          Tak            ID szablonu do usunicia
id       String

Elementy zwrócone posiadaj nastpujce atrybuty:
Metoda nie zwraca adnych danych. Status success oznacza prawidlowe usunicie szablonu.

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "delete_pack_template",
    "data": {
        "id": "ASGB6"
    }

}

Przykladowa odpowied:

{
    "status":"success",
    "response": {}

}

                                          46
Metoda: find_city ­ Wyszukiwanie miejscowoci po kodzie pocztowym
Metoda pozwala na wyszukanie nazwy miejscowoci po kodzie pocztowym

Elementy zapytania posiadaj atrybuty:

Atrybut   Typ                             Opis
                                          Kod pocztowy
postcode  String

Elementy zwrócone posiadaj nastpujce atrybuty:

Atrybut   Typ                             Opis

name      String                          Nazwa miejscowoci

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "find_city",
    "data": {
        "postcode": "63-400"
    }

}

Przykladowa odpowied:

{
    "status":"success",
    "response": [
        {"name": "Franklinów"},
        {"name": "Lamki"},
        {"name": "Ostrów Wielkopolski"},
        {"name": "Sadowie"},
        ...
    ]

}

                                                47
Metoda: get_map_token ­ Wygenerowanie tokenu mapy punktów
Metoda pozwala na wygenerowanie tokenu dostpowego dla mapy punktów kurierskich.

Wygenerowany token wany jest 4 godziny. Po tym czasie naley wygenerowa nowy.

Elementy zapytania posiadaj atrybuty:
Metoda nie przyjmuje adnych parametrów.

Elementy zwrócone posiadaj nastpujce atrybuty:

Atrybut  Typ                             Opis

token    String                          Token dostpowy w formacie JWT

Przykladowe zapytanie:

{
    "authorization": {...},
    "apimethod": "get_map_token",
    "data": {}

}

Przykladowa odpowied:

{
    "status":"success",
    "response": {
        "token": "eyJ0eXAiOiUzI1NiJ9.eyJpc3MiOiJwNCwibk1NDMxfQ.VieqSFy5wAC04eNF61bmvvyWg"
    }

}

                                               48
Wywietlenie mapy punktów kurierskich i paczkomatów

Widget mapy pozwala w prosty sposób doda moliwo wyboru punktu kurierskiego lub paczkomatu
z mapy.

Najpierw naley zaladowa zalenoci:

Naley doda style CSS (najlepiej do sekcji <HEAD> dokumentu HTML:
<link rel="stylesheet" href="https://maps.polkurier.pl/assets/dist/points-
map.css" />

Oraz zaladowa glówny skrypt dodajcy obslug widgetu mapy (mona to zrobi w sekcji <head> lub
<body> dokumentu HTML):
<script src="https://maps.polkurier.pl/assets/dist/points-
map.bundle.js"></script>

Przyklad inicjalizacji i uycia mapy w JavaScript:
const map = new POLKURIER.PointsMap({

         token: 'eyJ0eXAiOiUzI1NiJ9.eyJpc3MiOieqSFy5wAC04eNF61bmvvyWg',
         // Pozostale parametry konfiguracyjne opisane zostaly
         // w tabeli Opcje konfiguracji mapy
});
map.showMapDialog(); // Otwarcie okna modalnego z map
map.onConfirm(function (point) {
         // Dzialania po wybraniu punktu, np. ustawienie ID punktu w formularzu
         map.closeMapDialog(); // Zamknicie mapy
});

Konstruktor obiektu POLKURIER.PointsMap przyjmuje jako argument obiekt konfiguracyjny z nastpujcymi
parametrami:

Opcje konfiguracji mapy

Parametr     Typ                 Wyma Warto    Opis
                                 gany domylna

token        String              TAK `'        Token Dostpowy, który naley pobra za pomoc
                                               metody get_map_token

searchQuery  String              NIE `'        Domylna fraza wyszukiwania. Jeli bdzie to ID
                                               punktu, to mapa zostanie wycentrowana na
                                               wskazanym punkcie.

functions    Array<COURIER_POI NIE  undefined  Funkcje, które musi spelni punkt aby wywietli go
             NT_FUNCTION>                      na mapie. Funkcje opisane zostaly w tabeli
                                               COURIER_POINT_FUNCTION

providers    Array<String>       NIE undefined Tablica kodów kurierów do wywietlenia na licie.
                                                                 Kurierów pobra mona za pomoc moetody
                                                                 available_carriers. Jeli warto ta jest undefined
                                                                 lub null to wywietla wszystkich kurierów.

selectedProviders Array<String>  NIE undefined Tablica kodów kurierów, którzy s domylnie
                                                                 zaznaczeni. Kurierów pobra mona za pomoc
                                                                 moetody available_carriers. Jeli warto ta jest
                                                                 undefined lub null to zaznacza wszystkich.

latitude     Float               NIE 52.2252606 Domylna szeroko geograficzna, na której
                                                                 wycentruje si mapa po otwarciu.

                                         49
longitude         Float                NIE 20.9986249 Domylna dlugo geograficzna, na której wycentruje
                                                                       si mapa po otwarciu.

zoom              Float                NIE 13           Domylne przyblienie mapy.
showSelectButton  Bool
                                       NIE true         Czy wywietli przycisk ,,Wybierz" po klikniciu w
                                                        punkt na mapie. Jeli false to mapa bdzie w trybie
                                                        tylko do odczytu

showList          Bool                 NIE true         Czy pokaza list punków obok mapy
showSearchInput   Bool
                                       NIE true         Czy pokaza pole wyszukiwania

Instancja obiektu mapy posiada nastpujce metody:

Metody mapy       Argumenty                             Dane zwracane                Opis
Metoda

showMapView       HTMLElement targetElement                                          Wywietla mapk we
                                                                                     wskazanym elemencie
                                                                                     HTML

showMapDialog                                                                        Otwiera okno z mapk

closeMapDialog                                                                       Zamyka okno z mapk

on                String Nazwa eventu                                                Dodaje nasluch eventów.
                                                                                     Dostpne zdarzenia
                  Function Funkcja obslugujca event                                  zostaly opisane w tabeli
                                                                                     Zdarzenia poniej

onConfirm         Function Funkcja obslugujca event                                  Callback po wybraniu
                                                                                     punktu

onSelectPoint     Function Funkcja obslugujca event                                  Callback po zaznaczeniu
                                                                                     punktu na mapie lub
                                                                                     licie

getSelectedPoint                                        Object<COURIER_POINT> Zwraca wybrany punkt
                                                        | null

setSearchQuery    String searchQuery                                                 Ustawia fraz
                                                                                     wyszukiwania

setAvailableProviders Array<string> availableProviders                               Ustawia dostpnych
                                                                                     przewoników

setSelectedProviders Array<String> selectedProviders                                 Ustawia wybranych
                                                                                     przewoników

setMapPosition    Float Szeroko geograficzna                                         Ustawia pozycj mapy
                  Float Dlugo geograficzna
                  Float Zblienie mapy

getMapPosition                                          Array<Float, Float,          Zwraca pozycj rodka
                                                                                     mapy
                                                        Float> Szeroko
                                                        geograficzna, Dlugo
                                                        geograficzna, Zblienie mapy

getPointFunction                                        Array<String>                Zwraca wymagane
                                                                                     funkcje punktu

setPointFunctionsFilter Array<string>                                                Ustawia wymagane
                                                                                     funkcje punktu

getProviderName                                         String                       Zwraca nazw
                                                                                     wybranego przewonika

destroy                                                                              Niszczy widok mapy

                                                  50
Obiekt mapy posiada nastpujce metody statyczne:

Metody STATYCZNE mapy

Metoda                 Argumenty                     Dane zwracane           Opis
                                                     Promise<string|
getCourierMapProvider String ID przewonika           undefined>              Zwraca ID providera dla
                                                                             wybranego przewonika.
getAvailableProviders                                Promise<Array<string>>  Jeli dany przewonik nie
                                                                             obsluguje punktów to
                                                                             metoda zwróci warto
                                                                             undefined

                                                                             Zwraca tablic
                                                                             wszystkich
                                                                             dostpnych
                                                                             providerów.

Instancja mapy emituje zdarzenia, do których mona doda wlasne funkcje obslugujce za pomoc metody
on(...) (Opis w tabeli ,,Metody mapy")

map.on('select:point', function (point) {
         // ...

});

Zdarzenia              Argumenty                     Opis
Nazwa
dialog:open                                          Otwarcie okna z map
dialog:closed
confirm:point                                        Zamknicie okna z map

select:point           Object<COURIER_POINT> |       Zatwierdzenie wybrania punktu (Kliknicie
                       null                          ,,Wybierz")
input:searchQuery
                       Object<COURIER_POINT> |       Zaznaczeniu punktu na mapie lub licie
                       null

                       InputEvent Zdarzenie JS po wpisaniu Wpisanie frazy wyszukiwania
                       tekstu

                                                 51
Definicje

Rodzaj przesylek SHIPMENT_TYPE

Nazwa                       Opis
envelope                    koperty
box                         paczki
palette                     palety

Typy przesylek PACK_TYPE    Opis
                            Standardowa
       Nazwa                Niestandardowa
       ST                   Pól paleta
       NST                  Paleta przemyslowa
       PPAL                 Dluyca
       PAL
       DLU

Typ zwrotu pobrania codtype, COD_TYPE

Nazwa                       Opis
S                           Zwrot pobrania od 5 do 7 dni roboczych w zalenoci od przewonika
1D                          Zwrot pobrania w 1 dzie roboczy od daty dostarczenia przesylki
4D                          Zwrot pobrania w 4 dni robocze od daty dostarczenia przesylki
16D                         Zwrot w 16 dni robocze od daty dostarczenia przesylki

Sposób zwrotu pobrania return_cod

Nazwa                       Opis
BA                          Przelew na konto bankowe
PO                          Przekaz pocztowy na adres nadawcy
MB                          Pobranie przekazane do skarbonki

Status zlecenia ORDER_STATUS

Lista statusów

Kod        Nazwa                     Opis
                                     Zlecenie zostalo prawidlowo zapisane i oczekuje na platno
O          Oczekuje                  Zlecenie zostalo prawidlowo zapisane. Wygenerowano list przewozowy.
                                     Przesylka oczekuje na odbiór przez kuriera
P          Potwierdzone              Przesylka anulowana
                                     Przesylka odebrana od nadawcy przez kuriera i jest w drodze do adresata
A          Anulowane                 Przesylka dotarla do adresata
                                     Odbiorca odmówil odebrania przesylki która zostanie zwrócona nadawcy.
WP         W przewozie               Status informuje e pojawily si problemy z dostarczeniem przesylki. W
                                     przypadku wystpienia tego statusu zalecamy kontakt z BOK w celu szybkiego
D          Dostarczona               wyjanienia z przewonikiem
                                     Zamówienie z podjazdem zbiorczym. Kod uywany wylcznie w atrybucie
Z          Zwrot do nadawcy
                                     status metody get_orders w celu wyszukania zlece. Nie wystpuje jako
W          Wyjtek                    samodzielny status zlecenia.

PZ         Podjazd zbiorczy

Status pobrania COD_STATUS

Kod                  Nazwa             Opis
WAITING              Oczekuje          Przesylka oczekuje na nadanie

                                                52
IN_TRANSIT       W przewozie  Przesylka jest w przewozie
MONEY_BOX        W skarbonce  Kwota pobrania zostala dodana do salda skarbonki
PAYMENT_PENDING  Do wyplaty   Kwota pobrania zostala zlecona do wyplaty
COMPENSATION     Kompensata   Wykonana zostala kompensata
PAID             Wyplacone    Kwota pobrania zostala wyplacona
SETTLED          Rozliczone   Kwota pobrania zostal rozliczona

Status operacji na pobraniu COD_OPERATION_REASON

Kod                           Opis
COMPENSATION                  Kompensata
CUSTOMER_INVOICE_PAYMENT      Platno za faktur
CUSTOMER_PREPAID_PAYMENT      Doladowanie przedplaty

CUSTOMER_MONEY_BOX_FEE        Oplata manipulacyjna za wyplat ze skarbonki
CUSTOMER_PAID                 Wyplata do klienta

Uslugi dodatkowe ADDITIONAL_SERVICE               Opis
                                                  Dokumenty zwrotne.
       Nazwa                                      Podjazd kuriera z wydrukowanym listem przewozowym.
       ROD                                        Dostawa weekendowa.
       COURIER_WITH_LABEL                         Powiadomienie SMS o nadaniu przesylki
       WEEK_COLLECTION                            Powiadomienie SMS o nadaniu przesylki z wlasn nazw
       SMS_NOTIFICATION_RECIPIENT                 Nadanie bez etykiety
       SMS_NOTIFICATION_RECIPIENT_WITH_NAME       Ostronie
       LABELLESS                                  Dorczenie do rk wlasnych
       HANDLE_WITH_CARE                           Dodatkowe sprawdzenie zawartoci
       DOSTAWA_DO_RAK_WLASNYCH                    Awizacja telefoniczne przed dorczeniem
       CHECK_CONTENT                              Inny adres nadawcy na etykiecie
       PHONE_NOTIFICATION_RECIPIENT               Opony
       COVER_ADDRESS_SENDER                       Wniesienie przesylki
       TIRES                                      Dorczenie w sobot
       BRINGING_DELIVERED_PARCEL                  Awizacja telefoniczna odbioru
       SATURDAY_DELIVERY                          Dostawa w okrelonych godzinach
       PHONE_NOTIFICATION_COLLECTION              Dorczenie do rk wlasnych
       DELIVERY_TO_TIME
       HAND_DELIVERY

                                                  53
