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 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).

Kdy přestat čekat na štítek

Stav zásilky sám neříká, zda štítek vůbec někdy bude — u části služeb ho přiveze kurýr při svozu a Zaslat žádný štítek neposkytuje. Nečekejte proto na stav EXPORTED, ale řiďte se poli label_mode a label_status v odpovědi POST /shipments/detail:

• label_mode: CARRIER (label_status: NOT_APPLICABLE) — štítek přiveze kurýr, nic nestahujte;
• label_status: PENDING — štítek teprve vznikne, dotaz opakujte;
• label_status: READY — štítek stáhněte přes POST /shipments/label;
• label_status: FAILED — štítek se nepodařilo získat, další dotazování nepomůže.

Podrobný postup a přehled dopravců je na stránce Štítky a jejich stavy.

Heslo pro podání (Zásilkovna, Balíkovna, PPL SmartPIN)

U zásilek podávaných na výdejním místě nebo do boxu vybraných dopravců (Zásilkovna, Balíkovna) a u bezštítkových zásilek PPL dopravce přiděluje heslo pro podání — kód, který odesílatel zadá nebo napíše na balík při jeho předání. API ho vrací v objektu Package v poli package_password:

• heslo vzniká až při exportu zásilky k dopravci, tj. je dostupné od stavu EXPORTED — v odpovědi shipments/create je pole ještě null;
• vrací ho POST /shipments/detail a GET /shipments/list, a to pouze vlastníkovi zásilky (nebo při uvedení tokenu objednávky v poli tokens); ostatním se vrací null;
• u vratek heslo předejte zákazníkovi, který balík odnáší na výdejní místo nebo vkládá do boxu.

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).