# InPost

Integracja InPost ShipX z Ritevo: token API i ID organizacji, gabaryt i sposób nadania, przesyłki do paczkomatów z pobraniem, etykiety, ponowne połączenie.

Integracja z InPost tworzy przesyłki do paczkomatów InPost przez API ShipX. Podłączasz ją tokenem API i ID organizacji z Managera Paczek InPost.

> **Wymagana integracja:** Potrzebujesz konta w Managerze Paczek InPost z uzupełnionymi danymi firmy i danymi do faktury.

Integracji InPost możesz dodać dowolnie wiele, także kilka dla tego samego konta - na przykład z innym formatem etykiety, inną paczką albo innym adresem nadawcy. Każda działa osobno.

Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami.

`externalId` nie jest używany. Nowy token podasz przez `PATCH /integrations/shippings/inpost-locker-x/{id}/token` - w każdym stanie integracji. Sprawdza token w InPost i ustawia `authError=false` i `active=true`.

## Jakie przesyłki tworzy

- **Paczkomat** - przesyłka zawsze jedzie do paczkomatu wybranego przez kupującego. Zamówienie musi mieć punkt odbioru - bez niego InPost odrzuci przesyłkę.
- **Kurier** - przesyłki kurierskie nie są obsługiwane.
- **Zamówienia z Allegro** - dostają usługę Paczkomat Allegro, a pozostałe zwykłą usługę Paczkomat.
- **Pobranie i ubezpieczenie** - pobranie z zamówienia, ubezpieczenie z ustawień integracji.
- **Dowolny kanał sprzedaży** - przesyłkę utworzysz dla zamówienia z każdego kanału.

## Skąd wziąć token i ID organizacji

Oba znajdziesz w Managerze Paczek InPost. Przygotuj je przed dodaniem integracji:

1. Zaloguj się do Managera Paczek InPost na manager.paczkomaty.pl.
2. Przejdź do **Moje konto** → **API** i w zakładce **API ShipX** kliknij **Generuj**. Skopiuj token.
3. W zakładce **Ustawienia organizacji** skopiuj ID organizacji. Pojawi się ono dopiero po wygenerowaniu tokenu.

## Podłączenie konta

Zacznij w Ritevo:

1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu.
2. W sekcji **Przesyłki** wybierz kafelek **Inpost paczkomat ShipX**.
3. Wpisz **Nazwa konta** - własną nazwę integracji - oraz wklej **Token API ShipX** i **ID organizacji ShipX**.
4. Uzupełnij pozostałe ustawienia opisane niżej i kliknij **Dodaj integrację**. Token sprawdzamy od razu w InPost: jeśli jest błędny, zobaczysz błąd zwrócony przez InPost i nic nie zostanie zapisane.

![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp)

![Ekran Dodaj integrację z zaznaczonym kafelkiem Inpost paczkomat ShipX w sekcji Przesyłki](https://ritevo.com/docs/integrations/inpost/pl-catalogue.webp)

![Ekran dodawania integracji InPost z polami Nazwa konta, Token API ShipX, ID organizacji ShipX, gabarytem, formatem etykiety, sposobem nadania i kodem punktu](https://ritevo.com/docs/integrations/inpost/pl-add.webp)

## Ustawienia integracji

Na stronie integracji znajdziesz poniższe pola. Zmiany zapisujesz przyciskiem **Zaktualizuj integrację**:

- **Nazwa konta** - Twoja własna nazwa integracji.
- **Domyślny gabaryt paczki** - **Gabaryt A**, **Gabaryt B** albo **Gabaryt C**. Domyślnie A.
- **Format etykiety** - A4 PDF, A6 PDF, A6 ZPL, A6 ZPL 300dpi albo A6 EPL. Domyślnie A6 PDF.
- **Sposób nadania** - jak przekazujesz paczki InPost: **Odbiór przez kuriera**, **Nadanie w automacie Paczkomat**, **Nadanie w oddziale InPost**, **Nadanie w POK**, **Nadanie w POP (PaczkoPunkt)** albo **Nadanie w dowolnym punkcie**. Domyślnie odbiór przez kuriera.
- **Kod punktu nadawczego** - kod punktu, w którym nadajesz paczki. Pole jest wymagane przy każdym sposobie nadania.
- **Zaktualizuj token** - podajesz nowy token API ShipX.
- **Adres nadawcy na etykiecie** - dane nadawcy, które przewoźnik drukuje na etykiecie.
- **Adres odbioru przesyłek przez kuriera** - adres, spod którego kurier odbiera paczki. Może być inny niż adres nadawcy na etykiecie - na przykład przy dropshippingu: na etykiecie jest Twój sklep, a kurier odbiera paczkę z hurtowni.
- **Dodatkowe ubezpieczenie** - kwota ubezpieczenia każdej przesyłki: **Brak**, **Wartość zamówienia z dostawą**, **Wartość zamówienia bez dostawy** albo **Stała kwota**. W **Źródło waluty** wybierasz walutę zamówienia, walutę kraju dostawy albo stałą walutę.

Pola integracji: `accountName`, `apiToken`, `organizationId`, `defaultTemplate` (**Gabaryt A** = `SMALL`, **Gabaryt B** = `MEDIUM`, **Gabaryt C** = `LARGE`), `labelFormat` (`A4_PDF`, `A6_PDF`, `A6_ZPL`, `A6_ZPL_300`, `A6_EPL`), `sendingMethod` (**Odbiór przez kuriera** = `DISPATCH_ORDER`, **Nadanie w automacie Paczkomat** = `PARCEL_LOCKER`, **Nadanie w oddziale InPost** = `BRANCH`, **Nadanie w POK** = `POK`, **Nadanie w POP (PaczkoPunkt)** = `POP`, **Nadanie w dowolnym punkcie** = `ANY_POINT`) i `dropoffPoint`.

Pola wspólne dla przesyłek: `senderAddress` i `pickupAddress` (`companyName`, `firstName`, `lastName`, `street`, `city`, `zipCode`, `countryCode`, `phoneNumber`, `email`) oraz `additionalInsurance`. W nim `insuranceType`: **Brak** = `NONE`, **Wartość zamówienia z dostawą** = `ORDER_AMOUNT_WITH_DELIVERY`, **Wartość zamówienia bez dostawy** = `ORDER_AMOUNT_WITHOUT_DELIVERY`, **Stała kwota** = `FIXED_AMOUNT` (kwota w `fixedAmount`), a `currencySource`: **Waluta zamówienia** = `ORDER_CURRENCY`, **Waluta kraju dostawy** = `DELIVERY_COUNTRY_CURRENCY`, **Stała waluta** = `FIXED` (waluta w `fixedCurrency`, wymagana przy `FIXED`).

![Szczegóły integracji InPost: ustawienia podstawowe z gabarytem, formatem etykiety, sposobem nadania i kodem punktu oraz adres nadawcy](https://ritevo.com/docs/integrations/inpost/pl-details.webp)

![Karta Adres nadawcy na etykiecie z polami firmy, imienia i nazwiska, adresu, kraju, telefonu i e-maila](https://ritevo.com/docs/integrations/shipping/pl-sender.webp)

![Karta Adres odbioru przesyłek przez kuriera z polami firmy, imienia i nazwiska, adresu, kraju, telefonu i e-maila](https://ritevo.com/docs/integrations/shipping/pl-pickup-address.webp)

![Karta Dodatkowe ubezpieczenie z polami Typ ubezpieczenia i Źródło waluty](https://ritevo.com/docs/integrations/shipping/pl-insurance.webp)

> **Warto wiedzieć:** Integracja nie zamawia podjazdu kuriera. Podjazd zamawiasz bezpośrednio u przewoźnika albo ustawiasz u niego stały harmonogram odbiorów.

> **Warto wiedzieć:** Gdy zamówienie ma metodę płatności **Płatność przy odbiorze**, przesyłka dostaje pobranie automatycznie - w kwocie i walucie zamówienia.

## Tworzenie przesyłek

Przesyłkę tworzysz z zamówienia na dwa sposoby:

- **Ręcznie** - w szczegółach zamówienia, w karcie **Przesyłki**, kliknij przycisk z nazwą integracji InPost. Przyciski widzisz tylko dla aktywnych integracji, które pasują do zamówienia.
- **Automatycznie** - krokiem **Utwórz przesyłkę** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions).

Dane przesyłki bierzemy z zamówienia:

- **Odbiorca** - adres dostawy z zamówienia oraz telefon i e-mail kupującego.
- **Punkt odbioru** - punkt wybrany przez kupującego, jeśli zamówienie go ma.
- **Pobranie** - kwota do zapłaty z zamówienia, gdy metoda płatności to **Płatność przy odbiorze**.
- **Paczka** - jedna przesyłka to zawsze jedna paczka.

W tej samej karcie każda przesyłka ma numer śledzenia, stan i datę utworzenia. Stany:

- **W trakcie tworzenia** (API: "W trakcie tworzenia" = `PENDING`; wartość w `shipments[].status`) - przewoźnik jeszcze tworzy przesyłkę. Sprawdzamy ją co kilka sekund. Jeśli przewoźnik nie potwierdzi przesyłki w ciągu 24 godzin, kończy się ona błędem.
- **Utworzona pomyślnie** (API: "Utworzona pomyślnie" = `SUCCESS`; wartość w `shipments[].status`) - przesyłka jest u przewoźnika i ma numer śledzenia.
- **Błąd podczas tworzenia** (API: "Błąd podczas tworzenia" = `ERROR`; wartość w `shipments[].status`) - przewoźnik nie przyjął przesyłki. Przy stanie widzisz powód, a przy błędzie przewoźnika także jego komunikat.

Etykietę utworzonej przesyłki pobierzesz przyciskiem **Pobierz** w karcie **Przesyłki**. Drukujesz ją na dwa sposoby - na komputerze z drukarką musi wtedy działać aplikacja [Ritevo Printer](https://ritevo.com/pl/docs/integrations/ritevo-printer):

- **Ręcznie** - w karcie **Przesyłki** kliknij **Drukuj** i wybierz drukarkę.
- **Automatycznie** - krokiem **Wydrukuj etykietę przesyłki** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Krok drukuje etykietę ostatniej przesyłki ze stanem **Utworzona pomyślnie** - przesyłki w trakcie tworzenia i z błędem pomija.

Druk etykiet najlepiej zaplanować po kolei, jako dwie akcje:

- **Pierwsza akcja** - kończy się krokiem **Utwórz przesyłkę**.
- **Druga akcja** - startuje wyzwalaczem **Stworzono przesyłkę**, ma warunek **Status przesyłki jest** z wartością **Utworzona pomyślnie** i jeden krok **Wydrukuj etykietę przesyłki**. Dzięki temu każda nowa przesyłka od razu drukuje swoją etykietę - także gdy zamówienie ma kilka paczek.

> **Warto wiedzieć:** Krok **Wydrukuj etykietę przesyłki** drukuje zawsze tylko jedną etykietę - najnowszej udanej przesyłki. Jeśli najpierw utworzysz wszystkie przesyłki, a dopiero potem włączysz druk, wydrukuje się tylko ostatnia, a pozostałe wydrukujesz ręcznie przyciskiem **Drukuj**. Jeśli nowa przesyłka się nie uda, krok wydrukuje etykietę poprzedniej udanej.

> **Warto wiedzieć:** Każde kliknięcie przycisku i każde uruchomienie kroku **Utwórz przesyłkę** tworzy nową przesyłkę u przewoźnika. Przesyłki nie da się anulować w Ritevo - anulujesz ją w panelu przewoźnika.

### Jak przesyłka trafia do InPost

- **Potwierdzenie** - InPost tworzy przesyłkę w tle, więc najpierw ma ona stan **W trakcie tworzenia**. Gdy InPost nada numer śledzenia, zmienia się na **Utworzona pomyślnie**.
- **Numer śledzenia** - numer przesyłki InPost. Ten sam numer jest na etykiecie.
- **Anulowanie w InPost** - przesyłka anulowana w InPost w trakcie tworzenia kończy się błędem.

Przesyłkę tworzysz przez `POST /orders/{orderId}/create-shipments/{shipmentIntegrationId}` - odpowiedź 202, a wynik pojawia się później w `shipments[]` zamówienia (`status`, `trackingNumber`, `errorType`, `errorMessage`). Etykietę pobierasz przez `GET /orders/{orderId}/shipments/{shipmentId}/label`, a wydruk zlecasz przez `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}`.

Akcje dla zamówień: krok **Utwórz przesyłkę** to `CREATE_SHIPMENT`, a **Wydrukuj etykietę przesyłki** to `PRINT_SHIPMENT_LABEL` - oba w `actionSteps[].action.type`, z `uuidValue` = id integracji wysyłkowej (`GET /integrations/shippings`) albo id drukarki (`GET /integrations/printers`). Wyzwalacz **Stworzono przesyłkę** to `triggerType` = `CREATE_SHIPMENT`. Warunki: **Posiada przesyłkę** / **Nie posiada przesyłki** = `HAS_SHIPMENT` / `HAS_SHIPMENT_NOT` (`booleanValues` = `[true]`), **Status przesyłki jest** / **Status przesyłki nie jest** = `SHIPMENT_STATUS_IS` / `SHIPMENT_STATUS_IS_NOT` (`enumValues`: `PENDING`, `SUCCESS`, `ERROR`), **Przesyłka należy do integracji** / **Przesyłka nie należy do integracji** = `SHIPMENT_SHIPPING_INTEGRATION_IS` / `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT` (`uuidValues` = id integracji wysyłkowych). Druk etykiety w akcji bierze najnowszą przesyłkę z `status` = `SUCCESS` (po `createdAt`); ręczny druk przez `POST /orders/{orderId}/print-shipment-label/...` też przyjmuje tylko przesyłkę `SUCCESS`, inaczej zwraca `SHIPMENT_NOT_FOUND`. `SHIPMENT_STATUS_IS` jest spełniony, gdy dowolna przesyłka zamówienia ma podany status, nie tylko ostatnia. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions).

## Wymaga ponownego połączenia

Ten stan pojawia się, gdy InPost przestał akceptować token - na przykład po wygenerowaniu nowego tokenu w Managerze Paczek. Do czasu podania nowego tokenu nie utworzysz przesyłek ani nie pobierzesz etykiet.

1. W Managerze Paczek InPost skopiuj aktualny token z zakładki **API ShipX**.
2. Na stronie integracji kliknij **Zaktualizuj token**, wklej go w polu **Nowy token API ShipX** i zatwierdź. Sprawdzamy go w InPost tak samo jak przy dodawaniu - poprawny odświeży połączenie, a ustawienia zostają bez zmian.

![Dół strony integracji InPost z przyciskami Zaktualizuj token i Zaktualizuj integrację](https://ritevo.com/docs/integrations/inpost/pl-token.webp)

![Okno Zaktualizuj token w integracji InPost z polem Nowy token API ShipX](https://ritevo.com/docs/integrations/inpost/pl-update-token.webp)

> **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać.

W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony.

## Usunięcie integracji

**Usuń integrację** wyłącza integrację w Ritevo. Przesyłki utworzone wcześniej zostają w zamówieniach i u przewoźnika. **Przywróć integrację** włącza ją z powrotem.

## Czego integracja nie robi

- Nie zamawia podjazdu kuriera.
- Nie anuluje przesyłek.
- Nie śledzi przesyłki po jej utworzeniu - stan doręczenia sprawdzasz u przewoźnika.
- Nie przekazuje numeru śledzenia do kanału sprzedaży.
- Nie tworzy przesyłek z kilkoma paczkami.
- Nie tworzy przesyłek kurierskich - tylko do paczkomatów.

## Integracja przez API

Endpointy tej integracji są pod `/integrations/shippings/inpost-locker-x`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/shippings`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs.


---

Cała pomoc w jednym pliku: https://ritevo.com/llms-full.txt. Mapa pomocy z linkami do wszystkich stron: https://ritevo.com/llms.txt.