Centrum pomocy · API Paczuszki

Jak skorzystać z API Paczuszki?

Połącz sklep lub własny system z kontem Paczuszki. Zacznij od odczytu usług i salda, następnie przygotuj wycenę oraz świadome zatwierdzanie zleceń.

Otwórz specyfikację OpenAPI ↗Opis procesów API ↗

1. Konto i token API

Załóż lub wykorzystaj aktywne konto klienta Paczuszki. Ustal cennik i sposób rozliczenia: przedpłatę albo przyznany limit.
Uzyskaj token API w panelu Paczuszki. Zarządzanie kluczem wymaga odpowiedniego uprawnienia użytkownika; jeżeli sekcji nie widać, skontaktuj się z administratorem konta.
Przechowuj token wyłącznie po stronie serwera swojej integracji, oddzielnie dla każdego sklepu. Używaj menedżera sekretów lub chronionej konfiguracji środowiska.

2. Adres i autoryzacja

Adres bazowy: https://paczuszka.kuriersystem.pl/api/rest.

Do chronionych endpointów dodawaj nagłówek Authorization: Bearer TWÓJ_TOKEN. Żądania JSON używają Content-Type: application/json; odpowiedzi JSON odbieraj z Accept: application/json. Nie przekazuj tokenu w adresie URL.

3. Pierwsze bezpieczne zapytania

Poniższe przykłady korzystają z tokenu już ustawionego w chronionej zmiennej środowiskowej PACZUSZKA_TOKEN. Nie zawierają rzeczywistego klucza i nie tworzą przesyłki.

curl --fail-with-body \
  -H "Authorization: Bearer $PACZUSZKA_TOKEN" \
  -H "Accept: application/json" \
  https://paczuszka.kuriersystem.pl/api/rest/service

curl --fail-with-body \
  -H "Authorization: Bearer $PACZUSZKA_TOKEN" \
  -H "Accept: application/json" \
  https://paczuszka.kuriersystem.pl/api/rest/company/balance

GET /service zwraca katalog usług, opakowań i dodatków konta. Korzystaj z kodów zwróconych przez API, zamiast zakładać dostępność każdego przewoźnika lub dodatku. GET /company/balance zwraca dane salda. Samego przyznanego credit_limit nie traktuj jako pozostałego kredytu do wykorzystania.

4. Zalecany proces integracji

Zamówienia → parametry paczek → wycena → wybór oferty → suma kosztów → osobne zatwierdzenie → zlecenie → świadoma realizacja etykiety.

Cel	Endpoint i zasady
Katalog	`GET /service`. Sprawdź usługę, opakowanie, wymagane punkty i dostępność dodatków dla konta.
Wycena	`POST /portal/price/{service_code}`. Przekaż paczkę, nadawcę, odbiorcę, wymagane punkty i dodatki zgodnie ze schematem PortalOrder. Użyj tokenu konta, aby uzyskać jego cennik. Wycena sama nie tworzy zlecenia.
Wybór i zgoda	Sortuj zgodne oferty według ceny brutto. Wybór najtańszej nie zastępuje osobnej zgody na koszt. Zmiana danych lub ceny wymaga odnowienia wyceny i zgody.
Utworzenie	`POST /order` według schematu Order, po zatwierdzeniu. Zapisz trwały numer `reference_number` i identyfikator otrzymanego zlecenia.
Odczyt i uzgodnienie	`GET /order/{order_id}` albo `GET /order/{reference_number}`. Po przerwanym połączeniu najpierw ustal wynik wcześniejszego zapisu.
Etykieta	`POST /label/{order_id}` jest operacją realizacji, a nie zwykłym odczytem. Pierwsze pobranie etykiety może przekazać przesyłkę do przewoźnika. Zachowaj oryginalny PDF prywatnie do ponownego druku.

Komplet pól, formatów i parametrów sprawdzaj w aktualnym OpenAPI oraz opisie procesów. Schematy odpowiedzi nie opisują jeszcze wszystkich zachowań biznesowych; przy rozbieżnościach uzgodnij kontrakt z nami przed uruchomieniem automatyzacji.

5. Rozliczenia i dostępne opcje

API sprawdza środki lub pozostały limit klienta. Przy prepaid zlecenie jest oznaczane jako opłacone z salda już przy utworzeniu, przed etykietą. Nie ma zapisu roboczego zlecenia bez wyceny i wyboru usługi. Saldo w interfejsie ma charakter informacyjny i nie zastępuje walidacji backendu.

Pobranie COD — kontrakt potwierdzony 6 listopada 2026

Przy POST /order przekaż w głównym obiekcie cod_value (liczba, kwota w PLN) i cod_bank_account (rachunek do zwrotu pobrania). Przy tworzeniu zlecenia API samo dodaje pozycję COD; nie dodawaj jej drugi raz do service_list.

Wycena ma dodatkowe wymaganie: w POST /portal/price/{service_code} przekaż także service_list z pozycją {"code":"COD","value":"150.50","quantity":1}. Same pola główne nie uwzględniają dopłaty COD w kalkulatorze. Dla InPost wymagane jest również INSURANCE z deklarowaną wartością w obu żądaniach. Wtyczki WooCommerce 0.4.1-beta.1 i PrestaShop 0.1.1-beta.1 dodają ubezpieczenie automatycznie i uwzględniają dopłatę COD w wycenie.

SMS wymaga potwierdzenia w katalogu konta. API nadal nie ma potwierdzonego atomowego limitu maksymalnej zaakceptowanej ceny / quote_id. Po zapisie sprawdź naliczony koszt; rozbieżność wymaga wyjaśnienia i nie uprawnia do ponownego tworzenia zlecenia.

6. Błędy, timeouty i duplikaty

Odpowiedź	Postępowanie
HTTP 401	Sprawdź aktywność i poprawność tokenu. Nie wypisuj go w komunikacie lub logu.
HTTP 400 + `REMAINING_BALANCE_TOO_LOW` w details	Brak środków lub pozostałego limitu. Sprawdź rozliczenia konta i wynik rozpoczętej operacji przed ponowieniem.
HTTP 400 + `NO_OFFER` w details	Brak wyceny. Sprawdź usługę, trasę, dane paczki i dodatki. Nie traktuj tego jako braku środków lub ceny zero.
Inny HTTP 400	To ogólne odrzucenie żądania; nie zakładaj automatycznie braku środków. Sprawdź kontrakt i dane wejściowe.
Timeout / niepewny wynik	Zachowaj blokadę ponownego zapisu i wyszukaj po tej samej referencji. Nie wysyłaj nowego zlecenia z inną referencją tylko w celu obejścia niepewności.

reference_number jest unikalny w ramach klienta API. Ponowne wysłanie istniejącej referencji według kontraktu KurierSystemu zwraca stare zlecenie. Unikalność referencji nie oznacza jednak potwierdzonej idempotencji każdej operacji etykiety. Nie ponawiaj automatycznie realizacji po timeoutcie.

7. Anulowanie i testy

Przed testem ustal działającą ścieżkę anulowania i weryfikacji zwrotu. Samo 404 po anulowaniu nie potwierdza zwrotu ani ostatecznego statusu. Do czasu wyjaśnienia niepewnego wyniku sprawdzaj stan w panelu i nie reaktywuj tego samego zlecenia.

8. Dokumentacja i kontakt

Pomoc: biuro@paczuszka.pl. Przekaż metodę i ścieżkę endpointu, czas, kod HTTP oraz numer referencyjny zlecenia, jeśli dotyczy. Usuń token, hasła i dane osobowe z przykładów i logów.

← Wszystkie instrukcje