Błędy API InPost – najczęstsze komunikaty i jak je naprawić

Błędy walidacji danych przesyłki

Najwięcej błędów przy tworzeniu przesyłki to błędy danych. Część wynika z formularza zamówienia w sklepie, część z mapowania pól w integracji. Poniżej najczęstsze przypadki, które warto sprawdzić w pierwszej kolejności.

Problemy z telefonem to klasyka. Klienci wpisują numer z +48, ze spacjami albo numer stacjonarny. Jeśli formularz zamówienia nie normalizuje numeru, przesyłka zostanie odrzucona. Najlepiej czyścić numer już w koszyku – usuwać spacje, myślniki i prefiks kraju – a przy numerach zagranicznych od razu informować klienta, że dla dostawy do Paczkomatu potrzebny jest polski numer komórkowy.

Wykres – kolejność sprawdzania przyczyn błędu przy tworzeniu przesyłki [#chart:ip84b]

Błędy konta, usług i umowy

Druga grupa błędów nie dotyczy danych zamówienia, tylko konfiguracji konta. Dokumentacja tworzenia przesyłki wymienia m.in. błędy no_carriers (organizacja nie ma podpisanej umowy z żadnym przewoźnikiem) i carrier_unavailable (brak umowy z przewoźnikiem świadczącym wybraną usługę). FAQ ShipX opisuje też kilka komunikatów, które regularnie zaskakują sprzedawców.

[#uwaga] Błąd debt_collection potrafi zatrzymać wszystkie przesyłki naraz, często w najgorszym momencie – w szczycie sprzedaży. Jeśli korzystasz z prepaid, ustaw przypomnienie o niskim saldzie albo doładowuj konto z zapasem przed weekendem i sezonem.

Błędy przy edycji, anulowaniu i Paczce w Weekend

Część błędów wynika z próby wykonania operacji na przesyłce w niewłaściwym statusie. FAQ ShipX wyjaśnia, że zaktualizować można tylko przesyłki, które nie zostały jeszcze zakupione – w statusie created, offers_prepared albo offer_selected. Anulować przesyłkę może członek organizacji, a przesyłka musi mieć status created lub offers_prepared. Po opłaceniu przesyłki zmiana rozmiaru czy danych przez API nie jest już możliwa – wtyczki InPost wprost o tym informują.

Osobną grupą są błędy usługi Paczka w Weekend. Według FAQ usługa jest dostępna w określonym oknie czasowym, np. od czwartku od 20:00 do soboty do 13:00, bez uwzględniania świąt i dni wolnych. Próba utworzenia takiej przesyłki poza oknem, do punktu, który nie jest dostępny całą dobę, albo dla przesyłki Allegro kończy się błędem. Zasady usługi opisujemy w artykule Paczka w Weekend InPost.

Błędy śledzenia i webhooków

Przy śledzeniu przesyłek warto znać dwa ograniczenia z FAQ ShipX: API pozwala sprawdzić status pojedynczej przesyłki w jednym zapytaniu i umożliwia śledzenie statusów 45 dni wstecz. W sandboxie komponent śledzenia jest wyłączony, więc brak statusów w testach nie oznacza błędu integracji.

Webhooki wymagają, żeby adres był poprawnym URL-em, był dostępny i odpowiadał kodem HTTP 200 na zapytanie GET. Powiadomienia są wysyłane z zakresu adresów IP 91.216.25.0/24 – jeśli zapora sieciowa blokuje ten ruch, sklep nie dostanie aktualizacji statusów. Więcej w artykule śledzenie statusów InPost przez API.

Jak zorganizować obsługę błędów w sklepie

Błędy będą się zdarzać – ważne, żeby nie ginęły. Najgorszy scenariusz to zamówienie, dla którego przesyłka nie powstała, a nikt o tym nie wie aż do telefonu klienta.

• zapisuj pełne odpowiedzi API w logach integracji, z numerem zamówienia

• oznaczaj zamówienia z błędem osobnym statusem, widocznym dla magazynu

• wysyłaj powiadomienie do osoby odpowiedzialnej, gdy liczba błędów w ciągu dnia przekroczy próg

• przygotuj krótką instrukcję naprawy najczęstszych błędów dla zespołu

• po każdej aktualizacji wtyczki lub integracji powtórz testy w sandboxie

[#przyklad] Sklep z elektroniką miał kilka nieutworzonych przesyłek dziennie z powodu numerów telefonów z prefiksem kraju. Po dodaniu w koszyku automatycznego czyszczenia numeru i reguły, która oznacza zamówienia z błędem API osobnym statusem, liczba ręcznych poprawek spadła do pojedynczych przypadków, a magazyn widział je od razu rano.

Jeśli korzystasz z systemu do obsługi zamówień, sprawdź, gdzie wyświetla błędy przewoźników – piszemy o tym w artykule automatyczne nadawanie przesyłek InPost w systemie do obsługi zamówień. Przy własnej integracji pomoże przewodnik ShipX API InPost, a przy wtyczkach – InPost w WooCommerce. O bezpieczeństwie tokenów piszemy w tekście bezpieczeństwo kluczy API i konta InPost.

Najczęściej zadawane pytania

Co oznacza błąd 401 w API InPost?

Że zapytanie nie zostało podpisane ważnym tokenem. Sprawdź, czy token jest kompletny, aktualny i pochodzi z właściwego środowiska – produkcyjnego lub testowego.

Co oznacza validation_failed?

Że przesłane dane nie przeszły walidacji. Szczegóły znajdziesz w polu details odpowiedzi – są tam nazwy pól z błędami i klucze błędów, np. required, too_long czy invalid_format.

Dlaczego API odrzuca numer telefonu?

Według FAQ ShipX API obsługuje wyłącznie polskie numery telefonu – 9 cyfr, bez znaków specjalnych i numerów kierunkowych, np. +48.

Co zrobić z błędem debt_collection?

Na koncie prepaid sprawdź saldo i doładuj je. Przy umowie sprawdź, czy ostatnia faktura została opłacona, i skontaktuj się z opiekunem.

Dlaczego nie mogę pobrać etykiety?

Etykietę można pobrać dla przesyłki opłaconej – w statusie confirmed lub późniejszym – i tylko jako jej nadawca. Sprawdź status przesyłki i dane konta.

Czy mogę zmienić rozmiar przesyłki po jej utworzeniu?

Tylko przed zakupem przesyłki, w statusie created, offers_prepared lub offer_selected. Po opłaceniu zmiana przez API nie jest możliwa – trzeba anulować przesyłkę, jeśli status na to pozwala, i utworzyć nową.

Podsumowanie

Błędy API InPost dzielą się na kilka grup: autoryzacji (401, 403), walidacji danych (400 z polem details), konta i usług (np. debt_collection, brak umowy kurierskiej) oraz operacji w niewłaściwym statusie. Większość z nich da się szybko zdiagnozować, jeśli masz dostęp do pełnej odpowiedzi API. Zapobiegaj im na etapie koszyka – walidując telefon, kod pocztowy i punkt – i zorganizuj obsługę błędów tak, żeby żadne zamówienie nie utknęło bez wiedzy zespołu.

Wdrażamy i obsługujemy wysyłki InPost w sklepach internetowych – od konfiguracji integracji po monitoring błędów i reguły, które wyłapują problematyczne zamówienia, zanim zatrzymają wysyłkę. Sprawdź wdrożenie Base z automatyzacją wysyłek.