Copy page

Zaslat API v1

Sledování zásilek a stavy

Životní cyklus zásilky

Zásilka prochází stavy v tomto pořadí (číselník 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).

Příklad dotazu

Code
{
    "shipments": ["IZ076151CA1F", "IZ1234567890"]
}

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

Code
{
    "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).