JiriUhlir
68 lines
3.1 KiB
Markdown
68 lines
3.1 KiB
Markdown
# 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`.
|