Jak połączyć magazyn z kurierami przez API: zlecenie przesyłki z etykietą ZPL lub PDF oraz numerem śledzenia, a potem odbiór paczek z protokołem przekazania.
Etykieta kurierska to ostatni dokument, który powstaje w magazynie przed wyjazdem paczki. Gdy powstaje w API przewoźnika, WMS dostaje razem z nią numer przesyłki i musi go zapisać przy dokumencie WZ.
Wysyłkę przez firmy kurierskie opisuje strona o wysyłce z magazynu przez kurierów, przykład pliku dla jednego przewoźnika strona o generowaniu listu przewozowego DHL, a stanowisko pakowania strona o pakowaniu i kontroli wysyłki. Ta strona opisuje drogi integracji i to, co potwierdza dokumentacja przewoźników (stan na 6.10.2026). Cennik Studio WMS.net mówi o wymianie z firmami kurierskimi przez pliki Excel lub WebService i nie deklaruje gotowych konektorów do konkretnych kurierów, więc zakres dla danego przewoźnika potwierdza analiza przedwdrożeniowa.
Trzy drogi integracji z kurierem
Plik, API przewoźnika albo agregator.
Wybór drogi zależy od liczby przewoźników i od tego, kto zawiera umowę z kurierem. Plik jest drogą opisaną na stronie o DHL: przy tym przewoźniku dokument WZ generuje plik XML, który program DHL e-Case wczytuje i drukuje z niego list przewozowy. API zastępuje ręczny import wywołaniem wykonywanym w tle.
| Droga | Jak działa | Kiedy pasuje | Konsekwencja |
|---|---|---|---|
| Plik (Excel lub XML) | WMS zapisuje plik z danymi odbiorcy, a program przewoźnika go wczytuje | Przewoźnik ma własną aplikację do listów | Numer listu rejestruje się w Studio Spedycja.net i kojarzy z WZ |
| API przewoźnika (WebService) | Usługa integracji wywołuje API: zlecenie, etykieta, śledzenie | Duży wolumen jednego przewoźnika | Własne uwierzytelnianie i wersje API każdego kuriera |
| Agregator | Jedno API zamiast kilku, a umowy leżą w agregatorze | Wielu przewoźników naraz | Lista kurierów zależy od umów agregatora |
Przepływ przesyłki między WMS a przewoźnikiem
Numer przesyłki wraca do WMS, zanim paczka dostanie etykietę.
Zlecenie przesyłki powstaje po spakowaniu paczki i sprawdzeniu adresu. Odpowiedź przewoźnika niesie numer, a etykietę pobiera się w tym samym albo w osobnym wywołaniu. Dopiero zapis numeru przy WZ zamyka etap magazynowy i pozwala przekazać go dalej, na przykład do platformy sprzedażowej opisanej na stronie o integracji z marketplace.
Co dokumentują przewoźnicy i agregatory
Sześć dostawców, sześć różnych zestawów wywołań.
Tabela zestawia wyłącznie to, co stoi w publicznej dokumentacji. Brakujące komórki nie oznaczają braku funkcji, tylko to, że nie zostały sprawdzone. Kuriera dopisuje się do WMS jako ustawienie z danymi dostępowymi, a agregator zastępuje kilka takich ustawień jednym. Środowisko testowe potwierdza dokumentacja InPost i Furgonetki, więc pierwsze zlecenia da się sprawdzić bez prawdziwych przesyłek.
| Dostawca | Protokół i dostęp | Zlecenie i etykieta | Śledzenie i odbiór |
|---|---|---|---|
| InPost (ShipX) | REST z tokenem Bearer; środowiska: produkcyjne i sandbox | Utworzenie przesyłki, wybór oferty i opłacenie, asynchronicznie; etykiety PDF, EPL lub ZPL, do 100 w żądaniu | Webhooki shipment_confirmed i shipment_status_changed; zlecenie odbioru |
| DHL (DHL24 WebAPI2) | SOAP z opisem WSDL, dane w strukturze AuthData | createShipments; getLabels zwraca list przewozowy i etykietę BLP w PDF lub ZPL | getTrackAndTraceInfo i bookCourier; deleteShipments |
| DPD Polska | Login i hasło API oraz numer Master FID; środowisko produkcyjne lub testowe | Przesyłki i etykiety w PDF (wg dokumentacji modułu DPD) | Zamówienie kuriera i śledzenie; protokół w PDF |
| UPS (Developer Kit) | Poświadczenia z portalu dla deweloperów UPS | Shipping API | Tracking API i Pickup API |
| Furgonetka | REST z OAuth2; serwery: produkcyjny i sandbox | POST /packages/validate i POST /packages; etykieta PDF albo ZPL i EPL | GET /packages/{id}/tracking; protokół w PDF; webhook |
| Apaczka | API v2, podpis HMAC-SHA256 | order_send; waybill zwraca etykietę PDF w base64 | tracking; turn_in (zbiorcze potwierdzenie PDF); pickup_hours |
Etykiety ZPL i PDF
Format etykiety wynika z drukarki na stanowisku pakowania.
ZPL trafia na drukarkę termiczną, a PDF na laserową. DHL24 podaje dla etykiety BLP oba formaty (metoda getLabels), a InPost przy pobieraniu etykiet pozwala wybrać PDF, EPL albo ZPL. Etykieta przewoźnika nie zastępuje etykiety logistycznej GS1, którą opisuje strona o etykiecie logistycznej: pierwsza prowadzi paczkę przez sieć kuriera, druga identyfikuje jednostkę w łańcuchu dostaw. InPost dopuszcza typ etykiety A6 300 dpi tylko w ZPL i tylko dla wybranych usług.
W obecnym przepływie plikowym kolejny krok wykonuje program kuriera: po wczytaniu pliku XML aplikacja DHL e-Case drukuje list przewozowy po podaniu liczby paczek. Przy API ten krok przejmuje usługa integracji, a magazynier dostaje etykietę na drukarce stanowiska.
Statusy i śledzenie przesyłek
Webhook wymaga adresu dostępnego z Internetu, odpytywanie nie.
InPost zgłasza zmiany przez webhook shipment_status_changed, a adres odbiorcy musi odpowiadać kodem HTTP 200 (dokumentacja webhooków). Historię przesyłki zwraca też zapytanie o tracking, przez 45 dni od utworzenia przesyłki, a na środowisku testowym śledzenie jest niedostępne (dokumentacja śledzenia). Apaczka zwraca historię statusów od najnowszego (tracking w API v2).
Usługa integracji z ruchem tylko wychodzącym nie przyjmie webhooka, więc odpytuje o statusy w ustalonych odstępach. Odpytywanie obejmuje paczki, które nie zostały jeszcze doręczone. Statusy przewoźnika odwzorowuje się na własne etapy w WMS, a paczki wracające trafiają do przyjęcia jak każdy zwrot.
Pobranie i protokół odbioru
Cztery zagadnienia, które każdy przewoźnik rozwiązuje inaczej.
Pobranie, protokół, odbiór kuriera i etykiety zwrotne to parametry zlecenia, a nie osobne procesy. Poniżej zestawiono to, co podaje dokumentacja:
- Pobranie (COD) - InPost przyjmuje obiekt cod z kwotą i walutą, a przesyłka pobraniowa musi być ubezpieczona na co najmniej tę wartość; DPD wyróżnia metody dostawy za pobraniem.
- Odbiór kuriera - InPost ma zlecenie odbioru (dispatch order), DHL metodę bookCourier, a Apaczka godziny odbioru pickup_hours.
- Protokół - Furgonetka generuje protokół PDF dla wybranych przewoźników, DPD protokół zbiorczy, a Apaczka turn_in.
- Etykiety zwrotne - InPost ma osobną sekcję etykiet zwrotnych, a moduł DPD potrafi je tworzyć.
Protokół przekazania paczek kurierowi zamyka dokument WZ, a rozliczenie wpłat pobraniowych zwykle zostaje w systemie finansowym.
Błędy adresów i ponowienia
Jeden dokument WZ odpowiada jednej zleconej przesyłce.
Najczęstszy błąd przy integracji z kurierem to drugie zlecenie po utracie odpowiedzi. Tabela pokazuje, jak się przed nim chronić.
| Sytuacja | Skutek | Reakcja integracji |
|---|---|---|
| Błędny lub niepełny adres | Przewoźnik odrzuca zlecenie | Walidacja przed zleceniem (Furgonetka ma POST /packages/validate); WZ zostaje z komunikatem |
| Brak odpowiedzi na zlecenie | Nie wiadomo, czy przesyłka powstała | Zapytanie o przesyłkę po zapisanym identyfikatorze przed ponowieniem |
| Asynchroniczny zakup przesyłki (InPost) | Numer jeszcze nie istnieje | Zapis identyfikatora i odczyt numeru po webhooku lub zapytaniu |
| Pomyłkowo zlecona przesyłka | Dwie przesyłki do jednego WZ | Anulowanie przez API przed odbiorem (DHL deleteShipments, Apaczka cancel_order) |
| Webhook nie dociera | Status nieaktualny | Odpytywanie awaryjne po identyfikatorze przesyłki |
Identyfikator przesyłki zapisuj przed pierwszą próbą pobrania etykiety. Ponowienie zapytania po awarii łącza pobierze wtedy istniejącą etykietę, a nie utworzy drugiej przesyłki.
Kto wykonuje integracje po stronie Studio WMS.net
Usługa Windows na serwerze, a zakres dla przewoźnika potwierdza analiza.
Integracje w Studio WMS.net wykonuje usługa Windows SSService.exe, instalowana na serwerze klienta. Łączy się z przewoźnikiem wyłącznie ruchem wychodzącym HTTPS, bez publikowania punktu dostępowego w Internecie. Komunikaty trafiają do tabeli wysyłkowej z ponawianiem i unikalnym identyfikatorem, więc wznowienie łączności nie tworzy duplikatów, a log każdej wymiany zostaje w bazie.
Cennik wymienia wymianę z firmami kurierskimi przez pliki Excel lub WebService. Ta strona nie deklaruje gotowych konektorów do konkretnych kurierów. Opisuje drogi integracji, a zakres dla danego przewoźnika potwierdza analiza przedwdrożeniowa. Zamówienia ze sprzedaży internetowej opisuje strona o integracji z platformami e-commerce.
Co ustala analiza przedwdrożeniowa
Cztery decyzje, od których zależy zakres prac.
Zakres integracji z kurierem wynika z analizy przedwdrożeniowej. Lista decyzji ma cztery pozycje:
- Droga integracji - plik, API przewoźnika albo agregator, osobno dla każdego kuriera.
- Umowy i usługi - które umowy obowiązują, czy potrzebne jest pobranie i jakie punkty odbioru wchodzą w grę.
- Etykiety - format ZPL czy PDF oraz drukarka na stanowisku pakowania.
- Statusy - webhook czy odpytywanie oraz odwzorowanie statusów przewoźnika na etapy w WMS.