Project-Pro/orderPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6ae91a3fbe92425c4763441746da5d62c2cf0e20
orderPRO/.paul/phases/128-polkurier-shipment-service/polkurier-api-docs.txt
Jacek Pyziak c78ac335ee feat(128): polkurier shipment service + tracking + UI prepare 
PolkurierApiClient rozszerzony do pelnego kontraktu (7 metod):
createShipment/getLabel/getStatus/cancelOrder/getAvailableCarriers/
getInpostParcelMachines/getCourierPoints. Wspolny call() parsuje
envelope {status, response}. Kontrakt zweryfikowany na oficjalnej
dokumentacji PDF v1.11.

PolkurierShipmentService (implements ShipmentProviderInterface)
orchestruje pelen flow: normalizeShipmentType (lowercase), split
ulicy, build recipient/sender/pickup, COD z bank account z
company_settings, extractOrderNumber/extractTrackingNumber
priorytetujace SDK Order entity (number, waybills[0].number).

PolkurierTrackingService (implements ShipmentTrackingInterface)
mapuje statusy O/P/A/WP/D/Z/W przez delivery_status_mappings.

UI panel polkurier w prepare.php z dynamiczna lista uslug z
available_carriers. Bez dedykowanego selektora punktu — operator
wpisuje receiver_point_id w istniejace pole w sekcji Adres odbiorcy.

Migracja 20260514_000115 seedujaca 7 wpisow delivery_status_mappings
z oficjalnej tabeli ORDER_STATUS (O/P/A/WP/D/Z/W).

Live test #114/#115 zakonczony sukcesem po 4 iteracjach
(ReferenceError -> uppercase shipmenttype -> orderno parsing ->
A4/A6 etykieta). Rozmiar etykiety A4/A6 sterowany w panelu klienta
polkurier.pl, NIE przez API.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-14 12:56:36 +02:00

2963 lines
107 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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
Reference in New Issue View Git Blame Copy Permalink