Upload
vukien
View
400
Download
12
Embed Size (px)
Citation preview
Niniejszy dokument jest własnością firmy INITTEC sp. z o.o. Zabrania się zmieniania
treści bez zgody autora.
Paczkomaty API XML
DOCUMENT ID:
D-ST-12-3-1.6
D – INFORMACJA PUBLICZNA
Strona 2 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Spis treści
Wersja dokumentu i wersja API ................................................................................. 4
1 Założenia wstępne ................................................................................................ 7
2 Konta testowe ...................................................................................................... 7
3 Sugerowany sposób integracji w systemie sprzedażowym klienta .............................. 8
4 Spis funkcji dostępnych dla użytkownika ............................................................... 10
4.1 http://api.paczkomaty.pl/?do=listmachines_xml ............................................... 10
4.2 http://api.paczkomaty.pl/?do=listmachines_csv ................................................ 11
4.3 http://api.paczkomaty.pl/?do=findnearestmachines .......................................... 11
4.4 http://api.paczkomaty.pl/?do=findnearestmachines_csv .................................... 12
4.5 http://api.paczkomaty.pl/?do=findmachinebyname ........................................... 13
4.6 http://api.paczkomaty.pl/?do=pricelist............................................................. 14
4.7 http://api.paczkomaty.pl/?do=getpackstatus .................................................... 16
4.8 http://api.paczkomaty.pl/?do=findcustomer ..................................................... 17
4.9 https://api.paczkomaty.pl/?do=createdeliverypacks .......................................... 18
4.10 https://api.paczkomaty.pl/?do=createdeliveryletters ...................................... 23
4.11 https://api.paczkomaty.pl/?do=getsticker ..................................................... 25
4.12 https://api.paczkomaty.pl/?do=setcustomerref ............................................. 26
4.13 https://api.paczkomaty.pl/?do=getpacksbysender ......................................... 27
4.14 https://api.paczkomaty.pl/?do=cancelpack ................................................... 28
4.15 https://api.paczkomaty.pl/?do=change_packsize ........................................... 29
4.16 https://api.paczkomaty.pl/?do=getconfirmprintout ........................................ 30
4.17 https://api.paczkomaty.pl/?do=getcodreport ................................................ 30
4.18 https://api.paczkomaty.pl/?do=payforpack ................................................... 31
Strona 3 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
4.19 https://api.paczkomaty.pl/?do=createdispatchpoint ....................................... 32
4.20 https://api.paczkomaty.pl/?do=getdispatchpoints .......................................... 33
4.21 https://api.paczkomaty.pl/?do=updatedispatchpoint ...................................... 34
4.22 https://api.paczkomaty.pl/?do=deletedispatchpoint ....................................... 35
4.23 https://api.paczkomaty.pl/?do=createdispatchorder....................................... 36
4.24 https://api.paczkomaty.pl/?do=getdispatchorders ......................................... 37
4.25 https://api.paczkomaty.pl/?do=canceldispatchorder ...................................... 38
4.26 https://api.paczkomaty.pl/?do=getdispatchorderprintout ................................ 40
4.27 http://api.paczkomaty.pl/?do=listsendingpoints_xml...................................... 40
4.28 http://api.paczkomaty.pl/?do=listsendingpoints_xml...................................... 41
Strona 4 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Wersja dokumentu i wersja API
HISTORIA WERSJI
DOKUMENTU
Nr
wersji
Data Sprawdził /
Zatwierdził
Zmiany
1.0 15-06-2009 Marcin Welner Utworzenie dokumentu
1.1 14-09-2012 Dział Dokumentacji
IT
Layout
1.2 23.09.2014 Zespół
Dokumentacji i
Procesów
Layout, nowy numer ID
1.3 11.12.2014 Tomasz Nowak-
Bańdura / Zespół
Dokumentacji i
Procesów
Aktualizacja pkt. 5.24
1.4 03.02.2014 Zespół
Dokumentacji i
Procesów/
Przemysław Ciąćka
Aktualizacja pkt. 4 i 5.9
1.5 20.03.2015 Zespół
Dokumentacji i
Procesów/Piotr
Delkowski
Dodanie pkt. 4.26
1.6 10.11.2015 Zespół
Dokumentacji i
Procesów/Aneta
Banaś
Layout, aktualizacja pkt. 4.9,
4.23.
Strona 5 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
HISTORIA WERSJI API
Nr
wersji
Data Sprawdził /
Zatwierdził
Zmiany
2.0 28-08-2011 Marek Surma Zrezygnowano z konieczności
rejestracji klienta. Poprawki
błędów.
2.0.1 19-09-2011 Marek Surma Wyeliminowano ostrzeżenia oraz
informacje o wykorzystaniu
nieustawionych pól.
2.1.1 08-03-2012 Marek Surma Zmiana struktury cenników.
2.1.2 10-09-2012 Marek Surma Dodano format epl2 etykiety
paczkomatowej.
Dodano funkcjonalność Punktów
Nadawczych.
Dodano funkcjonalność Zlecenia
Zamówienia Kuriera.
2.1.3 28-09-2012 Marek Surma Dodano pole Nazwy Punktu
Nadawczego do metody
createdeliverypacks.
2.1.5 14-05-2013 Marek Surma Dodano funkcjonalność
generowania potwierdzenie
odbioru paczek z Punktu
Nadawczego.
Strona 6 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
2.1.6 23-07-2013 Marek Surma Dodano pole sposobu płatności
w funkcjach
findenearestmachines oraz
findnearestmachines_csv.
Dodano pole daty zmiany
statusu paczki w funkcji
getpackstatus.
2.1.7 10-04-2014 Marek Surma Dodano możliwość pobierania
etykiet dla kilku paczek w
jednym żądaniu.
2.1.8 03-02-2015 Marek Surma Dodano możliwość tworzenia
Allegro
Paczkomaty InPost oraz Allegro
Polecony InPost za pomocą
funkcji
createdeliverypacks.
2.1.9 20-03-2015 Piotr Delkowski Dodano funkcjonalność
rejestracji w systemie listów
poleconych InPost.
2.1.10 10-11-2015 Aneta Banaś Dodano funkcjonalność
rejestracji w systemie przesyłek
kurierskich Allegro, listowania
maszyn wirtualnych (dawnych
oddziałów InPost, punktów
odbioru).Wprowadzono blokadę
określenia paczkomatu
nadawczego dla przesyłek typu
AllegroLetter oraz eCommerce
Polecony.
2.1.11 20-10-2016 Tomasz Kuter Aktualizacja informacji
o kontach testowch pkt 2
Strona 7 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
1 Założenia wstępne
InPost Paczkomaty API XML jest rozwiązaniem umożliwiającym interakcję z systemem
obsługującym usługę Paczkomaty InPost za pomocą standardowych rozwiązań jakimi są
protokół HTTP oraz język XML. Część funkcji oprócz wersji zwracającej dane w postaci XML
dostępna jest również w wersji CSV w celu zmniejszenia ilości danych przesyłanych w
odpowiedzi na zapytanie.
Udostępniany przez protokół HTTP interfejs umożliwia pobranie niezbędnych informacji
o zainstalowanych paczkomatach, wyszukanie paczkomatów najbliższych wybranej
lokalizacji, wysłanie i sprawdzenie statusu przesyłki, założenie i weryfikację konta klienta,
pobranie informacji o obowiązującym cenniku.
Interfejs HTTP dostępny jest pod adresem: http://api.paczkomaty.pl
Dla funkcji wysyłania paczek (createdeliverypacks) i pobierania etykiety (getsticker)
należy stosować połączenie szyfrowane https (https://api.paczkomaty.pl).
Wszystkie przesyłane dane wykorzystują stronę kodową UTF-8.
2 Środowisko testowe
Dla ułatwienia użycia API w integracjach, dostępne jest środowisko testowe umożliwiające
tworzenie przesyłek. Składa się na nie:
a) API, dostępne pod adresem:
https://sandbox-api.paczkomaty.pl
b) Menadżer Paczek, dostępny pod adresem:
https://sandbox-manager.paczkomaty.pl
Do tworzenia przesyłek testowych należy wykorzystać następujące dane:
Login: [email protected]
Pass: WqJevQy*X7
W każdej chwili możliwe jest stworzenie własnego konta poprzez wypełnienie formularza:
https://sandbox-manager.paczkomaty.pl/register
Dotychczasowe konto testowe: [email protected] nie jest dostępne z poziomu
https://api.paczkomaty.pl
Strona 8 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
3 Sugerowany sposób integracji w systemie
sprzedażowym klienta
Sprzedawca winien umieścić logo InPost Paczkomaty InPost w widocznym miejscu na
swojej witrynie. Link do aktualnego logo można pobrać za pomocą funkcji
?do=getparams.
Koszyk/podsumowanie zamówienia – na tym etapie zazwyczaj już wiemy kim jest
nasz klient oraz zazwyczaj znamy jego adres email. Na podstawie emaila poprzez
funkcje ?do=findcustomer możemy zweryfikować czy klient ma już założone konto w
systemie Paczkomaty InPost i pobrać jego paczkomaty preferowane.
Od wersji 2.0 nie ma potrzeby rejestracji klienta. Metoda createdeliverypacks
w momencie wykrycia nieistniejącego konta stworzy je wyłącznie na potrzeby
jednorazowej wysyłki paczki.
Potwierdziliśmy, że klient jest użytkownikiem Paczkomaty InPost – na tym etapie
powinniśmy wyświetlić opcje wysyłki do paczkomatu, cennik (?do=pricelist) oraz
paczkomaty do wyboru.
Prezentację paczkomatów sugerujemy zrealizować w postaci dropdownu (listy
rozwijalnej).
Na pierwszej pozycji powinien znajdować się domyślny paczkomat – to wynik funkcji
?do=find_customer.
Poniżej sugerujemy wypisać 3 najbliższe paczkomaty w pobliżu kodu pocztowego –
jeżeli użytkownik zmieniłby zdanie (?do=findnearestmachines). Poniżej powinna
znajdować się lista wszystkich paczkomatów.
Akceptacja zamówienia, wygenerowanie Paczki
Po zatwierdzeniu zamówienia przez kupującego sprzedawca ma 3 drogi:
- wygenerować paczkę i etykietę samodzielnie w programie Manager Paczek,
- wygenerować przesyłkę poprzez API, a etykietę pobrać w Managerze Paczek
(oddzielnej aplikacji dostępnej pod adresem https://manager.paczkomaty.pl),
- wygenerować przesyłkę i etykiety poprzez API.
Zaznaczyć należy, iż wygenerowanie etykiety jest równoznaczne z przejściem paczki
ze stanu stworzona (created) do gotowa do wysyłki (prepared).
Wygenerowanie etykiety pociąga też za sobą pobranie opłaty za przesyłkę.
Niezależnie od sposobu tworzenia paczek – API czy poprzez Manager Paczek,
sugerujemy pobranie etykiety w momencie skompletowania zamówienia i
przygotowania paczki do wysyłki.
Strona 9 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Po przygotowaniu Paczki system powinien wysłać wiadomość e-mail do kupującego
z informacją o numerze przesyłki w systemie Paczkomaty InPost.
Począwszy od wersji 2.1.4 dostępna jest funkcjonalność nadawania Paczek do
Punktów Odbioru. W systemie działają one analogicznie do zwykłych
Paczkomatów, przy czym fizycznie nie są to maszyny, a Punkty Obsługi
Klienta, Agencje, lub sklepy, punkty handlowo-usługowe. Komunikacja przy
doręczaniu paczki jest w pełni spójna z dostarczaniem przesyłek do maszyn
paczkomatowych. Informacja o doręczeniu przesyłki dostarczana jest
klientom za pomocą wiadomości SMS, a odbiór przesyłki następuje po
przekazanie kodu odbioru paczki.
Począwszy od wersji 2.1.8 dostępna jest funkcjonalność nadawania Paczek
Allegro oraz
Listów Allegro. Aby z niej skorzystać niezbędne jest przekazanie do API
danych umożliwiających identyfikację transakcji Allegro – identyfikatorów
użytkownika oraz transakcji z systemu Allegro. Zmiany techniczne zawarte są
w opisie funkcji createdeliverypacks.
Więcej informacji można znaleźć na stronie http://allegro.paczkomaty.pl
Strona 10 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
4 Spis funkcji dostępnych dla użytkownika
4.1 http://api.paczkomaty.pl/?do=listmachines_xml
Zwraca pełną listę aktywnych paczkomatów
Opis
Funkcja zwraca plik XML zawierający szczegółowe dane o aktywnych Paczkomatach.
Parametry przesyłane metodą GET
paymentavailable – (t/f) – pobierz wyłącznie listę paczkomatów:
- t – obsługujących pobrania,
- f – nieobsługujących pobrań,
pickuppoint – (t/f) – pobierz tylko listę:
- t – Punktów Odbioru,
- f – Paczkomatów.
Domyślnie – dla pustego ciągu zostanie zwrócona pełna lista paczkomatów.
Zwracane wartości
Plik XML o następującej strukturze:
<paczkomaty>
<machine>
<name>nazwa_paczkomatu</name>
<type>typ_paczkomatu</type>
<postcode>kod_pocztowy</postcode>
<province>nazwa_województwa</province>
<street>nazwa_ulicy</street>
<buildingnumber>numer_budynku</buildingnumber>
<town>nazwa_miasta</town>
<latitude>szerokość_geogr</latitude>
<longitude>długość_geogr</longitude>
<paymentavailable>pobranie_dostępne</paymentavailable>
<operatinghours>godziny_dostępności</operatinghours>
<locationdescription>opis_lokalizacji</locationdescription>
<paymentpointdescr>opis_miejsca_uiszczania_opłat</paymentpointdescr>
<partnerid>id_partnera</partnerid>
<paymenttype>typy_obsługiwanych_płatności</paymenttype>
</machine>
(...)
<machine>
(...)
</machine>
</paczkomaty>
Strona 11 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Szerokość i długość geograficzna wyrażone są w stopniach. Pole paymentavailable
przyjmuje wartości t lub f w zależności od tego, czy dana lokalizacja ma możliwość odbioru
paczek za pobraniem.
Pole paymenttype przyjąć może jedną z trzech wartości:
0 – brak możliwości zapłaty za przesyłkę,
1 – możliwość zapłaty za przesyłkę gotówką,
2 – możliwość zapłaty za przesyłkę kartą płatniczą,
3 – możliwość zapłaty za przesyłkę gotówką bądź kartą płatniczą.
4.2 http://api.paczkomaty.pl/?do=listmachines_csv
Zwraca pełną listę aktywnych paczkomatów.
Opis
Funkcja zwraca plik CSV zawierający szczegółowe dane o aktywnych paczkomatach.
Parametry przesyłane metodą GET
paymentavailable – (t/f) – pobierz wyłącznie listę paczkomatów :
- t – obsługujących pobrania
- f – nie obsługujących pobrań
pickuppoint – (t/f) – pobierz tylko listę:
- t – Punktów Odbioru
- f – Paczkomatów
Domyślnie – dla pustego ciągu zostanie zwrócona pełna lista paczkomatów.
Zwracane wartości
Plik CSV rozdzielony znakiem średnika.
nazwa_paczkomatu;nazwa_ulicy;numer_budynku;kod_pocztowy;nazwa_miasta;szerokość_geogra
ficzna;długość_geograficzna;pobranie_dostępne;godziny_dostępności;opis_lokalizacji;op
is_miejsca_uiszczania_opłat;id_partnera;typ_płatności;typ_paczkomatu
Szerokość i długość geograficzna wyrażona są w stopniach. Pobranie przyjmuje wartości t lub
f, w zależności od tego, czy dana lokalizacja ma możliwość odbioru paczek za pobraniem
4.3 http://api.paczkomaty.pl/?do=findnearestmachines
Zwraca informacje o 3 najbliższych paczkomatach.
Opis
Funkcja zwraca plik XML zawierający szczegółowe dane o 3 najbliższych aktywnych
Strona 12 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
paczkomatach. Jako parametr funkcja przyjmuje kod pocztowy miejsca, od którego będą
wyznaczane odległości do paczkomatów.
Parametry przesyłane metodą GET
postcode
- kod pocztowy np. 31-545
limit
Umożliwia ograniczenie wyników zwracanych paczkomatów, minimum 3, maksimum
100.
paymentavailable – (t/f) – pobierz wyłącznie listę paczkomatów :
- t - obsługujących pobrania
- f – nie obsługujących pobrań
Domyślnie – dla pustego ciągu zostanie zwrócona pełna lista paczkomatów.
Zwracane wartości
Plik XML o następującej strukturze:
<paczkomaty>
<machine>
<name>nazwa_paczkomatu</name>
<distance>odległość_do_paczkomatu</distance>
<street>nazwa_ulicy</street>
<buildingnumber>numer_budynku</buildingnumber>
<town>nazwa_miasta</town>
<postcode>kod_pocztowy</postcode>
<paymenttype>typy_obsługiwanych_płatności</paymenttype>
</machine>
(...)
<machine>
(...)
</machine>
</paczkomaty>
Odległość do paczkomatu zwracana jest w kilometrach. Pole paymenttype przyjąć może
jedną z trzech wartości:
0 – brak możliwości zapłaty za przesyłkę
1 – możliwość zapłaty za przesyłkę gotówką
2 – możliwość zapłaty za przesyłkę kartą płatniczą
3 – możliwość zapłaty za przesyłkę gotówką bądź kartą płatniczą
4.4 http://api.paczkomaty.pl/?do=findnearestmachines_c
Strona 13 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
sv
Zwraca informacje o 3 najbliższych paczkomatach.
Opis
Funkcja zwraca plik CSV zawierający szczegółowe dane o 3 najbliższych aktywnych
paczkomatach. Jako parametr funkcja przyjmuje kod pocztowy miejsca, od którego będą
wyznaczane odległości do paczkomatów.
Parametry przesyłane metodą GET
postcode
- kod pocztowy np. 31-545
paymentavailable – (t/f) – pobierz wyłącznie listę paczkomatów :
- t - obsługujących pobrania
- f – nie obsługujących pobrań
Domyślnie – dla pustego ciągu zostanie zwrócona pełna lista paczkomatów.
Zwracane wartości
Plik CSV o następującej strukturze:
nazwa_paczkomatu;adres;kod_pocztowy;odległosć;typy_obsługiwanych_płatności
Odległość do paczkomatu zwracana jest w kilometrach. Pole paymenttype przyjąć może
jedną z trzech wartości:
0 – brak możliwości zapłaty za przesyłkę
1 – możliwość zapłaty za przesyłkę gotówką
2 – możliwość zapłaty za przesyłkę kartą płatniczą
3 – możliwość zapłaty za przesyłkę gotówką bądź kartą płatniczą
4.5 http://api.paczkomaty.pl/?do=findmachinebyname
Opis
Zwraca szczegółowe informacje na temat wybranego paczkomatu.
Parametry przesyłane metodą GET
name
- nazwa paczkomatu
Zwracane wartości
W przypadku powodzenia operacji zwraca plik XML o następującej strukturze:
Strona 14 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
<paczkomaty>
<machine>
<name>nazwa_paczkomatu</name>
<postcode>kod_pocztowy</postcode>
<province>nazwa_województwa</province>
<street>nazwa_ulicy</street>
<buildingnumber>numer_budynku</buildingnumber>
<town>nazwa_miasta</town>
<latitude>szerokość_geogr</latitude>
<longitude>długość_geogr</longitude>
<paymentavailable>pobranie_dostępne</paymentavailable>
</machine>
(...)
<machine>
(...)
</machine>
</paczkomaty>
Szerokość i długość geograficzna wyrażone są w stopniach. Pole paymentavailable
przyjmuje wartości t lub f w zależności od tego, czy dana lokalizacja ma możliwość odbioru
paczek za pobraniem.
W przypadku wystąpienia błędu (np. niepoprawna nazwa paczkomatu) zwraca plik XML
o następującej strukturze:
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.6 http://api.paczkomaty.pl/?do=pricelist
Zwraca standardowy cennik przesyłek.
Opis
Funkcja zwraca plik XML zawierający informacje o cenach przesyłek o rozmiarach A, B i C oraz
o dodatkowym koszcie w przypadku przesyłki za pobraniem.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
Przekazanie pustych wartości parametrów email oraz password spowoduje pobranie cennika
domyślnego.
Strona 15 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Zwracane wartości
Plik XML o następującej strukturze:
<paczkomaty>
<on_delivery_payment>minimalny_koszt_pobrania</on_delivery_payment>
<on_delivery_percentage>procent_pobrania</on_delivery_percentage>
<on_delivery_limit>maksymalny_koszt_pobrania</on_delivery_limit>
<packtype>
<type>typ_przesyłki</type>
<price>cena_przesyłki</price>
</packtype>
(...)
<packtype>
(...)
</packtype>
<insurance>
<limit>górny_limit_kwoty_ubezpieczenia</limit>
<price>koszt_ubezpieczenia</price>
</insurance>
(...)
<insurance>
(...)
</insurance>
</paczkomaty>
Przykład
<paczkomaty>
<on_delivery_payment>3</on_delivery_payment>
<packtype>
<type>C</type>
<price>11.99</price>
</packtype>
<packtype>
<type>B</type>
<price>8.99</price>
</packtype>
<packtype>
<type>A</type>
<price>6.99</price>
</packtype>
<insurance>
<limit>5000</limit>
<price>1.5</price>
</insurance>
</paczkomaty>
Pole on_delivery_limit zawiera informację o maksymalnym koszcie pobrania,
Strona 16 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Pole on_delivery_percentage zawiera informację o procentowej wartości pobrania
(kwota „dodana” do paczki, gdyby była ona paczką przedpłaconą),
Pole on_delivery_payment zawiera informację o minimalnym koszcie pobrania (jeżeli
wartość on_delivery_percentage konkretnej ceny za pobraniem jest mniejsza od
wartości on_delivery_payment, to różnicą ceny w stosunku do paczki przedpłaconej
będzie wartość on_delivery_payment),
Pola type i price informacją o kosztach przesyłki danego typu –
- A (8 x 38 x 64 cm),
- B (19 x 38 x 64 cm),
- C (41 x 38 x 64 cm).
Pole limit określa górny limit kwoty ubezpieczenia przesyłki dla danej ceny.
W przypadku wystąpienia błędu (np. błąd logowania) zwraca plik XML o następującej
strukturze:
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.7 http://api.paczkomaty.pl/?do=getpackstatus
Opis
Zwraca status przesyłki.
Parametry przesyłane metodą GET
packcode
Kod paczki w systemie Paczkomaty InPost
Zwracane wartości
W przypadku powodzenia operacji zwraca status przesyłki jako plik XML o następującej
strukturze:
<paczkomaty>
<status>status_paczki</status>
<statusDate>data_ostatniej_zmiany_statusu_paczki</statusDate>
</paczkomaty>
Możliwe wartości pola status:
Created - Oczekuje na wysyłkę
Strona 17 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Prepared - Gotowa do wysyłki
Sent - Przesyłka nadana
InTransit - Przesyłka w drodze
Stored - Oczekuje na odbiór
Avizo - Ponowne awizo
CustomerDelivering - Nadawana w paczkomacie
CustomerStored - Umieszczona przez klienta
LabelExpired - Etykieta przeterminowana
Expired - Nie odebrana
Delivered - Dostarczona
RetunedToAgency - Przekazana do oddziału
Cancelled - Anulowana
Claimed - Przyjęto zgłoszenie reklamacyjne
ClaimProcessed - Rozpatrzono zgłoszenie reklamacyjne
W przypadku wystąpienia błędu (np. niepoprawny numer przesyłki) zwraca plik XML o
następującej strukturze:
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.8 http://api.paczkomaty.pl/?do=findcustomer
Opis
Sprawdza czy użytkownik jest zarejestrowany w systemie i zwraca informacje opisujące
użytkownika.
Parametry przesyłane metodą GET
Adres e-mail użytkownika zarejestrowanego w systemie Paczkomaty InPost
Zwracane wartości
W przypadku powodzenia operacji zwraca plik XML opisujący użytkownika.
Obecnie jest to wyłącznie oznaczenie preferowanego paczkomatu oraz paczkomatu
Strona 18 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
alternatywnego, o ile klient je wcześniej wskazał.
Zbiór danych może być rozbudowany w przyszłości. Struktura pliku XML:
<paczkomaty>
<customer>
<email>email_klienta</email>
<preferedBoxMachineName>
nazwa_paczkomatu
</preferedBoxMachineName>
<alternativeBoxMachineName>
nazwa_paczkomatu
</alternativeBoxMachineName>
</customer>
</paczkomaty>
W przypadku wystąpienia błędu (np. brak klienta w systemie) zwraca plik XML o następującej
strukturze:
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.9 https://api.paczkomaty.pl/?do=createdeliverypacks
Rejestruje w systemie paczki do wysłania.
Opis
Funkcja umożliwia utworzenie dowolnej ilości paczek w systemie Paczkomaty. Niemniej w
czasie testów nie należy przekraczać wartości 100. Paczki w czasie ich tworzenia otrzymują
status Created (Oczekuje na wysyłkę), który natychmiast zostaje zmieniany na Prepared
(Gotowa do wysyłki).
W standardowej funkcjonalności (poprzez program Manager Paczek) oznacza to
wygenerowanie i pobranie etykiet adresowych, co jest równoznaczne z naliczeniem opłaty za
przesyłkę.
W przypadku korzystania z API klient powinien utworzyć etykietę sam wg załączonego wzoru
lub pobrać ją poprzez API.
Przesyłki „Allegro”
Począwszy od wersji 2.1.8 dostępna jest w API funkcjonalność nadawania Paczek Allegro oraz
Listów Allegro. Aby z niej skorzystać niezbędne jest przekazanie do API identyfikatorów
sprzedawcy Allegro oraz transakcji z systemu PayU (węzeł allegro struktury XML
przekazywanej w parametrze content). Powyższa para danych umożliwiających
Strona 19 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
jednoznaczna identyfikacje transakcji systemu Allegro oraz weryfikacje nabycia praw do
skorzystania z wysyłki przesyłki objętej ofertą Allegro Paczkomaty InPost bądź Allegro
Polecony InPost.
W przypadku przekazania do systemu identyfikatora transakcji przypisanego do przesyłki
listowej, niezbędne jest wypełnienie danych odbiorcy listu poleconego (węzeł
receiverAddress struktury XML przekazywanej w parametrze content). Te właśnie dane
widoczne będą na etykiecie przesyłki Allegro Polecony InPost.
Wraz z wersją 2.2.3 została wprowadzona nowa usługa: Allegro Kurier InPost. Z poziomu API
jest ona bardzo podobna do przesyłek Allegro Polecony InPost – jest również wysyłana
na adres odbiorcy, a dodatkowo możliwe jest dla niej określenie kwoty pobrania (węzeł
onDeliveryAmount) oraz kwoty ubezpieczenia (węzeł insuranceAmount).
Dla przesyłki Allegro Paczkomaty InPost dane odbiorcy nie są wymagane.
Prawidłowe są następujące punkty wysyłki (węzeł senderBoxMachineName):
zwykłe paczki:
- aktywne Paczkomaty, których listę można pobrać korzystając z endpointu:
http://api.paczkomaty.pl/?do=listmachines_xml
przesyłki Allegro Paczkomaty InPost
- aktywne Paczkomaty, których listę można pobrać korzystając z endpointu:
http://api.paczkomaty.pl/?do=listmachines_xml
- aktywne Punkty Obsługi Klienta, których listę można pobrać korzystając
z endpointu:
http://api.paczkomaty.pl/?do=listmachines_xml&pickuppoint=t
przesyłki Allegro Polecony InPost
- aktywne Punkty Obsługi Klienta, których listę można pobrać korzystając z
endpointu:
- http://api.paczkomaty.pl/?do=listmachines_xml&pickuppoint=t
przesyłki Allegro Kurier InPost
- aktywne Paczkomaty, których listę można pobrać korzystając z endpointu:
http://api.paczkomaty.pl/?do=listmachines_xml
- tzw. przyoddziałowe Punkty Obsługi Klienta, których listę można pobrać
korzystając z endpointu:
http://api.paczkomaty.pl/?do=listsendingpoints_xml&feature=allegrocourier
Pola obowiązkowe, to:
addresseeEmail
senderEmail
phoneNum
boxMachineName (nie dotyczy przesyłek Allegro Polecony InPost oraz Allegro Kurier
InPost)
packType
Strona 20 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
content
Struktura danych XML zawierająca informacje o paczkach, które mają być utworzone
w systemie.
<paczkomaty>
<autoLabels>automatyczne_etykiety</autoLabels>
<selfSend>nadawanie_w_paczkomacie</selfSend>
<pack>
<id>tymczasowy_identyfikator_paczki</id>
<addresseeEmail>adres_email_odbiorcy</addresseeEmail>
<senderEmail>adres_email_nadawcy</senderEmail>
<phoneNum>numer_telefonu_odbiorcy</phoneNum>
<boxMachineName>oznaczenie_paczkomatu</boxMachineName>
<alternativeBoxMachineName>
oznaczenie_alt_paczkomatu
</alternativeBoxMachineName>
<senderBoxMachineName>
oznaczenie_paczkomatu_nadawczego
</senderBoxMachineName>
<packType>typ_paczki</packType>
<insuranceAmount>kwota_ubezpieczenia</insuranceAmount>
<onDeliveryAmount>kwota_pobrania</onDeliveryAmount>
<customerRef>informacja_dodatkowa_drukowana_na_etykiecie</customerRef>
<senderAddress>
<name>imię_nadawcy_na_etykiecie</name>
<surName>nazwisko_nadawcy_na_etykiecie</surName>
<email>adres_email_nadawcy_na_etykiecie</email>
<phoneNum>numer_telefonu_nadawcy_na_etykiecie</phoneNum>
<street>nazwa_ulicy_nadawcy_na_etykiecie</street>
<buildingNo>identyfikator_budynku_nadawcy_na_etykiecie</buildingNo>
<flatNo>indentyfikator_lokalu_nadawcy_na_etykiecie</flatNo>
<town>miasto_nadawcy_na_etykiecie</town>
<zipCode>kod_pocztowy_nadawcy_na_etykiecie</zipCode> 1
<province>województwo_nadawcy_na_etykiecie</province>
</senderAddress>
<dispatchPointName>nazwa_punktu_nadawczego</dispatchPointName>
<allegro> 2
<userId>indetyfikator_użytkownika_w_serwisie_allegro</userId>
<transactionId>
indetyfikator_transakcji_użytkownika_w_serwisie_payu
</transactionId>
1 W przypadku podmiany nadawcy (węzeł senderAddress), wypełnienie pola zipCode nadawcy jest
obowiązkowe. 2 Węzeł niezbędny dla przesyłek transakcji Allegro.
Strona 21 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
</allegro>
<receiverAddress> 3
<name>imię_odbiorcy</name>
<surName>nazwisko_odbiorcy</surName>
<companyName>nawza_firmy_odbiorcy</companyName>
<email>adres_email_odbiorcy</email>
<phoneNum>numer_telefonu_odbiorcy</phoneNum>
<street>nazwa_ulicy_odbiorcy</street>
<buildingNo>identyfikator_budynku_odbiorcy</buildingNo>
<flatNo>indentyfikator_lokalu_odbiorcy</flatNo>
<town>miasto_ odbiorcy</town>
<zipCode>kod_pocztowy_odbiorcy</zipCode> 4
<province>województwo_odbiorcy</province>
</receiverAddress>
</pack>
(...)
<pack>
(...)
</pack>
</paczkomaty>
autoLabels
Parametr określający, czy przesyłki utworzone przez wywołanie funkcji
createdeliverypacks będą miały ustawiony automatycznie status Prepared
(autoLabels równe 1), czy też Created (autoLabels równe 0). Drugi przypadek
oznacza konieczność wygenerowania etykiet dla przesyłek (dopiero wówczas paczki
zostaną przekazane do wysyłki).
selfSend
Parametr określający, czy przesyłki utworzone przez wywołanie funkcji
inpost_send_packs będą nadawane w oddziale (selfSend równe 0) czy bezpośrednio
w paczkomacie (selfSend równe 1).
Od wersji 1.6 dla paczek nadaniowych istnieje możliwość wyboru paczkomatu
nadawczego poprzez przekazanie parametru senderBoxMachineName. W przypadku
gdy parametr ten jest pusty, jako paczkomat nadawczy zostanie wybrany domyślny
paczkomat nadawcy.
Począwszy od wersji 1.8 istnieje możliwość podmiany nadawcy na etykiecie paczki5.
Dane należy podać jako tabelę w polu senderAddress. W przypadku przekazania
pustego parametru, nadawcą paczki na etykiecie będzie nadawca przypisany do konta
3 Węzeł niezbędny jedynie dla przesyłek transakcji Allegro Polecony InPost i Allegro Kurier InPost.
Węzeł receiverAddress wymaga od użytkownika przekazania przynajmniej wartości pary pól name i
surName, lub pola companyName oraz dodatkowo pól street, buildingNo, zipCode i town. 4 W przypadku podmiany nadawcy (węzeł senderAddress), wypełnienie pola zipCode nadawcy jest
obowiązkowe. 5 W przypadku podmiany nadawcy (węzeł senderAddress), wypełnienie pola zipCode nadawcy jest
obowiązkowe.
Strona 22 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
tworzącego przesyłkę.
Dla przesyłek Allegro Paczkomaty InPost można określić pod parametrem
senderBoxMachineName zarówno Paczkomat nadawczy jak i nadawczy POK. Brak
parametru senderBoxMachineName oznaczać będzie, że klient chce nadać przesyłkę
przez swój domyślny Paczkomat.
W wersji 2.2.3 dla usługi Allegro Kurier InPost podanie senderBoxMachineName jest
obowiązkowe jeśli selfSend równe 1. W przypadku niepodania tego parametru,
zostanie zwrócony dla danej przysyłki błąd.
id
Tymczasowy identyfikator paczki (wartość typu int) nadany przez użytkownika API
umożliwiający zidentyfikowanie danych o określonej przesyłce zwróconych przez
funkcję.
Pola obowiązkowe to:
addresseeEmail,
senderEmail,
phoneNum,
boxMachineName,
packType.
Zwracane wartości
Plik XML zawierający informacje o każdej z paczek jakie zostały przekazane do wygenerowania
w systemie. Tablica posiada następującą strukturę:
<paczkomaty>
<pack>
<id>tymczasowy_identyfikator_paczki</id>
<packcode>kod_paczki_nadany_w_systemie</packcode>
<customerdeliveringcode>
kod_do_samodzielnego_nadania_paczki
</customerdeliveringcode>
<error key=”kod_błędu”>opis_błędu_tworzenia_paczki</error>
</pack>
(...)
<pack>
(...)
</pack>
</paczkomaty>
W przypadku poprawnego wygenerowania paczki pole packcode zawiera nadany przez
system kod paczki; w przeciwnym wypadku pole to pozostaje puste, a informacje o błędzie
przekazane są w polach error_key i error_message. Możliwe jest także wystąpienie błędu
ogólnego, niezwiązanego bezpośrednio z procesem tworzenia paczki (np. błąd autoryzacji);
Strona 23 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
zwrócony on zostanie w standardowy sposób (z pominięciem węzła pack).
W przypadku wystąpienia błędu paczki nie będą utworzone, należy wiec skorygować błąd i
przesłać zapytanie ponownie.
4.10 https://api.paczkomaty.pl/?do=createdeliveryletters
Rejestracja w systemie listów poleconych Inpost.
Wraz z wydaniem wersji 2.2.3 został naprawiony błąd polegający na tym, że dla przesyłek E-
commerce Polecony InPost można było określić Paczkomat jako punkt nadawczy, co było
nieprawidłowe.
Przesyłki E-commerce Polecony InPost można nadawać z poziomu API tylko w Punktach
Obsługi Klienta.
Opis
Funkcja umożliwia utworzenie dowolnej ilości listów w systemie Paczkomaty. W czasie testów
nie należy przekraczać wartości 100. Listy w czasie ich tworzenia otrzymują status Created
(Oczekuje na wysyłkę), który natychmiast jest zmieniany na CustomerDelivering (Gotowa).
W standardowej funkcjonalności (poprzez program Manager Paczek) oznacza to
wygenerowanie i pobranie etykiet adresowych, co jest równoznaczne z naliczeniem opłaty za
przesyłkę. W przypadku korzystania z API, klient powinien utworzyć etykietę sam, według
załączonego wzoru lub pobrać ją poprzez API.
W przypadku przekazania do systemu identyfikatora transakcji, przypisanego do przesyłki
listowej, niezbędne jest wypełnienie danych odbiorcy listu poleconego (węzeł
receiverAddress struktury XML przekazywanej w parametrze content). Te właśnie dane
widoczne będą na etykiecie przesyłki Allegro Polecony InPost.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
content
Struktura danych XML zawierająca informacje o paczkach, które mają być utworzone
w systemie.
<letters>
<autoLabels></autoLabels>
<letter>
<id>tymczasowy_identyfikator_paczki</id>
<addresseeEmail>adres_email_odbiorcy</addresseeEmail>
<phoneNum>numer_telefonu_odbiorcy</phoneNum>
<senderEmail>adres_email_nadawcy</senderEmail>
Strona 24 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
<senderBoxMachineName>oznaczenie_punktu_nadawczego</senderBoxMachineName>
<insuranceAmount></insuranceAmount>
<receiverAddress>
<name>imię_odbiorcy</name>
<surName>nazwisko_odbiorcy</surName>
<companyName>firma_odborcy</companyName>
<email>email_odbiorcy</email>
<phoneNum>numer_telefonu_odbiorcy</phoneNum>
<street>nazwa_ulicy_odbiorcy</street>
<buildingNo>identyfikator_budynku_odbiorcy</buildingNo>
<flatNo>identyfikator_lokalu_odbiorcy</flatNo>
<town>miasto__odbiorcy</town>
<zipCode>kod_poczotwy_odbiorcy</zipCode>
<province>województwo_odbiorcy</province>
</receiverAddress>
<senderAddress>
<name>imię_nadawcy_na_etykiecie</name>
<surName>nazwisko_nadawcy_na_etykiecie</surName>
<companyName>firma_nadawcy_na_etykiecie</companyName>
<email>adres_email_nadawcy_na_etykiecie</email>
<phoneNum>numer_telefonu_nadawcy_na_etykiecie</phoneNum>
<street>nazwa_ulicy_nadawcy_na_etykiecie</street>
<buildingNo>identyfikator_budynku_nadawcy_na_etykiecie</buildingNo>
<flatNo>indentyfikator_lokalu_nadawcy_na_etykiecie</flatNo>
<town>miasto_nadawcy_na_etykiecie</town>
<zipCode>kod_pocztowy_nadawcy_na_etykiecie</zipCode>
<province>województwo_nadawcy_na_etykiecie</province>
</senderAddress>
</letter>
</letters>
autoLabels
Parametr określający, czy przesyłki utworzone przez wywołanie funkcji
createdeliveryletters będą miały ustawiony automatycznie status
CustomerDelivering (autoLabels równe 1), czy też Created (autoLabels równe 0).
Drugi przypadek oznacza konieczność wygenerowania etykiet dla przesyłek (dopiero
wówczas paczki zostaną przekazane do wysyłki).
id
Tymczasowy identyfikator paczki (wartość typu int) nadany przez użytkownika API,
umożliwiający zidentyfikowanie danych o określonej przesyłce, zwróconych przez
funkcję.
Pola obowiązkowe to:
id (alfanum)
addresseeEmail (poprawny e-mail)
phoneNum (9 cyfr)
senderEmail (poprawny e-mail)
senderBoxMachineName (istniejący punkt nadawczy. patrz szczegóły wyżej)
receiverAddress
Strona 25 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
o name (co najmniej 2 znaki, max 50)
o surName (co najmniej 2 znaki, max 50)
o street (co najmniej 2 znaki, max 50)
o buildingNo (max 50 znaków),
o town (co najmniej 2 znaki, max 50)
o zipCode (XX-XXX),
Zwracane wartości
Plik XML zawierający informacje o każdej z paczek jakie zostały przekazane do
wygenerowania w systemie. Tablica posiada następującą strukturę:
<letters>
<letter>
<tmpId>tymczasowy_identyfikator_paczki</tmpId>
<parcelCode>kod_paczki_nadany_w_systemie</parcelCode>
<customerDeliveringCode>kod_do_samodzielnego_nadania_paczki</customerDeliveringCode>
</letter>
</letters>
W przypadku poprawnego wygenerowania paczki, pole parcelCode zawiera nadany przez
system kod paczki. W przeciwnym wypadku pole to pozostaje puste, a informacje o błędzie
przekazane są w polach error_key i error_message.
Możliwe jest także wystąpienie błędu ogólnego, niezwiązanego bezpośrednio z procesem
tworzenia paczki (np. błąd autoryzacji); zwrócony on zostanie w standardowy sposób.
W przypadku wystąpienia błędu, paczki nie będą utworzone, należy wiec skorygować błąd i
przesłać zapytanie ponownie.
4.11 https://api.paczkomaty.pl/?do=getsticker
Opis
Zwraca plik etykiety na paczkę w żądanym formacie.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
packcode (lub packcodes6)
Kod paczki w systemie Paczkomaty InPost
6 W przypadku potrzeby przygotowania etykiety dla większej ilości paczek w jednym żądaniu, należy
przesłać je w strukturze tablicy w polu packcodes.
Strona 26 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
labelType – typ etykiety, dostępne typy:
- A4, lub pusty string – etykieta standardowa – do 3 szt. na stronie A4
- A6P – etykieta A6 w orientacji pionowej
labelFormat – format etykiety, dostępne typy:
- Pdf, lub pusty string – etykieta w formacie PDF
- Epl2 – etykieta w formacie EPL2
Zwracane wartości
W przypadku powodzenia operacji zwraca plik z etykietą.
W przypadku wystąpienia błędu (np. niepoprawny numer przesyłki) zwraca plik XML o
następującej strukturze:
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.12 https://api.paczkomaty.pl/?do=setcustomerref
Opis
Przypisuje do wygenerowanej wcześniej paczki dodatkową informację, która zostanie
wydrukowana na etykiecie.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
packcode
Kod paczki w systemie Paczkomaty InPost
customerref
Informacja dodatkowa drukowana na etykiecie
Zwracane wartości
W przypadku powodzenia operacji zwraca plik XML o następującej strukturze:
<paczkomaty>
<status>Set</status>
</paczkomaty>
W przypadku wystąpienia błędu (np. niepoprawny numer przesyłki) zwraca plik XML o
następującej strukturze:
Strona 27 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.13 https://api.paczkomaty.pl/?do=getpacksbysender
Opis
Funkcja umożliwia pobranie szczegółowych informacji o paczkach wygenerowanych przez
określonego nadawcę. Lista paczek może być zawężona do paczek o określonym statusie,
wygenerowanych w określonym zakresie dat. Możliwe jest również odfiltrowanie paczek w
zależności od tego, czy potwierdzenie nadania zostało wydrukowane.
Funkcja umożliwia pobranie listy paczek za okres maksymalnie 60 dni. W przypadku podania
większego zakresu dat zostanie zwrócony błąd.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
status
Status paczki w systemie (niewymagane)
startdate
Data początkowa dla listy (niewymagane) np: 2014-07-22T00:00:00
enddate
Data końcowa dla listy (niewymagane) np: 2014-07-23T00:00:00
is_conf_printed
Czy potwierdzenie nadania zostało wygenerowane (niewymagane)
customerRef
Informacja dodatkowa podana podczas tworzenia paczki (niewymagane)
Zwracane wartości
Plik XML zawierający informacje o każdej z paczek jakie zostały przekazane do wygenerowania
w systemie. Tablica posiada następującą strukturę:
<paczkomaty>
<startdate>data_poczatku_zestastawienia</startdate>
<enddate>data_konca_zestawienia</enddate>
<pack>
<packcode>nr_paczki</packcode>
<packsize>gabaryt_paczki</packsize>
<amountcharged>kwota_pobrana_od_nadawcy_za_paczke</amountcharged>
<calculatedchargeamount>cena_paczki</calculatedchargeamount>
Strona 28 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
<paymentstatus>
status_pobrania
- Completed (Płatność zrealizowana )
- NotApplicable (Płatność niedostępna )
- Pending ( Płatność w trakcie realizacji )
- Required (Płatność wymagana )
</paymentstatus>
<creationdate>data_utworzenia</creationdate>
<labelcreationtime>data_pobrania_etykiety</labelcreationtime>
<customerdeliveringcode>
kod_samodzielnego_nadania
</customerdeliveringcode>
<status>status</status>
<is_conf_printed>potwierdzenie_pobrane</is_conf_printed>
<labelprinted>etykieta_wygenerowana</labelprinted>
<receiveremail>email_odbiorcy</receiveremail>
<ondeliveryamount>kwota_pobrania</ondeliveryamount>
<preferedboxmachinename>
paczkomat_podstawowy
</preferedboxmachinename>
<alternativeboxmachinename>
paczkomat_alternatywny
</alternativeboxmachinename>
<customerRef>informacja_dodatkowa</customerRef>
</pack>
(...)
<pack>
(...)
</pack>
<results>ilosc_zwroconych_rezultatow</results>
<paczkomaty>
W przypadku wystąpienia błędu zwraca plik XML o następującej strukturze:
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.14 https://api.paczkomaty.pl/?do=cancelpack
Opis
Usuwa przesyłkę w statusie Created.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
Strona 29 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
password
Hasło użytkownika API (nadawcy)
packcode
Kod paczki w systemie Paczkomaty InPost
Zwracane wartości
W przypadku powodzenia operacji zwracana jest wartość 1.
W przypadku wystąpienia błędu (np. niepoprawny numer przesyłki) zwraca plik XML o
następującej strukturze:
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.15 https://api.paczkomaty.pl/?do=change_packsize
Opis
Zmienia gabaryt paczki w statusie Created.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
packcode
Kod paczki w systemie Paczkomaty InPost
packsize
Nowy gabaryt (dopuszczalne wartości to ‘A’, ‘B’, ‘C’)
Zwracane wartości
W przypadku powodzenia operacji zwracana jest wartość 1.
W przypadku wystąpienia błędu (np. niepoprawny numer przesyłki) zwraca plik XML o
następującej strukturze:
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
Strona 30 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
4.16 https://api.paczkomaty.pl/?do=getconfirmprintout
Pobiera potwierdzenia nadania paczek do wysłania w formacie PDF.
Opis
Funkcja umożliwia pobranie potwierdzenia nadania wybranych paczek w formacie PDF.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
content
Struktura XML o następującej postaci <paczkomaty>
<pack>
<packcode>numer_paczki</packcode>
</pack>
(...)
<pack>
(...)
</pack>
<paczkomaty>
Zwracane wartości
W przypadku powodzenia operacji zwraca plik PDF z potwierdzeniem.
W przypadku wystąpienia błędu (np. niepoprawny numer przesyłki) zwraca plik XML o
następującej strukturze:
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.17 https://api.paczkomaty.pl/?do=getcodreport
Opis
Funkcja umożliwia pobranie szczegółowych informacji o transakcjach pobraniowych.
Funkcja umożliwia pobranie listy transakcji za okres maksymalnie 60 dni. W przypadku
podania większego zakresu dat zostanie zwrócony błąd.
Parametry przesyłane metodą POST
Strona 31 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
startdate
Data początkowa dla listy
enddate
Data końcowa dla listy
Zwracane wartości
Plik XML zawierający informacje o każdej z paczek jakie zostały przekazane do wygenerowania
w systemie. Tablica posiada następującą strukturę:
<paczkomaty>
<startdate>data_poczatku_zestastawienia</startdate>
<enddate>data_konca_zestawienia</enddate>
<payment>
<amount>kwota_pobrania </amount>
<posdesc>nazwa punktu POS</posdesc>
<packcode>nr_paczki</packcode>
<transactiondate>data_realizacji_transakcji</transactiondate>
</payment>
(...)
<payment>
(...)
</payment>
<results>ilosc_zwroconych_rezultatow</results>
<paczkomaty>
W przypadku wystąpienia błędu zwraca plik XML o następującej strukturze:
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.18 https://api.paczkomaty.pl/?do=payforpack
Opis
Funkcja procesuje paczkę ze statusu Created do Prepared. Implikuje to pobranie opłaty za
paczkę. Wykorzystywana dla implementacji w której klient sam drukuje etykiety
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Strona 32 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Hasło użytkownika API (nadawcy)
packcode
Kod paczki w systemie Paczkomaty InPost
Zwracane wartości
W przypadku powodzenia funkcja zwraca 1.
W przypadku wystąpienia błędu (np. niepoprawny numer przesyłki) zwraca plik XML o
następującej strukturze:
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.19 https://api.paczkomaty.pl/?do=createdispatchpoint
Opis
Funkcja tworzy punkt nadawczy, czyli miejsce zdefiniowane przez klienta z którego kurier
firmy InPost odbierać będzie przesyłki paczkomatowe.
Parametry przesyłane metodą POST.
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
content
Struktura XML o następującej postaci <paczkomaty>
<dispatchPoint>
<name>nazwa_punktu_nadawczego</name>
<postCode>kod_pocztowy_punktu_odbiorczego</postCode>
<street>ulica_punktu_odbiorczego</street>
<town>miasto_punktu_odbiorczego</town>
<building>budynek_punktu_odbiorczego</building>
<flat>lokal_punktu_odbiorczego</flat>
<phoneNumber>numer_telefonu_punktu_odbiorczego</phoneNumber>
<email>email_punktu_odbiorczego</email>
<comments>komentarz_dotyczący_punktu_odbiorczego</comments>
<availabilityHours>
godziny_dostępności_punktu_odbiorczego
</availabilityHours>
</dispatchPoint>
</paczkomaty>
Strona 33 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Zwracane wartości
W przypadku powodzenia funkcja zwraca XML o następującej postaci
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<status>OK</status>
</paczkomaty>
W przypadku wystąpienia błędu zwracany plik XML o następującej strukturze:
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.20 https://api.paczkomaty.pl/?do=getdispatchpoints
Opis
Funkcja zwraca listę punktów nadawczych przypisanych do klienta.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
content
Struktura XML o następującej postaci:
<paczkomaty>
<name>nazwa_punktu_nadawczego</name>
<agencyName>identyfikator_rejonu_spedycji</agencyName>
<dispatchPointStatus>status_punktu_nadawczego</dispatchPointStatus>
</paczkomaty>
Zwracane wartości
W przypadku powodzenia funkcja zwraca XML o następującej postaci
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<count>sumaryczna_ilość_rekordów</count>
<result> // dane punktu nadawczego
<name>nazwa</name >
<dispatchPointStatus>status</dispatchPointStatus >
<postCode>kod_pocztowy</postCode>
<street>ulica</street>
Strona 34 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
<town>miasto</town>
<building>numer_budynku</building>
<flat>numer_lokalu</flat>
<phoneNumber>numer_telefonu</phoneNumber>
<email>adres_email</email>
<comments>komentarz</comments>
<availabilityHours>godziny_otwarcia</availabilityHours>
<customerEmail>address_email_klienta</customerEmail>
</result>
(…)
<result>
(…)
</result>
</paczkomaty>
W przypadku wystąpienia błędu zwracany plik XML o następującej strukturze:
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.21 https://api.paczkomaty.pl/?do=updatedispatchpoint
Opis
Funkcja aktualizuje dane punktu nadawczego.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
content
Struktura XML o następującej postaci <paczkomaty>
<dispatchPointName>
nazwa_aktualizowaneg_punktu_nadawczego
</dispatchPointName>
<dispatchPoint>
<name>nazwa_punktu_nadawczego</name>
<postCode>kod_pocztowy_punktu_odbiorczego</postCode>
<street>ulica_punktu_odbiorczego</street>
<town>miasto_punktu_odbiorczego</town>
<building>budynek_punktu_odbiorczego</building>
<flat>lokal_punktu_odbiorczego</flat>
<phoneNumber>numer_telefonu_punktu_odbiorczego</phoneNumber>
Strona 35 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
<email>email_punktu_odbiorczego</email>
<comments>komentarz_dotyczący_punktu_odbiorczego</comments>
<availabilityHours>
godziny_dostępności_punktu_odbiorczego
</availabilityHours>
</dispatchPoint>
</paczkomaty>
Zwracane wartości
W przypadku powodzenia funkcja zwraca XML o następującej postaci <?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<status>OK</status>
</paczkomaty>
W przypadku wystąpienia błędu zwracany plik XML o następującej strukturze:
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.22 https://api.paczkomaty.pl/?do=deletedispatchpoint
Opis
Funkcja usuwa punkt nadawczy.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
content
Struktura XML o następującej postaci <paczkomaty>
<dispatchPointName>
nazwa_aktualizowaneg_punktu_nadawczego
</dispatchPointName>
<comments>komentarz</comments>
</paczkomaty>
Zwracane wartości
W przypadku powodzenia funkcja zwraca XML o następującej postaci
Strona 36 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<status>OK</status>
</paczkomaty>
W przypadku wystąpienia błędu zwracany plik XML o następującej strukturze:
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.23 https://api.paczkomaty.pl/?do=createdispatchorder
Opis
Funkcja tworzy zlecenie zamówienia kuriera do punktu nadawczego, czyli miejsce
zdefiniowane przez klienta, z którego kurier firmy InPost odebrać ma przesyłki paczkomatowe,
Allegro, polecone i kurierskie.
Wraz z wersją 2.2.3 wprowadzono możliwość składania zamówienia podjazdu kuriera po
przesyłki Allegro Kurier InPost.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
content
Struktura XML o następującej postaci <paczkomaty>
<dispatchPointName>nazwa_punktu_nadawczego</dispatchPointName>
<comment>komentarz</comment>
<parcelCodes>numer_przesyłki</parcelCodes>
(…)
<parcelCodes>numer_przesyłki</parcelCodes>
</paczkomaty>
UWAGA! Ilość węzłów parcelCodes jest dowolna i opcjonalna. W przypadku braku
konkretnych numerów paczek, wykorzystane zostaną wszystkie paczki podanego punktu
odbioru.
Zwracane wartości
W przypadku powodzenia funkcja zwraca XML o następującej postaci
Strona 37 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<dispatchOrderId>identyfikator_zlecenia_zamówienia_kuriera</dispatchOrderId>
</paczkomaty>
W przypadku wystąpienia błędu zwracany plik XML o następującej strukturze:
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.24 https://api.paczkomaty.pl/?do=getdispatchorders
Opis
Funkcja zwraca listę zleceń zamówienia kuriera (zzk) do punktu nadawczego przypisanego do
klienta.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
content
Struktura XML o następującej postaci <paczkomaty>
<dispatchPointName>nazwa_punktu_nadawczego</dispatchPointName>
</paczkomaty>
Zwracane wartości
W przypadku powodzenia funkcja zwraca XML o następującej postaci
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<count>ilość_rekordów</count>
<result>
<dispatchOrderId>identyfikator_zzk</dispatchOrderId>
<dispatchOrderStatus>status_zzk </dispatchOrderStatus>
<dispatchDateFrom>
początek_przedziału_odbioru_przesyłek
</dispatchDateFrom>
<dispatchDateTo>koniec_przedziału_odbioru_przesyłek</dispatchDateTo>
<comment>komentarz</comment>
<packCodes>nr_paczki_przypisanej_do_zzk</packCodes>
Strona 38 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
(…)
<packCodes>nr_paczki_przypisanej_do_zzk</packCodes>
<dispatchPoint> // dane punktu nadawczego
<name>nazwa</name>
<dispatchPointStatus>status</dispatchPointStatus>
<postCode>kod_pocztowy</postCode>
<street>ulica</street>
<town>miasto</town>
<building>numer_budynku</building>
<phoneNumber>numer_telefonu</phoneNumber>
<email>adres_email</email>
<customerEmail>adres_email_klienta</customerEmail>
<agencyName>identyfikator_rejonu_spedycji</agencyName>
</dispatchPoint>
</result>
(…)
<result>
(…)
</result>
</paczkomaty>
UWAGA! Ilość węzłów parcelCodes jest zależna od ilości przesyłek przypisanych do
Zlecenia Zamówienia Kuriera.
Węzły dispatchDateFrom oraz dispatchDateTo występują zależnie od przypisania tych dat
do Zlecenia Zamówienia Kuriera. Są one także zależne od przypisanego statusu – np. status
NEW może tych dat nie posiadać.
Zwracane wartości
W przypadku wystąpienia błędu zwracany plik XML o następującej strukturze:
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.25 https://api.paczkomaty.pl/?do=canceldispatchorder
Opis
Funkcja anuluje zlecenia zamówienia kuriera (zzk).
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Strona 39 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
Hasło użytkownika API (nadawcy)
content
Struktura XML o następującej postaci <paczkomaty>
<dispatchOrderId>identyfikator_zzk</dispatchOrderId>
<comments>komentarz</comments>
<customerEmail>adres_email_zglaszajacego</customerEmail>
</paczkomaty>
Zwracane wartości
W przypadku powodzenia funkcja zwraca XML o następującej postaci
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<status>OK</status>
</paczkomaty>
W przypadku wystąpienia błędu zwracany plik XML o następującej strukturze:
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
Strona 40 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
4.26 https://api.paczkomaty.pl/?do=getdispatchorderprint
out
Opis
Funkcja zwraca dokument w formacie PDF – potwierdzenie odbioru paczek.
Parametry przesyłane metodą POST
Adres e-mail użytkownika API (nadawcy)
password
Hasło użytkownika API (nadawcy)
content
Struktura XML o następującej postaci <paczkomaty>
<dispatchOrderId>identyfikator_zzk</dispatchOrderId>
</paczkomaty>
Zwracane wartości
W przypadku powodzenia funkcja zwraca plik PDF.
W przypadku wystąpienia błędu zwracany plik XML o następującej strukturze:
<?xml version="1.0" encoding="UTF-8"?>
<paczkomaty>
<error key=”kod_błędu”>opis_błędu</error>
</paczkomaty>
4.27 http://api.paczkomaty.pl/?do=listsendingpoints_xml
Metoda wprowadzona wraz z wersją 2.3.3, aktualnie zwracająca listę punktów wysyłki dla
przesyłek Allegro Kurier InPost.
Parametry przesyłane metodą GET:
feature – jest to aktualnie jedyny i wymagany parametr, którego wartością powinien
być ciąg: allegrocourier. W przypadku jego braku lub innej wartości otrzymamy pustą
odpowiedź z kodem HTTP 400 Bad Request.
Zwracane wartości
Plik XML o następującej strukturze:
<?xml version="1.0" encoding="UTF-8"?>
Strona 41 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
<points>
<point>
<name>CC250</name>
<postcode>26-610</postcode>
<town>Radom</town>
<province>Mazowieckie</province>
<street>Romualda Traugutta</street>
<buildingnumber>27</buildingnumber>
<operatinghours>6 - 24</operatinghours>
<latitude>21.1544</latitude>
<longitude>51.3953</longitude>
<locationdescription>Punkt Małpki</locationdescription>
<paymentavailable>t</paymentavailable>
<paymentpointdescr/>
<paymenttype>3</paymenttype>
<partnerid>0</partnerid>
<status>Operating</status>
<type>POK</type>
</point>
</points>
Format ten jest bardzo podobny do tego zwracanego przez metodę do=listmachines_xml.
Szerokość i długość geograficzna wyrażone są w stopniach. Pole paymentavailable
przyjmuje wartości t lub f w zależności od tego, czy dana lokalizacja ma możliwość odbioru
paczek za pobraniem.
Pole paymenttype przyjąć może jedna z trzech wartości:
0 – brak możliwości zapłaty za przesyłkę
1 – możliwość zapłaty za przesyłkę gotówką,
2 – możliwość zapłaty za przesyłkę karta płatnicza
3 – możliwość zapłaty za przesyłkę gotówką bądź karta płatnicza
4.28 http://api.paczkomaty.pl/?do=listsendingpoints_csv
Metoda wprowadzona wraz z wersją 2.3.3, aktualnie zwracająca listę punktów wysyłki dla
przesyłek Allegro Kurier InPost.
Parametry przesyłane metodą GET:
• feature – jest to aktualnie jedyny i wymagany parametr, którego wartością powinien
być ciąg: allegrocourier. W przypadku jego braku lub innej wartości otrzymamy pustą
Strona 42 z 42
TYTUŁ DOKUMENTU: Paczkomaty API XML
ID DOKUMENTU: D-ST-12-3-1.6 KLASYFIKACJA DOKUMENTU: D
odpowiedź z kodem HTTP 400 Bad Request.
Zwracane wartości
Plik CSV rozdzielony znakiem średnika.
Pierwszy wiersz zawiera liczbę będącą sumą kontrolą CRC16 wygenerowaną na podstawie
kolejnych wierszy. Z kolei drugi wiersz zawiera listę nagłówków w języku angielskim. W
trzecim wierszu i w kolejnych znajdują się informacje o punktach nadawczych.
nazwa_paczkomatu;nazwa_ulicy;numer_budynku;kod_pocztowy;nazwa_miasta;szerokość_geogra
ficzna;długość_geograficzna;pobranie_dostępne;godziny_dostępności;opis_lokalizacji;op
is_miejsca_uiszczania_opłat;id_partnera;typ_płatności;typ_punktu_nadawczego