Zaslat dokumentace
Zaslat API v1

Štítky a jejich stavy

Rozšířená specifikace

Jedná se o rozšířenou specifikaci API dokumentace pro pole label_mode a label_status v objektech Shipment a 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:

PoleVýznamKde ho najdete
label_modekdo štítek dodá — tisknete sami, přiveze kurýr, nebo stačí kód/rates/get (nabídka), /shipments/create, /shipments/detail, /shipments/list
label_statuszda 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:

HodnotaKdo štítek dodáCo udělat
PRINTZaslat — odesílatel štítek vytiskne a nalepí na balík.Po label_status: READY stáhněte štítek přes POST /shipments/label.
CARRIERKurý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).
CODENikdo — 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_CODEOdesí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:

HodnotaVýznamCo 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.
FAILEDZá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:

DopravceJednorázový svoz z adresy (ONDEMAND)Svozová adresa (REGULAR, OCCASIONAL)Podání na výdejním místě (pickup_branch)
PPLPRINTPRINTPRINT, s label_less: true CODE
DPDCARRIERPRINTPRINT
GLS, GLS_SKCARRIERPRINTPRINT
UPS, FedExPRINTPRINT—
Zásilkovna—PRINTPRINT
Balíkovna——PRINT_OR_CODE
WeDoCARRIERPRINTPRINT
SPSCARRIERPRINTPRINT
TopTransCARRIERPRINT—
LiftagoCARRIER——

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.

Formáty štítků a pozice na archu

Parametr paper_size endpointu /shipments/label určuje formát stránek výsledného PDF a velikost štítku. Hodnoty A4 a A6 jsou přímo formát stránky (lze je zapsat i jako A4xA6 a A6xA6); u hodnot A4xA7 a A4xA8 (zkráceně A7 a A8) je stránka vždy A4 a část za x udává velikost jednotlivých štítků na ní. Parametr position říká, na kterém místě archu A4 má začít první štítek (počítáno po řádcích zleva doprava), takže lze dotisknout zbytek částečně použitého archu samolepek.

paper_sizeStránka PDFŠtítekŠtítků na stránkupositionDopravci
A4 (výchozí), alias A4xA6A4A6, 2×241–4všichni
A6, alias A6xA6A6A61nepoužívá sevšichni
A4xA7, alias A7A4A7, 2×481–8Zásilkovna
A4xA8, alias A8A4A8, 4×4161–16Zásilkovna

Formáty A4xA7 a A4xA8 lze použít jen pro zásilky Zásilkovny — pro zásilku jiného dopravce vrátí endpoint 400 s popisem v poli error. Pozice mimo rozsah daného formátu vrátí 400 s chybou validace v poli errors. Hodnota paper_size je nezávislá na velikosti písmen.

JSONCode
{ "shipments": ["IZ0123456789", "IZ1234567890"], "format": "pdf", "paper_size": "A4xA7", "position": 5 }

Příklad odpovědi /shipments/detail

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

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

JSONCode
{ "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:

PoleKdeNáhrada
labels_readyShipmentlabel_status: READY. Hodnota false nerozlišuje PENDING od NOT_APPLICABLE.
printableRatelabel_mode jiný než CARRIER.
label_lessShipmentlabel_mode: CODE. Pole label_less se navíc vrací jen vlastníkovi zásilky.
Last modified on