# DPD

Integracja DPD Polska z Ritevo: dane do API i Numkat, paczka i dodatkowe serwisy, przesyłki kurierskie i do punktów DPD Pickup, etykiety, ponowne połączenie.

Integracja z DPD Polska tworzy przesyłki kurierskie DPD i przesyłki do punktów DPD Pickup. Podłączasz ją danymi do API DPD i numerami klienta Numkat.

> **Wymagana integracja:** Potrzebujesz umowy z DPD Polska oraz loginu i hasła do API DPD. To inne dane niż login do panelu DPD - dostaniesz je od opiekuna konta DPD.

Integracji DPD 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. Nowe dane logowania podasz przez `PATCH /integrations/shippings/dpd-pl/{id}/credentials` - w każdym stanie integracji. Sprawdza je w DPD i ustawia `authError=false` i `active=true`.

## Jakie przesyłki tworzy

- **Kurier** - domyślnie przesyłka jedzie kurierem pod adres z zamówienia.
- **Punkt DPD Pickup** - po zaznaczeniu usługi **Dostawa do punktu PUDO (DPD_PICKUP)** przesyłka jedzie do punktu wybranego w zamówieniu. Zamówienie bez punktu odbioru skończy się błędem.
- **Pobranie i ubezpieczenie** - pobranie z zamówienia, a ubezpieczenie z ustawień integracji jako wartość deklarowana, zaokrąglona do pełnych złotych.
- **Przesyłki krajowe** - etykiety pobieramy jako krajowe, więc przesyłki zagraniczne mogą się nie udać.

## Skąd wziąć dane do API

Login i hasło do API oraz numery Numkat dostaniesz od DPD. Przygotuj je przed dodaniem integracji:

1. Poproś opiekuna konta DPD o dostęp do API DPD.
2. Zapisz login i hasło do API oraz swój Numkat (MasterFID).
3. Jeśli nadajesz z kilku lokalizacji, poproś też o Numkat lokalizacji nadania. Przy jednej lokalizacji to ten sam numer.

## 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 **Dpd PL**.
3. Wpisz **Nazwa konta** - własną nazwę integracji - oraz **Login** i **Hasło** do API DPD.
4. Wpisz **Numkat (MasterFID)**, **Numkat (MasterFID) nadawcy** i **Numkat (MasterFID) DPDInfoServices (śledzenie paczek)**.
5. Uzupełnij pozostałe ustawienia opisane niżej i kliknij **Dodaj integrację**. Login i hasło sprawdzamy od razu w DPD: jeśli są błędne, zobaczysz błąd zwrócony przez DPD 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 Dpd PL w sekcji Przesyłki](https://ritevo.com/docs/integrations/dpd/pl-catalogue.webp)

![Ekran dodawania integracji DPD z polami Nazwa konta, Login, Hasło, trzema numerami Numkat i formatem etykiety](https://ritevo.com/docs/integrations/dpd/pl-add.webp)

## Ustawienia integracji

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

- **Nazwa konta** - Twoja własna nazwa integracji.
- **Numkat (MasterFID)** - główny numer klienta DPD.
- **Numkat (MasterFID) nadawcy** - numer lokalizacji nadania. Na ten numer DPD rozlicza przesyłki. Przy jednej lokalizacji wpisz ten sam numer co wyżej.
- **Numkat (MasterFID) DPDInfoServices (śledzenie paczek)** - numer do śledzenia paczek w DPD. Pole jest wymagane, ale dziś nie śledzimy przesyłek DPD.
- **Format etykiety** - A4 PDF, A6 PDF, A6 ZPL albo A6 EPL. Domyślnie A4 PDF.
- **Szczegóły paczki** - wymiary w centymetrach i waga w kilogramach każdej przesyłki. Wymiary zaokrąglamy do pełnych centymetrów.
- **Dodatkowe serwisy** - usługi DPD dodawane do każdej przesyłki, na przykład doręczenie w sobotę, doręczenie do 12:00 czy dokumenty zwrotne. **Etykieta cyfrowa (DIGITAL_LABEL)** i **Nadanie w punkcie PUDO (PUDO_TO_SEND)** działają tylko zaznaczone razem.
- **Zaktualizuj dane logowania** - podajesz nowy login i hasło do API DPD.
- **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`, `apiLogin`, `apiPassword`, `masterFid`, `senderFid`, `infoServicesFid` (liczby), `labelFormat` (`A4_PDF`, `A6_PDF`, `A6_ZPL`, `A6_EPL`), `packageDetails` z `length`, `width`, `height` w cm i `weight` w kg oraz `additionalServices` - lista wartości: `CARRY_IN`, `CUD`, `ROD`, `HAND_DELIVERY`, `SELF_COLLECTION`, `PRIVATE_PERSON`, `DEDICATED_DELIVERY`, `PALETTE`, `DOX`, `DPD_EXPRESS`, `DOCUMENTS_INTERNATIONAL`, `DPD_LQ`, `DPD_NEXT_DAY`, `DPD_PICKUP`, `DPD_TODAY`, `INTERNATIONAL`, `SATURDAY`, `TIME0930`, `TIME1200`, `TIRES`, `TIRES_EXPORT`, `DIGITAL_LABEL`, `PUDO_TO_SEND`. Wartość w API to nazwa w nawiasie przy usłudze w aplikacji.

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`).

![Karta Dodatkowe serwisy z listą usług DPD do zaznaczenia](https://ritevo.com/docs/integrations/dpd/pl-services.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 DPD. 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 DPD

- **Od razu** - DPD odpowiada od razu, więc przesyłka ma stan **Utworzona pomyślnie** albo **Błąd podczas tworzenia** zaraz po wysłaniu.
- **Numer śledzenia** - numer listu przewozowego DPD. Ten sam numer jest na etykiecie.

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 DPD przestało akceptować login i hasło do API - na przykład po ich zmianie przez DPD. Do czasu podania nowych danych nie utworzysz przesyłek ani nie pobierzesz etykiet.

1. Poproś opiekuna konta DPD o aktualne dane do API.
2. Na stronie integracji kliknij **Zaktualizuj dane logowania**, wpisz **Login** i **Hasło** i zatwierdź. Sprawdzamy je w DPD tak samo jak przy dodawaniu - poprawne odświeżą połączenie, a ustawienia zostają bez zmian.

> **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 śledzi przesyłek przez DPDInfoServices, mimo że numer do śledzenia jest w ustawieniach.

## Integracja przez API

Endpointy tej integracji są pod `/integrations/shippings/dpd-pl`, 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.