pplcplapi/documentation/shipments.md

Zásilky

Tok CPL API je asynchronní (dávkový). Mapování na upstream metody:

Endpoint služby	Upstream CPL	Popis
POST /shipments/batch	POST shipment/batch	vytvoření zásilek (max 1000), vrací batchId
GET /shipments/batch/{batchId}	GET shipment/batch/{batchId}	stav importu
GET /shipments/batch/{batchId}/labels	GET shipment/batch/{batchId}/label	binární etikety
PUT /shipments/batch/{batchId}/label-settings	PUT shipment/batch/{batchId}	změna formátu etiket
POST /shipments/batch/connect-set	POST shipment/batch/connectSet	spojení zásilek do sady
POST /shipments/create-and-wait	(kombinace výše)	synchronní obálka
GET /shipments	GET shipment	tracking / vyhledání
POST /shipments/{n}/cancel	POST shipment/{n}/cancel	storno (PPL vrací 202)
POST /shipments/{n}/redirect	POST shipment/{n}/redirect	úprava kontaktu příjemce
POST /shipments/{n}/documents	POST shipment/{n}/documents	celní dokumenty (multipart)

Vytvoření zásilky

POST /shipments/batch — tělo se předává 1:1 do PPL (viz příklad ve Swaggeru). Povinné: shipments[].referenceId, shipments[].productType, shipments[].recipient.zipCode + country. Odpověď:

{ "batchId": "1c37...", "location": "https://.../shipment/batch/1c37...", "correlationId": "..." }

Query parametr transliterate řídí převod diakritiky (default dle služby).

Stav importu

GET /shipments/batch/{batchId} vrací items[] s importState: Accepted → InProcess → Complete (etikety připraveny) / Error (errorMessage, errorCode). Po dokončení obsahuje labelUrl per zásilka, příp. completeLabel.labelUrls (souhrnné PDF).

Etikety

GET /shipments/batch/{batchId}/labels?limit=200&offset=0&pageSize=A4&position=1 vrací binární soubor ve formátu z labelSettings.format (Pdf / Zpl / Jpeg / Png / Svg; DPI 203–1200). Jednotlivé etikety lze stáhnout i přes GET /data/{dataGuid} (guid z labelUrl).

create-and-wait (doporučeno pro e-shop scénář)

POST /shipments/create-and-wait?timeout_seconds=30&include_labels=true

1. vytvoří batch,
2. polluje stav (interval 1 s) dokud vše není Complete/Error nebo nevyprší timeout,
3. s include_labels=true stáhne etikety a vrátí je v base64.

Odpověď: {batchId, completed, items[], completeLabel, label?: {contentType, base64}}. completed=false = timeout; zpracování v PPL běží dál, stav lze dosledovat přes GET /shipments/batch/{batchId} (batchId platí 30 dní).

Tracking

GET /shipments?shipmentNumbers=...&limit=100&offset=0 — filtry: shipmentNumbers, invoiceNumbers, customerReferences, variableSymbols (vše max 50 hodnot, lze opakovat), dateFrom, dateTo, shipmentStates. Odpověď obsahuje tracking události; paging v hlavičkách X-Paging-*.

Celní dokumenty

POST /shipments/{n}/documents?documentFileType=... — multipart pole files (max 5 souborů, 1 MB celkem; pdf, doc(x), xls(x), jpg, jpeg, png, odt, ods, txt). Typy viz GET /codelists/documentFileType.