# DPD DPD Polska integration with Ritevo: API access and Numkat numbers, parcel and extra services, courier and DPD Pickup shipments, labels, reconnecting. The DPD Polska integration creates DPD courier shipments and shipments to DPD Pickup points. You connect it with DPD API credentials and your Numkat customer numbers. > **Required integration:** You need a contract with DPD Polska and a DPD API login and password. These are different from your DPD panel login - your DPD account manager gives them to you. You can add as many DPD integrations as you like, including several for the same account - for example with a different label format, parcel or sender address. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. `externalId` is not used. You provide new credentials with `PATCH /integrations/shippings/dpd-pl/{id}/credentials` - in any state of the integration. It checks them in DPD and sets `authError=false` and `active=true`. ## Which shipments it creates - **Courier** - by default the shipment goes by courier to the order's address. - **DPD Pickup point** - with the **Dostawa do punktu PUDO (DPD_PICKUP)** service ticked, the shipment goes to the point chosen in the order. An order without a pickup point fails. - **Cash on delivery and insurance** - cash on delivery from the order, insurance from the integration settings as a declared value rounded to whole units. - **Domestic shipments** - labels are requested as domestic, so international shipments may fail. ## Where to get the API access DPD gives you the API login and password and the Numkat numbers. Have them ready before adding the integration: 1. Ask your DPD account manager for DPD API access. 2. Note the API login and password and your Numkat (MasterFID). 3. If you ship from several locations, also ask for the Numkat of the dispatch location. With one location it is the same number. ## Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Shipments** section pick the **Dpd PL** tile. 3. Enter the **Account name** - your own name for the integration - and the DPD API **Login** and **Password**. 4. Enter the **Numkat (MasterFID)**, the **Sender Numkat (MasterFID)** and the **DPDInfoServices Numkat (MasterFID) (parcel tracking)**. 5. Fill in the other settings described below and click **Add integration**. We check the login and password in DPD right away: if they are wrong, you will see the error returned by DPD and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Dpd PL tile framed in the Shipments section](https://ritevo.com/docs/integrations/dpd/en-catalogue.webp) ![The DPD add screen with Account name, Login, Password, three Numkat numbers and label format fields](https://ritevo.com/docs/integrations/dpd/en-add.webp) ## Integration settings On the integration page you will find the fields below. You save changes with **Update integration**: - **Account name** - your own name for the integration. - **Numkat (MasterFID)** - your main DPD customer number. - **Sender Numkat (MasterFID)** - the number of the dispatch location. DPD bills the shipments to this number. With one location enter the same number as above. - **DPDInfoServices Numkat (MasterFID) (parcel tracking)** - the number for DPD parcel tracking. The field is required, but we do not track DPD shipments today. - **Label format** - A4 PDF, A6 PDF, A6 ZPL or A6 EPL. A4 PDF by default. - **Parcel details** - the dimensions in centimetres and the weight in kilograms of every shipment. Dimensions are rounded to whole centimetres. - **Extra services** - DPD services added to every shipment, for example Saturday delivery, delivery by 12:00 or return documents. **Etykieta cyfrowa (DIGITAL_LABEL)** and **Nadanie w punkcie PUDO (PUDO_TO_SEND)** only work when both are ticked. - **Update credentials** - you enter a new DPD API login and password. - **Sender address on the label** - the sender details the carrier prints on the label. - **Courier pickup address** - the address the courier collects parcels from. It can differ from the sender address on the label - for example in dropshipping: the label shows your shop, and the courier collects the parcel from the wholesaler. - **Additional insurance** - the insurance amount of every shipment: **None**, **Order value with delivery**, **Order value without delivery** or **Fixed amount**. In **Currency source** you pick the order currency, the delivery country currency or a fixed currency. Integration fields: `accountName`, `apiLogin`, `apiPassword`, `masterFid`, `senderFid`, `infoServicesFid` (numbers), `labelFormat` (`A4_PDF`, `A6_PDF`, `A6_ZPL`, `A6_EPL`), `packageDetails` with `length`, `width`, `height` in cm and `weight` in kg, and `additionalServices` - a list of: `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`. The API value is the name in brackets next to the service in the app. Fields shared by shipping integrations: `senderAddress` and `pickupAddress` (`companyName`, `firstName`, `lastName`, `street`, `city`, `zipCode`, `countryCode`, `phoneNumber`, `email`) and `additionalInsurance`. In it `insuranceType`: **None** = `NONE`, **Order value with delivery** = `ORDER_AMOUNT_WITH_DELIVERY`, **Order value without delivery** = `ORDER_AMOUNT_WITHOUT_DELIVERY`, **Fixed amount** = `FIXED_AMOUNT` (amount in `fixedAmount`), and `currencySource`: **Order currency** = `ORDER_CURRENCY`, **Delivery country currency** = `DELIVERY_COUNTRY_CURRENCY`, **Fixed currency** = `FIXED` (currency in `fixedCurrency`, required with `FIXED`). ![The Extra services card with the list of DPD services to tick](https://ritevo.com/docs/integrations/dpd/en-services.webp) ![The Sender address on the label card with company, first and last name, address, country, phone and email fields](https://ritevo.com/docs/integrations/shipping/en-sender.webp) ![The Courier pickup address card with company, first and last name, address, country, phone and email fields](https://ritevo.com/docs/integrations/shipping/en-pickup-address.webp) ![The Additional insurance card with the Insurance type and Currency source fields](https://ritevo.com/docs/integrations/shipping/en-insurance.webp) > **Good to know:** The integration does not book a courier pickup. You book the pickup directly with the carrier or set up a regular pickup schedule with them. > **Good to know:** When the order's payment method is **Cash on delivery**, the shipment gets cash on delivery automatically - in the order's amount and currency. ## Creating shipments You create a shipment from the order in two ways: - **By hand** - in the order details, in the **Shipments** card, click the button with the DPD integration name. You only see buttons for active integrations that match the order. - **Automatically** - with the **Create shipment** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). The shipment details come from the order: - **Recipient** - the order's delivery address and the buyer's phone and email. - **Pickup point** - the point the buyer chose, if the order has one. - **Cash on delivery** - the amount to pay from the order, when the payment method is **Cash on delivery**. - **Parcel** - one shipment is always one parcel. In the same card every shipment has a tracking number, a state and a creation date. The states: - **Being created** (API: "Being created" = `PENDING`; value in `shipments[].status`) - the carrier is still creating the shipment. We check it every few seconds. If the carrier does not confirm the shipment within 24 hours, it ends with an error. - **Created successfully** (API: "Created successfully" = `SUCCESS`; value in `shipments[].status`) - the shipment is with the carrier and has a tracking number. - **Creation failed** (API: "Creation failed" = `ERROR`; value in `shipments[].status`) - the carrier did not accept the shipment. The reason is shown next to the state, and for a carrier error also the carrier's message. You download the label of a created shipment with the **Download** button in the **Shipments** card. You print it in two ways - the [Ritevo Printer](https://ritevo.com/en/docs/integrations/ritevo-printer) app must run on the computer with the printer: - **By hand** - in the **Shipments** card click **Print** and pick the printer. - **Automatically** - with the **Print shipment label** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). The step prints the label of the latest shipment in the **Created successfully** state - it skips shipments being created and failed ones. Plan label printing step by step, as two actions: - **First action** - ends with the **Create shipment** step. - **Second action** - starts on the **Shipment created** trigger, has the **Shipment status is** condition with **Created successfully** and a single **Print shipment label** step. This way every new shipment prints its label right away - also when the order has several parcels. > **Good to know:** The **Print shipment label** step always prints just one label - that of the newest successful shipment. If you first create all shipments and only then turn on printing, only the last one is printed, and you print the others by hand with **Print**. If a new shipment fails, the step prints the label of the previous successful one. > **Good to know:** Every button click and every run of the **Create shipment** step creates a new shipment with the carrier. A shipment cannot be cancelled in Ritevo - you cancel it in the carrier's panel. ### How a shipment reaches DPD - **Right away** - DPD answers straight away, so the shipment is **Created successfully** or **Creation failed** right after sending. - **Tracking number** - the DPD waybill number. The same number is on the label. You create a shipment with `POST /orders/{orderId}/create-shipments/{shipmentIntegrationId}` - the response is 202, and the result shows up later in the order's `shipments[]` (`status`, `trackingNumber`, `errorType`, `errorMessage`). You download the label with `GET /orders/{orderId}/shipments/{shipmentId}/label` and request printing with `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}`. Order actions: the **Create shipment** step is `CREATE_SHIPMENT` and **Print shipment label** is `PRINT_SHIPMENT_LABEL` - both in `actionSteps[].action.type`, with `uuidValue` = the shipping integration id (`GET /integrations/shippings`) or the printer id (`GET /integrations/printers`). The **Shipment created** trigger is `triggerType` = `CREATE_SHIPMENT`. Conditions: **Has shipment** / **Has no shipment** = `HAS_SHIPMENT` / `HAS_SHIPMENT_NOT` (`booleanValues` = `[true]`), **Shipment status is** / **Shipment status is not** = `SHIPMENT_STATUS_IS` / `SHIPMENT_STATUS_IS_NOT` (`enumValues`: `PENDING`, `SUCCESS`, `ERROR`), **Shipment belongs to integration** / **Shipment does not belong to integration** = `SHIPMENT_SHIPPING_INTEGRATION_IS` / `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT` (`uuidValues` = shipping integration ids). The print step in an action takes the newest shipment with `status` = `SUCCESS` (by `createdAt`); manual printing via `POST /orders/{orderId}/print-shipment-label/...` also accepts only a `SUCCESS` shipment and returns `SHIPMENT_NOT_FOUND` otherwise. `SHIPMENT_STATUS_IS` is met when any shipment of the order has the given status, not only the latest. Full description: [Order actions](https://ritevo.com/en/docs/automations/order-actions). ## Reconnection required This state shows up when DPD stops accepting the API login and password - for example after DPD changed them. Until you enter new ones you cannot create shipments or download labels. 1. Ask your DPD account manager for the current API credentials. 2. On the integration page click **Update credentials**, enter the **Login** and **Password** and confirm. We check them in DPD the same way as when adding - correct ones refresh the connection, and the settings stay unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ## Deleting the integration **Delete integration** turns the integration off in Ritevo. Shipments created earlier stay in the orders and with the carrier. **Restore integration** turns it back on. ## What the integration does not do - It does not book a courier pickup. - It does not cancel shipments. - It does not track a shipment after it is created - you check the delivery state with the carrier. - It does not send the tracking number to the sales channel. - It does not create shipments with several parcels. - It does not track shipments through DPDInfoServices, even though the tracking number is in the settings. ## The integration through the API This integration's endpoints are under `/integrations/shippings/dpd-pl`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/shippings`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- All help in one file: https://ritevo.com/llms-full.txt. Help map with links to every page: https://ritevo.com/llms.txt.