Copy page

Zaslat API v1

Štítky a jejich stavy

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:

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

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.

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:

Code
{
    "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í:

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