Š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
- V nabídce
/rates/getpřečtětelabel_modea podle něj zákazníka informujte, zda bude potřebovat tiskárnu. - Po
POST /shipments/createuložtelabel_modekaždé zásilky. UCARRIERje hotovo — na štítek nečekejte a/shipments/labelnevolejte. - U
PRINTaPRINT_OR_CODEsledujtelabel_statusvPOST /shipments/detail(neboGET /shipments/list), dokud neníREADY, a pak zavolejtePOST /shipments/label. - U
CODEčtěte odlabel_status: READYkód zpackages[].package_password. - Při
label_status: FAILEDdotazová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_size | Stránka PDF | Štítek | Štítků na stránku | position | Dopravci |
|---|---|---|---|---|---|
A4 (výchozí), alias A4xA6 | A4 | A6, 2×2 | 4 | 1–4 | všichni |
A6, alias A6xA6 | A6 | A6 | 1 | nepoužívá se | všichni |
A4xA7, alias A7 | A4 | A7, 2×4 | 8 | 1–8 | Zásilkovna |
A4xA8, alias A8 | A4 | A8, 4×4 | 16 | 1–16 | Zá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.
Code
Příklad odpovědi /shipments/detail
Zásilka DPD s jednorázovým svozem z adresy — štítek přiveze kurýr:
Code
Zásilka GLS ze svozové adresy po exportu — štítek je připraven ke stažení:
Code
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. |