first

2026-07-16 11:56:15 +02:00
parent b650357194
commit 0e05fef335
23 changed files with 1900 additions and 15 deletions
@@ -0,0 +1,67 @@
+# 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ěď:
+
+```json
+{ "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`.