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