# Sledování zásilek a stavy

:::info[Rozšířená specifikace]
Jedná se o rozšířenou specifikaci API dokumentace pro endpointy `shipments/tracking`,
`shipments/detail` a `shipments/list`.
:::

## Životní cyklus zásilky

Zásilka prochází stavy v tomto pořadí (číselník
[ShipmentStatus](/api-v1/~schemas#shipmentstatus)):

| Stav | Popis |
| --- | --- |
| `CREATED` | Zásilka vytvořena v systému Zaslat. |
| `EXPORTED` | Dopravce potvrdil přijetí dat o zásilce — od této chvíle je dostupný štítek. |
| `ONPICKUP` | Zásilka čeká na svoz kurýrem. |
| `INTRANSIT` | Zásilka na cestě do cílového depa. |
| `ONDELIVERY` | Zásilka předána kurýrovi k doručení. |
| `DELIVERED` | Zásilka doručena. |
| `CANCELLED` | Zásilka zrušena (stornována). |

Stav má jak zásilka, tak každý její balík zvlášť. Tracking odpověď navíc obsahuje příznak
`returned` — `true` znamená, že zásilka byla vrácena odesílateli.

## Jak stav zjistit

- **`POST /shipments/tracking`** — aktuální stav a kompletní historie tracking událostí. Pro
  každý balík zásilky vrací samostatné pole událostí (datum, čas, popis, stav, místo).
- **`POST /shipments/detail?tracking`** — detail zásilek; s query parametrem `tracking` odpověď
  u každé zásilky obsahuje navíc pole `tracking_information` se stejným obsahem jako
  `shipments/tracking`. Ušetříte tak druhé volání, pokud potřebujete detail i historii.
- **`GET /shipments/list?tracking`** — stránkovaný seznam zásilek, parametr `tracking` funguje
  stejně. Seznam lze filtrovat podle stavu (`status=OPEN|ACTIVE|DELIVERED|STORNO`), data
  vytvoření nebo vlastní reference.

## Doporučený způsob integrace

API v1 **nenabízí webhooky** (odchozí HTTP notifikace o změně stavu). Stav zásilek zjišťujte
dotazováním (pollingem):

- Pro průběžnou synchronizaci většího množství zásilek použijte `GET /shipments/list?tracking`
  s filtrem `status=ACTIVE` — jedním voláním získáte stav všech aktivních zásilek.
- Pro jednotlivé zásilky použijte `POST /shipments/tracking` s dávkou identifikátorů (endpoint
  přijímá pole `shipments`).
- Tracking data se přebírají od dopravců průběžně — pro běžnou integraci je dostačující
  dotazovat se v intervalu desítek minut.

E-mailové notifikace o vyzvednutí, problému či doručení (odesílateli i příjemci) lze zapnout
ve správním rozhraní ([app.zaslat.cz](https://app.zaslat.cz)).

## Příklad dotazu

```json
{
    "shipments": ["IZ076151CA1F", "IZ1234567890"]
}
```

Odpověď (zkráceno na jednu zásilku):

```json
{
    "status": 200,
    "message": "OK. Found 2 item(s).",
    "data": {
        "IZ076151CA1F": {
            "status": "INTRANSIT",
            "returned": false,
            "packages": [
                [
                    {
                        "date": "2026-07-04",
                        "time": "15:00:00",
                        "name": "Balík byl přijat pobočkou GLS.",
                        "status": "INTRANSIT",
                        "location": "Česká republika"
                    },
                    {
                        "date": "2026-07-02",
                        "time": "12:00:00",
                        "name": "Údaje k balíku byly zadány do systému GLS.",
                        "status": "EXPORTED"
                    }
                ]
            ]
        }
    }
}
```

Události jsou řazené od nejnovější; klíčem objektu `data` je identifikátor zásilky
(`tracking_number`).