# Štítky a jejich stavy

:::info[Rozšířená specifikace]
Jedná se o rozšířenou specifikaci API dokumentace pro pole `label_mode` a `label_status`
v objektech [Shipment](/api-v1/~schemas#shipment) a [Rate](/api-v1/~schemas#rate).
:::

Ne každá zásilka potřebuje štítek vytištěný odesílatelem. U části služeb přiveze štítek kurýr
při svozu, u bezštítkové zásilky PPL stačí kód SmartPIN a u Balíkovny lze místo štítku napsat
na balík jméno příjemce a podací kód. Samotný stav zásilky (`EXPORTED`) proto neříká, zda štítek
bude — tuto informaci nesou dvě pole:

| Pole | Význam | Kde ho najdete |
| --- | --- | --- |
| `label_mode` | **kdo štítek dodá** — tisknete sami, přiveze kurýr, nebo stačí kód | `/rates/get` (nabídka), `/shipments/create`, `/shipments/detail`, `/shipments/list` |
| `label_status` | **zda je štítek (nebo kód) už k dispozici** | `/shipments/create`, `/shipments/detail`, `/shipments/list` |

Obě pole se vrací všem volajícím, i bez přihlášení a bez tokenu objednávky.

## Režim štítku (`label_mode`)

Číselník [LabelMode](/api-v1/~schemas#labelmode):

| Hodnota | Kdo štítek dodá | Co udělat |
| --- | --- | --- |
| `PRINT` | Zaslat — odesílatel štítek vytiskne a nalepí na balík. | Po `label_status: READY` stáhněte štítek přes `POST /shipments/label`. |
| `CARRIER` | Kurýr dopravce ho přiveze při svozu. Zaslat žádný štítek neposkytuje. | Nic nestahujte; `/shipments/label` pro takovou zásilku štítek nevrátí (`400`). |
| `CODE` | Nikdo — bezštítková zásilka PPL, balík se podává kódem SmartPIN. | Po `label_status: READY` přečtěte kód z `packages[].package_password`, viz [Bezštítková zásilka PPL (SmartPIN)](/api/v1/labelless). |
| `PRINT_OR_CODE` | Odesílatel buď vytiskne štítek, nebo na balík napíše jméno příjemce a podací kód (Balíkovna). | Po `label_status: READY` buď stáhněte štítek, nebo použijte `packages[].package_password`. |

Režim je dán dopravcem, službou a způsobem podání a znáte ho už z nabídky `/rates/get` — pole
`label_mode` u každé položky [Rate](/api-v1/~schemas#rate). Můžete tak partnerovi nebo
zákazníkovi ještě před objednávkou říct, zda bude potřebovat tiskárnu. V nabídce se hodnota `CODE`
nevrací; bezštítkovou zásilku PPL volíte až příznakem `label_less` při objednávce.

## Stav štítku (`label_status`)

Číselník [LabelStatus](/api-v1/~schemas#labelstatus):

| Hodnota | Význam | Co udělat |
| --- | --- | --- |
| `NOT_APPLICABLE` | Štítek Zaslat neposkytuje (`label_mode: CARRIER`). | Na štítek nečekejte. |
| `PENDING` | Štítek (nebo kód) zatím není k dispozici — objednávka není zaplacena, nebo zásilka ještě nebyla předána dopravci. | Dotaz opakujte později. |
| `READY` | Štítek lze stáhnout přes `/shipments/label`; u `label_mode: CODE` je vyplněn `packages[].package_password`. | Stáhněte štítek, resp. přečtěte kód. |
| `FAILED` | Zásilka je u dopravce, ale štítek se od něj nepodařilo získat. | Další dotazování nepomůže — kontaktujte podporu. |

Stav `READY` nastává po předání zásilky dopravci (stav zásilky `EXPORTED`) u zaplacené objednávky.
U platby `ONLINE` zůstává `PENDING`, dokud objednávku nezaplatíte.

## Kdo štítek dodá — přehled dopravců

Rozhodující je vždy hodnota `label_mode` v odpovědi API; tabulka slouží pro orientaci při návrhu
integrace. Typ podání odpovídá poli `type` zásilky a použití `pickup_branch`:

| Dopravce | Jednorázový svoz z adresy (`ONDEMAND`) | Svozová adresa (`REGULAR`, `OCCASIONAL`) | Podání na výdejním místě (`pickup_branch`) |
| --- | --- | --- | --- |
| PPL | `PRINT` | `PRINT` | `PRINT`, s `label_less: true` `CODE` |
| DPD | `CARRIER` | `PRINT` | `PRINT` |
| GLS, GLS_SK | `CARRIER` | `PRINT` | `PRINT` |
| UPS, FedEx | `PRINT` | `PRINT` | — |
| Zásilkovna | — | `PRINT` | `PRINT` |
| Balíkovna | — | — | `PRINT_OR_CODE` |
| WeDo | `CARRIER` | `PRINT` | `PRINT` |
| SPS | `CARRIER` | `PRINT` | `PRINT` |
| TopTrans | `CARRIER` | `PRINT` | — |
| Liftago | `CARRIER` | — | — |

Pravidlo, které z tabulky plyne: ze svozové adresy nebo při podání na výdejním místě tiskne
štítek vždy odesílatel. Při jednorázovém svozu z adresy záleží na dopravci — PPL, UPS a FedEx
štítek nepřivážejí, ostatní dopravci ano.

## Doporučený postup

1. V nabídce `/rates/get` přečtěte `label_mode` a podle něj zákazníka informujte, zda bude
   potřebovat tiskárnu.
2. Po `POST /shipments/create` uložte `label_mode` každé zásilky. U `CARRIER` je hotovo — na
   štítek nečekejte a `/shipments/label` nevolejte.
3. U `PRINT` a `PRINT_OR_CODE` sledujte `label_status` v `POST /shipments/detail` (nebo
   `GET /shipments/list`), dokud není `READY`, a pak zavolejte `POST /shipments/label`.
4. U `CODE` čtěte od `label_status: READY` kód z `packages[].package_password`.
5. Při `label_status: FAILED` dotazování ukončete a kontaktujte
   [podpora@zaslat.cz](mailto:podpora@zaslat.cz).

Pro dotazování postačí interval jednotek minut; export k dopravci proběhne obvykle do několika
minut po zaplacení objednávky.

## Endpoint `/shipments/label`

Endpoint vrátí štítek jen pro zásilky s `label_status: READY`. Zásilku ve stavu `CREATED`
(např. nezaplacenou objednávku s platbou `ONLINE`) nenajde a vrátí `404`, stejně jako zásilku,
která neexistuje nebo patří jinému účtu. Pro zásilku s `label_mode: CARRIER` nebo
`label_status: FAILED` vrátí `400` — štítek buď přiveze kurýr, nebo se ho nepodařilo získat.
Před voláním proto zkontrolujte `label_status` v `/shipments/detail`, ušetříte si neúspěšné
dotazy.

## Příklad odpovědi `/shipments/detail`

Zásilka DPD s jednorázovým svozem z adresy — štítek přiveze kurýr:

```json
{
    "tracking_number": "IZ076151CA1F",
    "status": "EXPORTED",
    "type": "ONDEMAND",
    "carrier": "DPD",
    "label_mode": "CARRIER",
    "label_status": "NOT_APPLICABLE",
    "labels_ready": false,
    "label_less": false
}
```

Zásilka GLS ze svozové adresy po exportu — štítek je připraven ke stažení:

```json
{
    "tracking_number": "IZ0761A2B3C4",
    "status": "EXPORTED",
    "type": "OCCASIONAL",
    "carrier": "GLS",
    "label_mode": "PRINT",
    "label_status": "READY",
    "labels_ready": true,
    "label_less": false
}
```

## Zastaralá pole

Následující pole zůstávají v odpovědích kvůli zpětné kompatibilitě, v nových integracích je
nepoužívejte:

| Pole | Kde | Náhrada |
| --- | --- | --- |
| `labels_ready` | Shipment | `label_status: READY`. Hodnota `false` nerozlišuje `PENDING` od `NOT_APPLICABLE`. |
| `printable` | Rate | `label_mode` jiný než `CARRIER`. |
| `label_less` | Shipment | `label_mode: CODE`. Pole `label_less` se navíc vrací jen vlastníkovi zásilky. |