API Reference

Pro správnou funkčnost metod je nutné udržet posloupnost dle diagramu. To znamená, že je nutné nejdříve zásilky vložit (v této fázi můžete zásilky rušit a editovat), a poté zásilky uzavřít. Tisk štítků a svozových protokolů lze realizovat pouze pro uzavřené zásilky.

Terminologie

V aplikaci Štíteknabalík.cz, API a při CSV importech používáme sjednocenou terminologii. Bližší popis výrazů je v následující tabulce.

Český výraz	Anglický výraz	API pole	Podrobnosti
Zásilka	Delivery	`delivery`
Balík	Package	`package`	Zásilka má jeden a více balíků.
Přepravce	Agent	`agent`	Např.: Česká pošta, GLS, PPL, Zásilkovna,..
Přepravní služba	Delivery Type	`deliveryType`	Např.: Balík do ruky, Balík na poštu, Výdejní místa,..
Doplňková služba	Extra Service	`extraService`	Např.: Dobírka, Připojištění, SMS Avízo,..
Štíteknabalík.cz ID zásilky	Delivery Štíteknabalík.cz ID	`deliveryId`	ID zásilky v systému Štíteknabalík.cz.
Číslo zásilky	Delivery Number	`deliveryNumber`	Trekovací číslo zásilky.
Číslo balíku	Package Number	`packageNumber`	Číslo balíku, který je součástí zásilky (většinou je shodné s číslem zásilky).
Svozové místo	Collection Place	`collectionPlace`	Svozové místo kde bude přepravce vyzvedávat zásilky.
Odběrné místo	Pickup Place	`pickupPlace`	Odběrné místo pro doručení zásilek (dropoff point, pickup point, parcelshop, atd.)
Zpětná zásilka	Back Delivery	-	Zásilka, která putuje od zákazníka zpět k Vám (vetšinou na adresu Vašeho svozového místa).
Přímá zásilka	Direct Delivery	-	Zásilka, která je zaslána z adresy na adresu. Tedy NENÍ odeslána z Vašeho standardního svozového místa.
Výměnná zásilka	Swap Delivery	-	Zásilka, která je poslána příjemci s podmínkou, že bude vyměněná za původní zásilku, kterou Vám doručí zpět.
Vícekusá zásilka	Multipackage Delivery	-	Zásilka, která obsahuje více než jeden balík.

Podporované metody

Endpointy pro https://rest.stiteknabalik.cz

Path	Podporované HTTP metody	OAuth Scope	Popis endpointu
/	GET	-	Speciální neverzovaný testovací zdroj bez nutné autentizace
/v4/deliveries	POST - import nových zásilek GET - získání informací o zásilkách PATCH - uzavření zásilek PUT - Úprava zásilek DELETE - rušení zásilek	`deliveries`	Práce s jednou nebo několika zásilkami najednou
/v4/deliveries/tickets	GET	`deliveries`	Vygenerování štítků do PDF souboru pro jednu nebo více zásilek
/v4/deliveries/zpl	GET	`deliveries`	Vygenerování štítků do v ZPL formátu pro jednu nebo více zásilek
/v4/deliveries/traces	GET	`deliveries`	Track and trace stavy pro jednu nebo více zásilek
/v4/collection-protocols	POST - import nových zásilek GET - získání informací o zásilkách	`collection-protocols`	Vytvoření svozového protokolu včetně vygenerování PDF souboru
/v4/collection-places	GET	`collection-places`	Získání informací o všech aktivních svozových místech
/v4/list	GET	`list`	Sada endpointů pro získání číselníků (seznamy přepravců, doplňkových služeb, stavů zásilek, formátů štítků apod.)

Deliveries / Zásilky

deliveries POST

Import zásilek do systému Štíteknabalík.cz

Zásilky importované do Štíteknabalík.cz budou vytvořené se stavem 1_0_0 - Rozpracované. V tomto stavu zatím nejsou zásilky odeslány k přepravci. To se děje až v dalším kroku pomocí metody PATCH.

Při importování zásilek probíhají základní formátovací validace předávaných hodnot.
Zda-li zásilka splňuje kriteria daná přepravcem je zjišťováno až při samotném uzavírání zásilek metodou PATCH.

Ukázka HTTP Požadavku (REQUEST)

Dle příkladu níže se v těle požadavku se mohou objevit údaje z následující tabulky. Pořadí polí v jednotlivých zásilkách není zaručeno a může se měnit. Typy hodnot v požadavku jsou pouze informativní, tedy je jedno zda je v JSON požadavku 2.3 nebo "2.3".

K URI lze připojit query parametr fields a specifikovat jaká data zásilek se mají objevit v odpovědi stejně jako u metody GET.

Endpoint

POST: https://rest.stiteknabalik.cz/v4/deliveries

Ukázka hlavičky

Host => rest.stiteknabalik.cz
Authorization => Basic b66f6b694032e4271710deb21d7a7d703c974854a9a09a72825115bce69cb369
Accept => application/json
Content-type => application/json

Ukázka těla

{
    "deliveries": [
        {
            "variableSymbol": "12345678",
            "cod": 1200,
            "codCurrency": "CZK",
            "value": 2000,
            "valueCurrency": "CZK",
            "packages": [
                {
                    "barcode": null,
                    "weight": 3,
                    "length": 15,
                    "width": 40,
                    "height": 20,
                    "containerCode": "EUP",
                    "containerItems": 5
                }
            ],
            "agent": "GLS",
            "deliveryType": "BP",
            "sender": {
                "type": "collectionPlace",
                "collectionPlace": "sokolovska-21"
            },
            "recipient": {
                "firstname": null,
                "surname": "Společnost s.r.o.",
                "contactPerson": null,
                "phone": "+420777111000",
                "email": "email@recipient.cz",
                "type": "address",
                "address": {
                    "city": "Praha",
                    "street": "Revoluční 11",
                    "postalCode": "11000",
                    "state": "CZ"
                }
            },
            "extraServices": [
                {
                    "code": "cod",
                    "arguments": []
                },
                {
                    "code": "email_advice_unload",
                    "arguments": {
                        "email": "email@recipient.com"
                    }
                },
                {
                    "code": "sms_advice_unload",
                    "arguments": {
                        "phone": "+420777111000"
                    }
                }
            ],
            "ticketNote": "Dodat do 2. podlaží",
            "externalId": "1234567"
        }
    ]
}

Popis polí požadavku (REQUEST)

Pole	Datový typ	Povinné	Validace	Popis
`recipient` ^1] `sender`	string[]	Povinné		Pole odesílatele i příjemce jsou typově shodná, tzn. obsahují stejné povinné a nepovinné parametry.
↳ `recipient\|sender.type` ^2]	string	Povinné	klíč číselníku, max 15 zn.	Typ příjemce. Rozhoduje o dalších polích, které je nutné pro příjemce uvést. Povolené hodnoty jsou: address, collectionPlace, pickUpPlace.
↳ `recipient\|sender.address`	string[]	Podmíněno		Pole adresu pokud je příjemce či odesílatel na běžné adrese. Parametry adresy jsou : `street`, `streetNumber`, `state`,`city`, `postalCode`;
↳ `recipient\|sender.address.street`	string	Povinné	max 110 zn. včetně č.p.	Název ulice; Musí obsahovat číslo popisné, pokud není uvedeno ve `streetNumber`
↳ `recipient\|sender.address.streetNumber`	string	Podmíněno		Číslo popisné; Povinné pouze pokud není uvedeno za mezerou ve `street`
↳ `recipient\|sender.address.state`	string	Povinné	ISO 3166-2, 2 zn.	Stát ve formátu ISO 3166-2 , tedy například CZ či SK.
↳ `recipient\|sender.address.city`	string	Povinné	max 127 zn.	Město
↳ `recipient\|sender.address.postalCode`	string	Povinné	validace podle státu, max 15 zn.	PSČ; Bez mezer
↳ `recipient\|sender.collectionPlace` ^1]	string	Podmíněno	klíč číselníku, max 63 zn.	Identifikátor svozového místa pokud je příjemce či odesílatel svozové místo
↳ `recipient\|sender.pickUpPlace` ^1]	string	Podmíněno	klíč číselníku, max 63 zn.	Identifikátor odběrného místa pokud je příjemce odběrné místo (Pickup, Dropoff, Parcelshop)
↳ `recipient\|sender.firstname`	string	Nepovinné	max 63 zn.	Jméno (vynechte, pokud jde o firmu)
↳ `recipient\|sender.surname`	string	Povinné	max 127 zn.	Přijmení nebo název firmy
↳ `recipient\|sender.contactPerson`	string	Nepovinné	max 127 zn.	Kontaktní osoba - Jméno a příjmení kontaktní osoby (pokud jde o firmu)
↳ `recipient\|sender.email` ^1]	string	Podmíněno	RFC 2822, max 255 zn.	Email - Nemusí být vyplněno, pokud je vyplněn telefon
↳ `recipient\|sender.phone` ^1]	string	Podmíněno	Formát dle státu. Vždy s předvolbou a bez mezer.	Telefon - Nemusí být vyplněno, pokud je vyplněn email.
`value`	float	Povinné	0.00	Hodnota zásilky v měně uvedené v klíči `valueCurrency`. Desetinná místa se oddělují tečkou.
`valueCurrency`	string	Povinné	ISO_4217	Měna hodnoty zásilky ve formátu ISO 4217 , tedy například CZK či EUR
`cod`	float	Nepovinné	0.00	výše dobírky zásilky v měně uvedené v klíči `codCurrency`
`codCurrency`	string	Podmíněno	ISO_4217	Měna dobírky zásilky ve formátu ISO 4217 , tedy například CZK či EUR, povinné, pokud je vyplněna dobírka
`variableSymbol`	string	Podmíněno	max 10 zn.	Variabilní symbol pro platbu dobírky (povinné, pokud je vyplněna dobírka `cod` a `codCurrency`)
`packages.weight` ^3]	float	Nepovinné	0.00	Hmotnost balíku v Kg. Desetinná místa se oddělují tečkou.
`packages.height` ^3]	int	Podmíněno		Výška balíku v cm. Pokud uvedete vyplňte i zbývající rozměry.
`packages.length` ^3]	int	Podmíněno		Délka balíku v cm. Pokud uvedete vyplňte i zbývající rozměry.
`packages.width` ^3]	int	Podmíněno		Šířka balíku v cm. Pokud uvedete vyplňte i zbývající rozměry.
`packages.containerCode` ^4]	string	Podmíněno	klíč číselníku, 3 zn.	Cargo jednotka. Povinné pouze u `deliveryType`, které podporují cargo přepravu. Seznam cargo jednotek naleznete v číselnících.
`packages.containerItems` ^4]	int	Podmíněno		Počet cargo jednotek, které mají shodné parametry. Pouze pokud exportujete cargo zásilku s `packages.containerCode`. Minimum je 1. Maximum stanovuje konkrétní přepravce.
`deliveryType`	string	Povinné	klíč číselníku, 2 zn.	Přepravní služba - Identifikátor. Seznam identifikátorů naleznete v příslušném číselníku.
`agent`	string	Povinné	klíč číselníku, max 7 zn.	Přepravce - Identifikátor. Seznam identifikátorů naleznete v příslušném číselníku.
`extraServices.code`	string	Povinné	klíč číselníku, max 63 zn.	Doplňkové služby - Identifikátor. Seznam identifikátorů naleznete v příslušném číselníku.
`extraServices.arguments`	string	Nepovinné	dle parametru, max 255 zn.	Argumenty pro doplňkovou službu. Seznam požadovaných argumentl jednotlivých služeb je součástí stejného číselníku jako doplňkové služby.
`ticketNote`	string	Nepovinné	max 255 zn.	Poznámka na štítek. Doporučujeme co nejkratší poznámky (cca do 35 znaků).
`externalId`	string	Nepovinné	max 127 zn.	Externí identifikátor zásilky, slouží k Vaší identifikaci zásilky. Tento klíč lze také využít k získávání informací o zásilkách.
`platformKey`	string	Nepovinné	max 255 zn.	Identifikátor platformy. Nechte prázdné. Vyplňují pouze poskytovatelé systémů CMS, WMS, OpenSource a doplňků pro marketplaces na základě dohody s naší technickou podporou.

1] Objekty recipient a sender mají identické chodvání a parametry.

2] Hodnoty pro typ příjemce recipient.type a typ odesílatele sender.type rozhodují o dalších polích, které je nutné pro příjemce nebo odesílatele uvést:

address - Pro tento typ je nutné specifikovat údaje dané osoby (recipient.firstname, recipient.surname, recipient.address.street, recipient.address.city, recipient.address.postalCode,...).
collectionPlace - Tento typ požaduje pouze identifikátor svozového místa v poli collectionPlace. Pole související s adresou již neposíláte.
pickUpPlace - Tento typ požaduje identifikátor odběrného místa v poli pickUpPlace a údaje příjemce (recipient.firstname, recipient.surname, recipient.email, recipient.phone).

3] Může být povinné u některých přepravců. Dozvíte se z hlášky při uzavírání zásilek. Pro doplnění hodnoty můžete použít metodu deliveries/PUT.

4] Parametry pro cargo přepravu. Pro zásilky mimo cargo se parametry neuvádějí nebo se zasílají jako null.

Implicitní doplňkové služby

Tyto typy rozhodují o implicitním použití doplňkových služeb přímá a zpětná zásilka:

Běžné svozové zásilky jsou ze svozového místa ➡ na ➡ adresu (recipient.type má hodnotu address a sender.type má hodnotu collectionPlace).
Přímé zásilky jsou z adresy ➡ na ➡ adresu (recipient.type a sender.typedocs.js mají hodnotu address).
Zpětné zásilky jsou z adresy ➡ na ➡ svozové místo. (recipient.type má hodnotu collectionPlace a sender.type má hodnotu address).

Aby k aplikaci zpětné a přímé zásilky došlo dle výše uvedených pravidel, je nutné mít pro daného přepravce u svozového místa vyplněný typ svozu (pravidelný|nepravidelný svoz). Svozové místo bez typu svozu se chová stejně jako obyčejná adresa - například přeprava ze svozového místa bez typu svozu na adresu použije přímou zásilku. Výjimkou jsou přepravci, kteří nerozlišují svozové a nesvozové zásilky (například TNT) - u nich vůbec neexistují doplňkové služby zpětná a přímá zásilka.

Ukázka úspěšné odpovědi (RESPONSE)

Odpověď zachovává standardní strukturu (viz výše). V poli data naleznete údaje z požadavku + další doplňkové informace jako nevyplněné položky a další. Údaje v odpovědi se mohou mírně lišit od těch, jenž byly v požadavku. Například mohlo dojít k mírným formátovacím úpravám jako je odebranání mezer, změně typu hodnoty či podobným změnám.

Ukázka hlavičky

HTTP/1.1 201
X-Frame-Options => SAMEORIGIN
Vary => X-Requested-With
X-Powered-By => Lean Mapper
X-Robots-Tag => noindex
Content-Type => application/json; charset=UTF-8
ETag => "5887cca6c93d143c689ced8bc5080651"
Location => http://rest.stiteknabalik.cz/v4/deliveries

Ukázka těla

{
    "code": 201,
    "status": "success",
    "message": "Deliveries successfully created!",
    "data": [
        {
            "agent": "GLS",
            "closed": "2020-09-23T15:05:40+02:00",
            "cod": 1200,
            "codCurrency": "CZK",
            "created": "2020-09-22T13:21:08+02:00",
            "deliveryId": 15023456,
            "deliveryMetaData": null,
            "deliveryNumber": null,
            "deliveryType": "BP",
            "externalId": "1234567",
            "foxdeliDetailUrl": "https://app.stiteknabalik.cz/deliveries/15023456",
            "foxdeliTrackingUrl": "https://tt.stiteknabalik.cz/status/mujshop/15023456?sig=NGVjMjdjMmVhYjJiAtc5MGVmMzFmNjcyMzBlZjE5ZDliN2MxZjU1YmY3ZWE0MjQ1ZWUwZjQ4ZDg5MjJhZTZiNQ%3D%3D",
            "extraServices": [
                {
                    "code": "cod",
                    "arguments": []
                },
                {
                    "code": "email_advice_unload",
                    "arguments": {
                        "email": "email@recipient.com"
                    }
                },
                {
                    "code": "sms_advice_unload",
                    "arguments": {
                        "phone": "+420777111000"
                    }
                }
            ],
            "important": false,
            "inDelay": false,
            "notDelivered": 0,
            "notPickedUp": 0,
            "packages": [
                {
                    "barcode": "",
                    "weight": 3,
                    "length": 15,
                    "width": 40,
                    "height": 20
                }
            ],
            "recipient": {
                "firstname": null,
                "surname": "Společnost s.r.o.",
                "contactPerson": null,
                "phone": "+420777111000",
                "email": "email@recipient.cz",
                "type": "address",
                "address": {
                    "city": "Praha",
                    "street": "Revoluční 11",
                    "postalCode": "11000",
                    "state": "CZ"
                }
            },
            "sender": {
                "type": "collectionPlace",
                "collectionPlace": "sokolovska-21"
            },
            "source": 3,
            "sourceName": "API",
            "state": "1.0.0",
            "stateName": "Rozpracované",
            "stateChanged": "2020-09-11T07:09:39+02:00",
            "stateCategory": "1",
            "stateCategoryName": "Rozpracované",
            "stateSubcategory": "1.0",
            "stateSubcategoryName": "Rozpracované",
            "ticketNote": "Dodat do 2. podlaží",
            "value": 2000,
            "valueCurrency": "CZK",
            "variableSymbol": "12345678",
            "monitored": false
        }
    ]
}

Popis "vybraných" polí úspěšné odpovědi (RESPONSE)

Pole	Datový typ	Popis
`data[].deliveryId`	int	Interní číslo zásilky. Pomocí tohoto čísla můžete získávat informace o zásilce přes ostatní metody v naší API.
`data[].deliveryNumber`	string	Číslo zásilky přepravce - je doplněno až po uzavření zásilky. Většinou je jde také o "trekovací číslo".
`data[].created`	string	Datum vytvoření zásilky.
`data[].packages.barcode`	string	Čárový kód balíku (bude i na štítku). Oproti deliveryNumber se většinou liší v kontrolní číslici.
`data[].important`	bool	Flag, který reflektuje problematickou zásilku (například velké zpoždění, nepřevzetí, apod.).
`data[].inDelay`	bool	Flag, který reflektuje zpožděnou zásilku (oproti standardnímu času doručení ostaních zásilek stejného přepravce).
`data[].source`	int	Id původu vzniku zásilky, možné hodnoty jsou: prázdné – Neznámý původ vytvoření zásilky 1 - manuální 2 - CSV 3 - API
`data[].sourceName`	string	Pojmenování původu vzniku zásilky.
`data[].state`^1]	string	Hlavní stav zásilky.
`data[].stateName`^1]	string	Název hlavního stavu zásilky.
`data[].stateChanged`^1]	string	Čas změny stavu (v případě exportu jde o čas vytvoření záznamu ve Štíteknabalík.cz).
`data[].stateCategory`^1]	string	Kategorie stavu zásilky.
`data[].stateCategoryName`^1]	string	Název kategorie stavu zásilky.
`data[].stateSubcategory`^1]	string	Podkategorie stavu zásilky.
`data[].stateSubcategoryName`^1]	string	Název podkategorie stavu zásilky.
`data[].foxdeliDetailUrl`	string	Url detailu zásilky v aplikaci Foxdeli.com (vyžaduje přihlášení)
`data[].foxdeliTrackingUrl`	string	Url detailu zásilky vedoucí na brandovanou Track & Trace stránku (dle licence)
`data[].monitored`	bool	Indikace zda-li se zásilka chová jako monitorovaná zásilka nebo standardní. ^2]

1] Pole se týkají sledování Track&Trace stavů. Číselníky stavů naleznete zde.

2] Monitorované zásilky jsou určené pouze pro sledování stavů Track & Trace a jsou vytvořeny metodou monitored-deliveries POST. Více zde.

Validace a chybové kódy

V případě validační chyby je vrácena odpověď s HTTP kódem 422 a popisem chyb se standardní strukturou, viz následující příklad. V takovém případě nedojde k vložení žádné z vkládaných zásilek a je nutné chyby opravit a pokusit se o vložení znovu. Díky chybové odpovědi můžete snadno detekovat, u jakých zásilek k chybě došlo (dle čísla v závorce u položky field) a zbylé zásilky vložit v dalším požadavku. Ty zásilky, u kterých došlo k chybě si pravděpodobně budete ve svém systému chtít označit jako chybné a opravit je. Většina chyb má překlad do češtiny - tu lze vyžádat použitím dříve zmíněné HTTP hlavičky Accept-language: cs.

Ukázka chybové odpovědi (RESPONSE)

Pokud dojde k dosažení limitu zásilek dle aktuální licence, je vrácen HTTP kód 403.

Ukázka hlavičky

HTTP/1.1 422
X-Frame-Options => SAMEORIGIN
Vary => X-Requested-With
X-Powered-By => Lean Mapper
X-Robots-Tag => noindex
Content-Type => application/json; charset=UTF-8

Ukázka těla

{
    "code": 422,
    "status": "error",
    "message": "Validation failed",
    "errors": [
        {
            "message": "Unknown extra service \"email_advice\" for given delivery type and address combination. Allowed codes are => email_advice_unload, sms_advice_unload",
            "field": "[0].extraServices[0].code",
            "value": "email_advice"
        }
    ]
}

Vkládání více zásilek v jednom požadavku

Je nevhodné a neefektivní vkládat více zásilek pomocí několika HTTP požadavků. Raději využijte jeden požadavek s více položkami uvnitř pole deliveries. To samozřejmě znamená, že ošetření údajů Vašich zásilek musí být dostatečně striktní, aby zásilky prošly validačními kontrolami v našem API.
Pokud přeci jen k validační chybě dojde, je možné z odpovědi získat konkrétní zásilky, kde se vložení nezdařilo a pro zbylé zásilky požadavek zopakovat.

Další informace k odpovědi

V úpěšné odpovědi naleznete hlavičku Location, která vede na stránku s právě vytvořenými zásilkami. Taktéž je přítomna hlavička ETag sloužící ke cacheování GET požadavků.

deliveries PATCH

Uzavření importovaných zásilek v rámci jednoho svozového místa.

Při této operaci se odesílají data k jednotlivým přepravcům.

Metoda vrací detaily svozu (u svozových míst, která nemají zaškrtnutý pravidelný svoz), dále čísla zásilek u přepravce a detaily zásilek.

Zásilky uzavřené ve Štíteknabalík.cz spadnou do stavu 2_0_0 - K odeslání a to je okamžik, kdy přepravce získává informaci o zásilce a požadavku na vyzvednutí (svoz). Do dalšího stavu 3_0_0 - Odeslané se již zásilka dostává automaticky na základě získání informace z API přepravce o převzetí zásilky kurýrem (většinou jde o čas prvního scanu čárového kódu ze štítku).

Ukázka HTTP Požadavku (REQUEST)

Požadavek přijímá pole deliveries, které může obsahovat jednu nebo více zásilek k uzavření.

Každá zásilka musí obsahovat ID zásilky a požadavek o uzavření s kladnou hodnotou true. Tedy klíče deliveryId a closed. Při této akci může na základě nastavení Vašeho účtu dojít k objednání svozu u přepravce.

K URI lze připojit query parametr fields a specifikovat jaká data zásilek se mají objevit v odpovědi stejně jako u metody GET.

Endpoint

PATCH: https://rest.stiteknabalik.cz/v4/deliveries

Ukázka hlavičky

Host => rest.stiteknabalik.cz
Authorization => Basic b66f6b694032e4271710deb21d7a7d703c974854a9a09a72825115bce69cb369
Accept => application/json
Content-type => application/json

Ukázka těla

{
    "deliveries": [
        {
            "deliveryId": 15023456,
            "closed": true
        }
    ]
}

Popis polí požadavku (REQUEST)

Pole	Datový typ	Povinné	Popis
`deliveryId`	int	Povinné	Štíteknabalík.cz ID zásilky, které jste získali při vytváření zásilky metodou POST.
`closed`	bool	Povinné	Flag pro uzavření zásilky. Pokud posíláte hromadný příkaz pro uzavření zásilek, budou uzavřeny pouze zásilky s hodnotou `true`.
`?fields`	string	Nepovinné	Parametr se posílá v URL. Pro více informací nalistujte metodu deliveries/GET

Ukázka úspěšné odpovědi (RESPONSE)

Všechny objednané svozy jsou uvedeny v odpovědi a jsou v ní také zahrnuta data všech uzavíraných zásilek včetně doplněných čísel zásilek přepravců viz. příklad odpovědi.

Struktura výpisu zásilek je totožná jako u odpovědi POST požadavku.

Ukázka hlavičky

HTTP/1.1 200
X-Frame-Options => SAMEORIGIN
Vary => X-Requested-With
X-Powered-By => Lean Mapper
X-Robots-Tag => noindex
Content-Type => application/json; charset=UTF-8

Ukázka těla

{
    "code": 200,
    "status": "success",
    "message": "Deliveries successfully closed!",
    "data": {
        "collectionOrders": [
            {
                "agent": "GLS",
                "scheduled": "2020-09-23",
                "collectionPlace": "sokolovska-21"
            }
        ],
        "deliveries": [
            {
                "agent": "GLS",
                "closed": "2020-09-23T15:05:40+02:00",
                "cod": 1200,
                "codCurrency": "CZK",
                "created": "2020-09-22T13:21:08+02:00",
                "deliveryId": 15023456,
                "deliveryMetaData": null,
                "deliveryNumber": "12859588454",
                "deliveryType": "BP",
                "externalId": "1234567",
                "foxdeliDetailUrl": "https://app.stiteknabalik.cz/deliveries/15023456",
                "foxdeliTrackingUrl": "https://tt.stiteknabalik.cz/status/mujshop/15023456?sig=NGVjMjdjMmVhYjJiAtc5MGVmMzFmNjcyMzBlZjE5ZDliN2MxZjU1YmY3ZWE0MjQ1ZWUwZjQ4ZDg5MjJhZTZiNQ%3D%3D",
                "extraServices": [
                    {
                        "code": "cod",
                        "arguments": []
                    },
                    {
                        "code": "email_advice_unload",
                        "arguments": {
                            "email": "email@recipient.com"
                        }
                    },
                    {
                        "code": "sms_advice_unload",
                        "arguments": {
                            "phone": "+420777111000"
                        }
                    }
                ],
                "important": false,
                "inDelay": false,
                "notDelivered": 0,
                "notPickedUp": 0,
                "packages": [
                    {
                        "barcode": "12859588454",
                        "weight": 3,
                        "length": 15,
                        "width": 40,
                        "height": 20,
                        "containerCode": "EUP",
                        "containerItems": 5
                    }
                ],
                "recipient": {
                    "firstname": null,
                    "surname": "Společnost s.r.o.",
                    "contactPerson": null,
                    "phone": "+420777111000",
                    "email": "email@recipient.cz",
                    "type": "address",
                    "address": {
                        "city": "Praha",
                        "street": "Revoluční 11",
                        "postalCode": "11000",
                        "state": "CZ"
                    }
                },
                "sender": {
                    "type": "collectionPlace",
                    "collectionPlace": "sokolovska-21"
                },
                "source": 3,
                "sourceName": "API",
                "state": "2.0.0",
                "stateName": "K odeslání",
                "stateChanged": "2020-09-23T15:05:40+02:00",
                "stateCategory": "2",
                "stateCategoryName": "K odeslání",
                "stateSubcategory": "2.0",
                "stateSubcategoryName": "K odeslání",
                "ticketNote": "Dodat do 2. podlaží",
                "value": 2000,
                "valueCurrency": "CZK",
                "variableSymbol": "12345678",
                "monitored": false
            }
        ]
    }
}

Popis "vybraných" polí úspěšné odpovědi (RESPONSE)

Pole	Datový typ	Popis
`data[].collectionOrders[].agent`	string	Zkratka přepravce, u něhož byl svoz objednán
`data[].collectionOrders[].scheduled`	string	Datum objednání svozu ve formátu YYYY-MM-DD, o přesném času svozu budete informováni kurýrem.
`data[].collectionOrders[].collectionPlace`	string	Identifikátor svozového místa, na jehož adresu byl objednán svoz.
`deliveries[].deliveryNumber`	string	Číslo zásilky přepravce - je doplněno až po uzavření zásilky. Většinou je jde také o "trekovací číslo".
`deliveries[].packages.barcode`	string	Čárový kód balíku (bude i na štítku). Oproti deliveryNumber se většinou liší v kontrolní číslici.

Pozor

Uzavírat lze pouze zásilky ze stejného svozového místa a stejného přepravce. Všechny zásilky musejí být doposud neuzavřené a nezrušené.

Validace a chybové kódy

Při této operaci se odesílají data k jednotlivým přepravcům.
V případě nenalezení nějaké zásilky je vrácen HTTP kód 404. Při pokusu o přístup k zásilce s nedostatečným oprávněním je vrácen HTTP kód 403.
Pokud dojde validační chybě (ať již u nás nebo na straně přepravce), je vrácen kód 422.

Jak funguje validace

Vyjma základní validace formátů, ponechává systém Štíteknabalík.cz validaci zásilek na přepravcích. Správnost zadaných údajů je ověřena až při samotném uzavření zásilky metodou deliveries/PATCH.
Pokud je zásilka nebo více zásilek odmítnuto přepravcem, jsou veškeré informace předány zpět přes API přímo e-shopu. Pro následnou opravu údajů je možné poslat opravenou zásilku znovu, stejně jako v metodě deliveries/POST, akorát s použitím metody PUT, která existující zásilku ve Štíteknabalík.cz opraví.
Ihned potom je možné zásilku znovu exportovat k přepravci metodou PATCH.

deliveries PUT

Editace doposud neuzavřených zásilek.

Popis požadavku (REQUEST)

V požadavku je nutné vyplnit všechny povinné údaje zásilky jako u POST metody a přidat klíč deliveryId (k zásilce do pole deliveries[].deliveryId).

K URI lze připojit query parametr fields a specifikovat jaká data zásilek se mají objevit v odpovědi stejně jako u metody GET.

Popis odpovědi (RESPONSE)

V poli data jsou totožné údaje jako u POST metody. V případě, že uvedete v hlavičce If-Match hodnotu ETagu pro editované zásilky a došlo ke změně dat zásilky (od doby získání daného ETagu), úprava nebude provedena a bude vrácen HTTP kód 412.
Díky tomuto mechanizmu je možné kontrolovat neočekávané změny zásilek na straně webové aplikace. Pro správné fungování je třeba použít ETag získaný pro všechna data zásilky či zásilek (ETag byl získán GET požadavkem bez query parametru fields).

Validace a chybové kódy

Validace je totožná jako u metody POST s tím, že se ještě validuje klíč deliveryId. Validační chyby jsou označeny HTTP kódem 422. Odpověď má stejnou strukturu jako u vkládání zásilek.
Nelze upravovat uzavřené a zrušené zásilky.

deliveries GET

Získání informací o zásilkách

Ukázka HTTP Požadavku (REQUEST)

Nejčastější a nejrychlejší je hledání dle parametru deliveryId. Tento parametr musí obsahovat Štíteknabalík.cz ID čísla zásilek, která jste měli možnost získat v POST odpovědi při importu zásilek. Jednotlivá čísla zásilek musejí být oddělena čárkou.

Pořadí čísel zásilek v tomto parametru neurčuje pořadí zásilek v odpovědi!.

Pomocí query parametru fields můžete definovat jaké parametry zásilky chcete v odpovědi. Více hodnot je opět odděleno čárkou. Možné hodnoty tohoto parametru jsou: deliveryId, externalId, deliveryNumber, state, stateCategory, stateSubcategory, stateName, stateCategoryName, stateSubcategoryName, value, valueCurrency, closed, cod, codCurrency, source, sourceName, variableSymbol, ticketNote, created, agent, deliveryType, extraServices, recipient, sender, packages, foxdeliDetailUrl, agentTrackingUrl.

Neplatné hodnoty jsou ignorovány. Pořadí polí v tomto parametru neurčuje pořadí polí v odpovědi! Pokud je tento parametr vynechán, jsou vráceny všechny údaje o zásilce.

Endpoint otevřít

GET: https://rest.stiteknabalik.cz/v4/deliveries?deliveryId=15023456,15023457&fields=deliveryId,externalId,deliveryNumber,state,stateName,stateCategory,stateCategoryName,foxdeliDetailUrl,agentTrackingUrl

Ukázka hlavičky

Host => rest.stiteknabalik.cz
Authorization => Basic b66f6b694032e4271710deb21d7a7d703c974854a9a09a72825115bce69cb369
Accept => application/json

Ukázka úspěšné odpovědi (RESPONSE)

Ukázka hlavičky

HTTP/1.1 200
X-Frame-Options => SAMEORIGIN
Vary => X-Requested-With
X-Powered-By => Lean Mapper
X-Robots-Tag => noindex
Content-Type => application/json; charset=UTF-8
Cache-Control => max-age=0
Expires => Thu, 24 Sep 2020 13:08:01 GMT
ETag => "5887cca6c93d143c689ced8bc5080651"

Ukázka těla

{
    "code": 200,
    "status": "success",
    "message": "Deliveries successfully retrieved.",
    "data": [
        {
            "agentTrackingUrl": "https://gls-group.eu/CZ/cs/sledovani-zasilek?match=1285958845412859588454",
            "deliveryId": 15023456,
            "externalId": "1234567",
            "deliveryNumber": "12859588454",
            "state": "6.0.0",
            "stateName": "Zrušeno",
            "stateCategory": "6",
            "stateCategoryName": "Zrušeno",
            "foxdeliDetailUrl": "https://app.stiteknabalik.cz/deliveries/15023456"
        },
        {
            "agentTrackingUrl": "https://gls-group.eu/CZ/cs/sledovani-zasilek?match=12859588455",
            "deliveryId": 15023457,
            "externalId": 1234568,
            "deliveryNumber": "12859588455",
            "state": "3.1.2",
            "stateName": "Na doručení dnes",
            "stateCategory": "3",
            "stateCategoryName": "Doručované",
            "foxdeliDetailUrl": "https://app.stiteknabalik.cz/deliveries/15023457"
        }
    ]
}

Popis dalších polí odpovědi (RESPONSE) ^1]

Pole	Datový typ	Popis
`agentTrackingUrl`	string	Aktuální odkaz na track and trace stránku přepravce pro tuto zásilku. Odkaz se může v průběhu doručování měnit v závislosti na tom jaký přepravce zásilku zrovna převáží (například v zahraničí). Odkaz bude vrácen pouze v případě, že zásilka byla uzavřena a Štíteknabalík.cz zná tracking number od přepravce.

1] V metodě GET můžete získat všechny parametry z metody POST.

Hledání dle ostatních parametrů zásilky

V případě, že potřebujete přesnější vyhledávání zásilek je možné hledat i podle dalších parametrů.
Všechna požadovaná kritéria jsou vyhodnocena s logickým operátorem AND. Parametry jsou hledány fulltextově nebo výčtem hodnot - v tabulce níže vidíte klíče s jejich předdefinovaným způsobem hledání. Hledání dle výčtu dosáhnete oddělením hodnot čárkou, stejně jako u standardního parametru deliveryId. Navíc je možné libovolný z těchto klíčů hledat porovnáním s nějakou hodnotou pomocí prefixu > nebo <, viz příklady níže. Tedy například všechny zásilky s výší dobírky přesahující hodnotu 5000. Toto hledání potlačuje výchozí způsob hledání - nedochází tedy k fulltextovému hledání ani nelze použít výčet.

Typ hledání	Klíče
fulltextové	`(sender\|recipient).contactPerson`, `(sender\|recipient).firstname`, `(sender\|recipient).surname`, `(sender\|recipient).email`, `(sender\|recipient).phone`, `ticketNote`, `created`
výčtem	`deliveryId`, `externalId`, `agent`, `deliveryType`, `deliveryNumber`, `state`, `stateCategory`, `stateSubcategory`, `value`, `valueCurrency`, `deliveryId`, `packages.weight`, `packages.width`, `packages.height`, `packages.length`, `cod`, `codCurrency`, `source`, `variableSymbol`

Příklady hledání (query parametry v URL)

Query string	Popis
`?deliveryId=>10441`	Všechny zásilky s vyšším Štíteknabalík.cz Id než 10441 (tzn. novější než daná zásilka) - vhodné pro synchronizaci zásilek vložených manuálně či pomocí CSV s vaším systémem.
`?externalId=>B5007`	Všechny zásilky s vyšším externím identifikátorem než B5007 (lexikograficky).
`?created=2014-12-24`	Zásilky vytvořené na štědrý den v libovolný čas.
`?deliveryNumber=M89`	Fulltextové hledání dle čísla zásilky přepravce.
`?value=>10000&valueCurrency=CZK`	Zásilky s hodnotou vyšší než 10 000 Kč.
`?value[]=>10000&value[]=<20000&valueCurrency=CZK`	Zásilky s hodnotou v rozmezí 10 000 - 20 000 Kč.
`?variableSymbol=1234567890,9876543210`	Zásilky s variabilním symbolem 1234567890 nebo 9876543210.

HTTP Cacheování

V případě, že se opakovaně dotazujete na stejný zdroj se stejným nastavením filtrování i parametru fields, doporučujeme uvádět dříve získaný obsah hlavičky ETag (je součástí odpovědi na všechny GET požadavky) v hlavičce If-None-Match. V takovém případě, pokud nedošlo od Vašeho posledního dotazu k žádné změně zásilky, bude vrácen HTTP kód 304 a nebudou zbytečně přenášena žádná data (tělo odpovědi bude prázdné). Princip je totožný jako u kořenového zdroje .

Validace a chybové kódy

V případě nenalezení žádné vlastní zásilky dle hledacích kritérií je vrácen HTTP kód 404.
Pozor na případy, kdy vyhledáváte například podle několika deliveryId a některé z nich jsou platné a jiné neplatné - v takovém případě je vrácen HTTP kód 200 a v odpovědi jsou pouze existující zásilky.

Při získávání informací o velkém množství zásilek mějte na paměti, že délka URL je omezena na cca 8000 bytů. V takovém případě je vrácena chyba s HTTP kódem 414 a obsah není v požadovaném formátu. Pro požadavky na velké množství zásilek se i čas zpracování může výrazně prodloužit, doporučujeme tedy dotazovat se pouze na potřebné zásilky a pouze na potřebné položky.

Omezení

Maximální počet vrácených hledaných zásilek je 100.

deliveries DELETE

Rušení doposud neuzavřených zásilek.

Ukázka HTTP Požadavku (REQUEST)

Každá zásilka musí obsahovat id zásilky deliveryId dle příkladu. Lze rušit pouze neuzavřené a nezrušené zásilky.

Endpoint

DELETE: https://rest.stiteknabalik.cz/v4/deliveries

Ukázka hlavičky

Host => rest.stiteknabalik.cz
Authorization => Basic b66f6b694032e4271710deb21d7a7d703c974854a9a09a72825115bce69cb369
Accept => application/json
Content-type => application/json

Ukázka těla

{
    "deliveries": [
        {
            "deliveryId": 15023456
        },
        {
            "deliveryId": 15023457
        }
    ]
}

Popis odpovědi (RESPONSE)

Odpověď obsahuje pole code, status a message.

Validace a chybové kódy

Validační chyby jsou označeny HTTP kódem 422.

Monitored Deliveries / Monitorované Zásilky

Monitorujte Vaše zásilky lépe i když neexportujete balíky přes Štíteknabalík.cz

Nezávisle na Vašem propojení s API přepravce můžete využít jednu z nejdůležitějších vlastností našeho systému. Vytvoření monitorované zásilky ve Štíteknabalík.cz Vám umožní získat podrobné stavy včetně upozorňování na zpožděné nebo problematické zásilky a vlastní Track & Trace stránku pro Vaše zákazníky.

monitored-deliveries POST

Import zásilek s trekovacími čísly do systému Štíteknabalík.cz pro Track & Trace monitoring

Zásilky importované do Štíteknabalík.cz budou vytvořené se stavem 2_0_0 - K odeslání. Předpokládá se, že zásilka již existuje v systému přepravce a čeká na převzetí kurýrem, případně je již na cestě k příjemci.
Data o zásilce do Štíteknabalík.cz předáváte současně s trekovacím číslem což je hlavní rozdíl oproti standardním zásilkám.

Změna stavu zásilky ve Štíteknabalík.cz nastane automaticky po prvním zkontrolování jejího stavu u přepravce (řádově do několika minut v případě, že je dostupný nový stav).

Oproti standardní zásilce vyžaduje tato metoda pouze několik základních parametrů nezbytných pro správný tracking.

Po vytvoření monitorované zásilky získáte možnost doptávat se na stavy pomocí metod deliveries/traces GET včetně získání informací o zásilce pomocí deliveries GET.

Ukázka HTTP Požadavku (REQUEST)

API přijímá všechny parametry jako metoda deliveries POST avšak v tomto případě jsou povinně vyžadovány jen parametry uvedené v příkladu.

Endpoint

POST: https://rest.stiteknabalik.cz/v4/monitored-deliveries

Ukázka hlavičky

Host => rest.stiteknabalik.cz
Authorization => Basic b66f6b694032e4271710deb21d7a7d703c974854a9a09a72825115bce69cb369
Accept => application/json
Content-type => application/json

Ukázka těla

{
    "deliveries": [
        {
            "tackingNumber": "CF55465884",
            "referenceId": "20210001",
            "value": 2000,
            "valueCurrency": "CZK",
            "agent": "GLS",
            "deliveryType": "BP",
            "sender": {
                "type": "collectionPlace",
                "collectionPlace": "sokolovska-21"
            },
            "recipient": {
                "firstname": null,
                "surname": "Společnost s.r.o.",
                "contactPerson": null,
                "phone": "+420777111000",
                "email": "email@recipient.cz",
                "type": "address",
                "address": {
                    "city": "Praha",
                    "street": "Revoluční 11",
                    "postalCode": "11000",
                    "state": "CZ"
                }
            }
        }
    ]
}

Popis polí požadavku (REQUEST)

Pole	Datový typ	Povinné	Validace	Popis
`trackingNumber`	string	Povinné	max 63 zn.	Trekovací číslo zásilky, které jste získali od přepravce. Pokud je zásilka vícekusá je nutné poslat číslo hlavního balíku (většinou je to ten, který je první v pořadí, případně ten u kterého se udává i dobírka).
`referenceId`	string	Nepovinné	max 255 zn.	Váš identifikátor zásilky - použijte v případě, že nechcete pracovat se zásilkou pomocí našeho deliveryId, které bude vráceno po exportu zásilky. Číslo musí být unikátní. Tento identifikátor lze také využít k získávání informací o zásilkách pomocí metody deliveries/GET nebo deliveries/traces/GET.
`recipient`\|`sender`	string[]	Povinné		Pole odesílatele i příjemce jsou typově shodná, tzn. obsahují stejné povinné a nepovinné parametry. ^1]
`value`	float	Povinné	0.00	Hodnota zásilky v měně uvedené v klíči `valueCurrency`. ^1]
`valueCurrency`	string	Povinné	ISO_4217	Měna hodnoty zásilky ^1]
`cod`	float	Nepovinné	0.00	výše dobírky zásilky v měně uvedené v klíči `codCurrency` ^1]
`codCurrency`	string	Podmíněno	ISO_4217	Měna dobírky zásilky ^1]
`deliveryType`	string	Povinné	klíč číselníku, 2 zn.	Přepravní služba - Identifikátor. Seznam identifikátorů naleznete v příslušném číselníku. ^1]
`agent`	string	Povinné	klíč číselníku, max 7 zn.	Přepravce - Identifikátor. Seznam identifikátorů naleznete v příslušném číselníku. ^1]

1] Podrobnosti pole jsou popsány v metodě deliveries POST, více zde

Ukázka úspěšné odpovědi (RESPONSE)

Ukázka hlavičky

HTTP/1.1 201
X-Frame-Options => SAMEORIGIN
Vary => X-Requested-With
X-Powered-By => Lean Mapper
X-Robots-Tag => noindex
Content-Type => application/json; charset=UTF-8
ETag => "5887cca6c93d143c689ced8bc5080651"
Location => http://rest.stiteknabalik.cz/v4/monitored-deliveries

Ukázka těla

{
    "code": 201,
    "status": "success",
    "message": "Deliveries successfully created!",
    "data": [
        {
            "trackingNumber": "CF55465884",
            "referenceId": "20210001",
            "agent": "GLS",
            "cod": 1200,
            "codCurrency": "CZK",
            "created": "2020-09-22T13:21:08+02:00",
            "deliveryId": 15023456,
            "deliveryMetaData": null,
            "deliveryNumber": "CF55465884",
            "deliveryType": "BP",
            "externalId": "1234567",
            "foxdeliDetailUrl": "https://app.stiteknabalik.cz/deliveries/15023456",
            "foxdeliTrackingUrl": "https://tt.stiteknabalik.cz/status/mujshop/15023456?sig=NGVjMjdjMmVhYjJiAtc5MGVmMzFmNjcyMzBlZjE5ZDliN2MxZjU1YmY3ZWE0MjQ1ZWUwZjQ4ZDg5MjJhZTZiNQ%3D%3D",
            "extraServices": [],
            "important": false,
            "inDelay": false,
            "notDelivered": 0,
            "notPickedUp": 0,
            "packages": [
                []
            ],
            "recipient": {
                "firstname": null,
                "surname": "Společnost s.r.o.",
                "contactPerson": null,
                "phone": "+420777111000",
                "email": "email@recipient.cz",
                "type": "address",
                "address": {
                    "city": "Praha",
                    "street": "Revoluční 11",
                    "postalCode": "11000",
                    "state": "CZ"
                }
            },
            "sender": {
                "type": "collectionPlace",
                "collectionPlace": "sokolovska-21"
            },
            "source": 3,
            "sourceName": "API",
            "state": "2.0.0",
            "stateName": "K odeslání",
            "stateChanged": "2020-09-11T07:09:39+02:00",
            "stateCategory": "2",
            "stateCategoryName": "K odeslání",
            "stateSubcategory": "2.0",
            "stateSubcategoryName": "K odeslání",
            "value": 2000,
            "valueCurrency": "CZK",
            "variableSymbol": "12345678",
            "monitored": true
        }
    ]
}

Pozn. Popis polí v odpovědi naleznete v popisu polí metody deliveries/POST zde.

Omezení monitorovaných zásilek

Monitorované zásilky mají několik omezení týkajících se především API metod, které u nich nelze použít. Jedná se o metody pro tisk štítků (PDF, ZPL) a uzavírání zásilek PATCH. Ty jsou určeny výhradně pro zásilky vytvořené standardní POST metodou.
Metody pro editaci PUT a smazání DELETE připravujeme.

monitored-deliveries PUT

Editace monitorovaných zásilek.

BUDE IMPLEMENTOVÁNO

monitored-deliveries DELETE

Zrušení monitorovaných zásilek.

BUDE IMPLEMENTOVÁNO

Tickets / Zásilky

deliveries/tickets GET - PDF štítky

Vygenerování štítků do PDF souboru v base64.

Popis požadavku (REQUEST)

Štítky lze generovat na Vámi definované pozice na arch A4, výchozí je první pozice na stránce. Požadované zásilky definujte query parameterem deliveryId podobně jako při získávání zásilek (GET), tedy více čísel oddělte čárkou. Počáteční pozice prvního štítku je určena volitelným query parametrem position. Tento parametr může nabývat hodnot od jedné do maxima dle daného přepravce. Počet pozic pro jednotlivé přepravce naleznete ve specifikaci štítků (sloupec Arch A4).

Dalším volitelným parametrem je printFormat. Možné hodnoty jsou v tabulce níže.

Hodnoty pro `printFormat`

Klíč	Popis
default	Tisk na arch formátu A4 (výchozí hodnota při neuvedení parametru). Současně se uvádí i `position` pozice štítku na archu.
single	Tisk štítků na kotouč. Každý štítek v PDF dokumentu bude jako samostatná stránka v přesných rozměrech štítku přepravce.

Ukázka HTTP Požadavku (REQUEST)

Endpoint otevřít

GET: https://rest.stiteknabalik.cz/v4/deliveries/tickets?deliveryId=15023456,15023457&position=2&printFormat=default

Ukázka hlavičky

Host => rest.stiteknabalik.cz
Authorization => Basic b66f6b694032e4271710deb21d7a7d703c974854a9a09a72825115bce69cb369
Accept => application/json

Popis odpovědi (RESPONSE)

Jako všechny odpovědi, i tato respektuje požadovaný formát dle hlavičky Accept. Binární data vygenerovaného PDF souboru jsou vrácena ve formátu base64 dle specifikace MIME .

Ve vaší aplikaci je tedy nutné před uložením souboru dekódovat obsah zpět do binárních dat. Ve většině jazyků toto není problém, viz PHP a Java .

Ukázka úspěšné odpovědi (RESPONSE)

Data štítku v ukázce jsou jen vzorová a neobsahují skutečný štítek.

Ukázka hlavičky

HTTP/1.1 200
X-Frame-Options => SAMEORIGIN
Vary => X-Requested-With
X-Powered-By => Lean Mapper
X-Robots-Tag => noindex
Content-Type => application/json; charset=UTF-8
Cache-Control => max-age=0
Expires => Thu, 24 Sep 2020 13:08:01 GMT
ETag => "7e43086bf308a5bfc7c58741b4443683"

Ukázka těla

{
    "code": 200,
    "status": "success",
    "message": "Tickets successfully generated",
    "data": [
        {
            "created": "2020-09-22T14:21:31+02:00",
            "size": 82348,
            "contents": "JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10+Pl0+Pj4+Pj4="
        },
        {
            "created": "2020-09-22T14:21:31+02:01",
            "size": 67798,
            "contents": "BHBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10+Pl0+Pj4+Pj8="
        }
    ]
}

Popis "vybraných" polí úspěšné odpovědi (RESPONSE)

Pole	Datový typ	Popis
`data[].created`	string	Datum vytvoření PDF souboru.
`data[].size`	int	Informace o velikosti souboru v bytech před zakódováním do base64
`data[].contents`	string	Obsah PDF souboru ve formátu base64 MIME. Mějte na paměti, že generování velkých PDF souborů je časově náročná operace a celkové zpracování může trvat několik vteřin. Při hromadných requestech doporučujeme rozumné rozdělení na několik dávek (například do 50ks najednou).

Validace a chybové kódy

Štítky lze generovat pouze pro uzavřené zásilky. V případě nenalezení některé ze zásilek je vrácen HTTP kód 404. Při pokusu o přístup k zásilce s nedostatečným oprávněním je vrácen HTTP kód 403. Ostatní validační chyby, například pokus o tisk neuzavřené zásilky, jsou indikovány kódem 422.

Upozornění

1) Není možné generovat štítky pro několik přepravců najednou, jelikož každý z nich má jiné štítky.

2) Nelze tisknout štítky pro zásilky s doplňkovou službou "Zpětná zásilka", protože balík není vyzvedáván na Vašem svozovém místu. Tisk by tak postrádal smysl.

3) Zpracování velkého množství štítků v jednom requestu může mít negativní dopad na reponse time. V případě, že zaznamenáte potíže s hromadným získáváním štítků, doporučujeme dotazy rozdělit na menší dávky.

deliveries/zpl GET - ZPL štítky

Vygenerování štítků do ZPL formátu.

Popis požadavku (REQUEST)

Štítky lze generovat pro více zásilek najednou avšak vždy od jednoho přepravce.

Požadované zásilky definujte query parameterem deliveryId podobně jako při získávání zásilek, tedy více čísel oddělte čárkou. Generovat štítky lze pouze pro přepravce s integrovanou podporou ZPL. Velikost štítku a DPI definujete parametrem size a dpi. V případě, že parametry neuvedete bude vrácena defaultní kombinace velikosti a DPI štítku.

ZPL formáty

Podporované formáty ZPL naleznete ve specifikaci štítků anebo ve strukturované podobě v API viz. popis.

Ukázka HTTP Požadavku (REQUEST)

Endpoint otevřít

GET: https://rest.stiteknabalik.cz/v4/deliveries/zpl?deliveryId=15023456,15023457&size=10x15&dpi=300

Ukázka hlavičky

Host => rest.stiteknabalik.cz
Authorization => Basic b66f6b694032e4271710deb21d7a7d703c974854a9a09a72825115bce69cb369
Accept => application/json
Content-type => application/json

Popis odpovědi (RESPONSE)

Odpověď obsahuje data všech štítků k požadovaným zásilkám. V případě, že zásilka je vícekusá, naleznete v odpovědi štítky pro každý kus.

Ukázka úspěšné odpovědi (RESPONSE)

Data štítku v ukázce jsou jen vzorová a neobsahují skutečný štítek.

Ukázka hlavičky

HTTP/1.1 200
X-Frame-Options => SAMEORIGIN
Vary => X-Requested-With
X-Powered-By => Lean Mapper
X-Robots-Tag => noindex
Content-Type => application/json; charset=UTF-8
Cache-Control => max-age=0
Expires => Thu, 24 Sep 2020 13:15:01 GMT
ETag => "153ee69dbc346eac73ccedb5c03ac4d5"

Ukázka těla

{
    "code": 200,
    "status": "success",
    "message": "ZPL tickets successfully retrieved",
    "data": [
        {
            "deliveryId": 15023456,
            "contents": "^XA^CI28^CWZ,E:TT0003M_.FNT^FS^BY3^FO60,10^B2B,150,N,N,N^FD000609431990^FS^FT50,360^AZB50,50^FWB^FD0006^FS^FT50,210^AZB40,40^FWB^FD0943199^FS^FT50,40^AZB30,30^FWB^FD0^F..."
        },
        {
            "deliveryId": 15023457,
            "contents": "^XA^CI28^CWZ,E5GGVD_.FNT^FS^BY3^FO60,10^B2B,150,N,N,N^FD000609431990^FS^FT50,360^AZB50,50^FWB^FD0006^FS^FT50,210^AZB40,40^FWB^FD0943199^FS^FT50,40^AZB30,30^FWB^FD0^DF..."
        }
    ]
}

Validace a chybové kódy

Štítky lze generovat pouze pro uzavřené zásilky. V případě nenalezení některé ze zásilek nebo štítku ZPL je vrácen HTTP kód 404. Při pokusu o přístup k zásilce s nedostatečným oprávněním je vrácen HTTP kód 403. Ostatní validační chyby, například pokus o tisk neuzavřené zásilky, jsou indikovány kódem 422.

Traces / Stavy

deliveries/traces GET

Získání detailních Track and trace stavů k vybraným zásilkám.

Ukázka HTTP Požadavku (REQUEST)

Požadované zásilky definujte query parameterem deliveryId podobně jako při získávání zásilek, tedy více čísel oddělte čárkou.

Endpoint otevřít

GET: https://rest.stiteknabalik.cz/v4/deliveries/traces?deliveryId=15023456,15023457

Ukázka hlavičky

Host => rest.stiteknabalik.cz
Authorization => Basic b66f6b694032e4271710deb21d7a7d703c974854a9a09a72825115bce69cb369
Accept => application/json
Content-type => application/json

Popis odpovědi (RESPONSE)

V odpovědi naleznete stavy ke všem požadovaným zásilkám v klíči traces.
Čas poslední kontroly daných stavů je uložena pod klíčem lastChecked u dané zásilky (před první kontrolou nemusí obsahovat žádnou hodnotu).
V případě, že zásilka ještě nebyla odeslána, může být pole traces prázdné.

Ukázka úspěšné odpovědi (RESPONSE)

Ukázka hlavičky

HTTP/1.1 200
X-Frame-Options => SAMEORIGIN
Vary => X-Requested-With
X-Powered-By => Lean Mapper
X-Robots-Tag => noindex
Content-Type => application/json; charset=UTF-8
Cache-Control => max-age=0
Expires => Thu, 26 Sep 2020 13:15:01 GMT
ETag => "8887cca6c93d143c689ced8bc5080651"

Ukázka těla

{
    "code": 200,
    "status": "success",
    "message": "Traces successfully retrieved",
    "data": [
        {
            "deliveryId": 15023456,
            "lastChecked": "2020-09-25T10:30:00+02:00",
            "traces": [
                {
                    "type": "state",
                    "date": "2020-09-20T18:00:37+02:00",
                    "text": "Zásilka byla vydána.",
                    "flag": "",
                    "state": "4.0.0",
                    "stateSubcategory": "4.0",
                    "stateCategory": "4"
                },
                {
                    "type": "flag",
                    "date": "2020-09-20T00:00:00+02:00",
                    "text": "Zpožděné doručení",
                    "flag": "notDelivered3Days",
                    "state": "",
                    "stateSubcategory": "",
                    "stateCategory": ""
                },
                {
                    "type": "flag",
                    "date": "2020-09-19T00:00:00+02:00",
                    "text": "Mírně zpožděné doručení",
                    "flag": "notDelivered2Days",
                    "state": "",
                    "stateSubcategory": "",
                    "stateCategory": ""
                },
                {
                    "type": "state",
                    "date": "2020-09-17T14:24:35+02:00",
                    "text": "Zásilka byla přijata na cílovém výdejním místě Nymburk, Pražská 2261.",
                    "flag": "",
                    "state": "3.1.4",
                    "stateSubcategory": "3.1",
                    "stateCategory": "3"
                },
                {
                    "type": "state",
                    "date": "2020-09-17T10:20:51+02:00",
                    "text": "Zásilka byla odeslána na pobočku Nymburk, Pražská 2261",
                    "flag": "",
                    "state": "3.1.3",
                    "stateSubcategory": "3.1",
                    "stateCategory": "3"
                },
                {
                    "type": "state",
                    "date": "2020-09-17T05:19:33+02:00",
                    "text": "Zásilka byla přijata na depu Zásilkovna, DEPO, Praha 19, Satalice, U Arborky 696.",
                    "flag": "",
                    "state": "3.1.3",
                    "stateSubcategory": "3.1",
                    "stateCategory": "3"
                },
                {
                    "type": "state",
                    "date": "2020-09-17T05:19:22+02:00",
                    "text": "Zásilka byla připravena k odeslání na depu Zásilkovna, DEPO, Praha 19, Satalice, U Arborky 696.",
                    "flag": "",
                    "state": "3.1.3",
                    "stateSubcategory": "3.1",
                    "stateCategory": "3"
                },
                {
                    "type": "state",
                    "date": "2020-09-16T20:34:47+02:00",
                    "text": "Zásilka byla odeslána na pobočku DEPO, Praha 19, Satalice, U Arborky 696",
                    "flag": "",
                    "state": "3.1.3",
                    "stateSubcategory": "3.1",
                    "stateCategory": "3"
                },
                {
                    "type": "state",
                    "date": "2020-09-16T19:51:27+02:00",
                    "text": "Zásilka byla odeslána na pobočku DEPO, Praha 19, Satalice, U Arborky 696",
                    "flag": "",
                    "state": "3.1.3",
                    "stateSubcategory": "3.1",
                    "stateCategory": "3"
                },
                {
                    "type": "state",
                    "date": "2020-09-16T19:32:48+02:00",
                    "text": "Zásilka byla přijata na depu Zásilkovna, DEPO, Ostrava, Frýdecká 700/475.",
                    "flag": "",
                    "state": "3.1.3",
                    "stateSubcategory": "3.1",
                    "stateCategory": "3"
                },
                {
                    "type": "state",
                    "date": "2020-09-16T19:32:41+02:00",
                    "text": "Zásilka byla připravena k odeslání na depu Zásilkovna, DEPO, Ostrava, Frýdecká 700/475.",
                    "flag": "",
                    "state": "3.1.3",
                    "stateSubcategory": "3.1",
                    "stateCategory": "3"
                },
                {
                    "type": "state",
                    "date": "2020-09-16T14:20:35+02:00",
                    "text": "Internetový obchod předal informace o zásilce.",
                    "flag": "",
                    "state": "2.0.0",
                    "stateSubcategory": "2.0",
                    "stateCategory": "2"
                },
                {
                    "type": "state",
                    "date": "2020-09-16T14:20:34+02:00",
                    "text": "Zásilka uzavřena v foxdeli",
                    "flag": "",
                    "state": "2.0.0",
                    "stateSubcategory": "2.0",
                    "stateCategory": "2"
                },
                {
                    "type": "state",
                    "date": "2020-09-16T14:20:32+02:00",
                    "text": "Zásilka vytvořena v foxdeli",
                    "flag": "",
                    "state": "1.0.0",
                    "stateSubcategory": "1.0",
                    "stateCategory": "1"
                }
            ]
        },
        {
            "deliveryId": 15023457,
            "lastChecked": "2020-09-25T10:30:00+02:00",
            "traces": []
        }
    ]
}

Popis "vybraných" polí v položce `data` úspěšné odpovědi (RESPONSE)

Pole	Datový typ	Popis
`deliveryId`	int	Číslo zásilky. Při dotazování na více zásilek v jednom dotazu rozlišujte jendotlivé položky podle tohoto klíče a nikoli podle pořadí.
`lastChecked`	string	Čas poslední kontroly zásilky v API přepravce.
`traces[]`	array	Jednotlivé stavy zásilky seřazené od nejnovějších po nejstarší (odshora).
↳ `traces[].type`	string	Typ stavu. Rozlišujeme state - stav zásilky flag - flag zásilky
↳ `traces[].date`	string	Datum vytvoření stavu u přepravce.
↳ `traces[].text`	string	Informace od přepravce nebo systému Štíteknabalík.cz.
↳ `traces[].flag`	string	Hodnota upřesňuje o jaký flag se jedná. Možné flagy naleznete v tabulce stavů zde.
↳ `traces[].state`	string	Aktuální přesný stav zásilky v největším detailu. Stavy a kategorie naleznete zde.
↳ `traces[].stateSubcategory`	string	Přesnější detail stavu hlavní kategorie.
↳ `traces[].stateCategory`	string	Hlavní kategorie stavu reflektující sekci přehledu zásilek v aplikaci Štíteknabalík.cz.

Validace a chybové kódy

Stavy lze získávat pouze pro uzavřené zásilky. V případě nenalezení některé ze zásilek je vrácen HTTP kód 404. Při pokusu o přístup k zásilce s nedostatečným oprávněním je vrácen HTTP kód 403. Ostatní validační chyby, například pokus o získání stavu u neuzavřené zásilky, jsou indikovány kódem 422.

Collection Protocols / Svozové protokoly

collection-protocols POST

Vytvoření svozového protokolu včetně vygenerování PDF souboru.

Popis požadavku (REQUEST)

Svozový protokol slouží jako přehled zásilek, které předáváte přepravci v rámci daného svozu. Pro vytvoření tohoto protokolu tedy stačí definovat identifikátor svozového místa a přepravce. Hodnoty polí jsou totožné s poli při vkládání vkládání zásilek, tj. collectionPlace a agent.

Lze také zaslat čísla zásilek, která chcete na protokolu mít. K tomu poslouží volitelný kontejner deliveries. Vyžádané zásilky, ale musí být uzavřené, nedoručené a nesmí být na jiném svozovém protokolu jinak se vrátí chybová hláška.

Ukázka HTTP Požadavku (REQUEST)

Endpoint

POST: https://rest.stiteknabalik.cz/v4/collection-protocols

Ukázka hlavičky

Host => rest.stiteknabalik.cz
Authorization => Basic b66f6b694032e4271710deb21d7a7d703c974854a9a09a72825115bce69cb369
Accept => application/json
Content-type => application/json

Ukázka těla

{
    "agent": "PPL",
    "collectionPlace": "sokolovska-21",
    "deliveries": [
        15023456,
        15023457
    ]
}

Popis odpovědi (RESPONSE)

V hlavičce Location naleznete odkaz na právě vytvořený protokol, nicméně data protokolu jsou vrácena i v této odpovědi. V odpovědi v klíči data naleznete všechny potřebné údaje o vytvořeném protokolu, včetně obsahu PDF souboru.

Ukázka úspěšné odpovědi (RESPONSE)

Data štítku v ukázce jsou jen vzorová a neobsahují skutečný štítek.

Ukázka hlavičky

HTTP/1.1 201
X-Frame-Options => SAMEORIGIN
Vary => X-Requested-With
X-Powered-By => Lean Mapper
X-Robots-Tag => noindex
Content-Type => application/json; charset=UTF-8
Location => /v4/collection-protocols?collectionProtocolId=1425

Ukázka těla

{
    "code": 201,
    "status": "success",
    "message": "Collection protocol successfully created!",
    "data": {
        "collectionProtocolId": 1425,
        "agent": "PPL",
        "collectionPlace": "sokolovska-21",
        "protocol": "JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10+Pl0+Pj4+Pj4=",
        "created": "2020-09-25T08:07:45+02:00",
        "deliveries": [
            15023456,
            15023457,
            15023458
        ]
    }
}

Popis polí odpovědi (RESPONSE)

Pole	Datový typ	Popis
`collectionProtocolId`	string	Je id svozového protokolu, používá se v URL zdroje pro získání informací o protokolu (viz níže)
`agent`	string	Zkratka přepravce, pro kterého byl protokol vygenerován
`protocol`	string	Obsah PDF souboru v base64 MIME
`created`	string	Datum vytvoření protokolu
`deliveries`	string	Pole id zásilek, které jsou v protokolu zahrnuty

Validace a chybové kódy

Svozový protokol lze generovat pouze pokud v daném svozovém místě existují nějaké neodeslané uzavřené zásilky daného přepravce bez vytvořeného protokolu.

Všechny validační chyby vracejí kód 422 s polem errors se standardní strukturou a totožnými chybovými kódy jako u vkládání zásilek.

Pro obecné chyby jako je špatné použití metody (například pokud neexistují zásilky pro daný protokol) však není pole errors dostupné. Lze generovat pouze jeden protokol v jednom požadavku.

collection-protocols GET

Získání informací o svozovém protokolu včetně obsahu PDF souboru.

Popis požadavku (REQUEST)

Jako query parametr collectionProtocolId uveďte hodnotu klíče collectionProtocolId získanou v odpovědi při vytváření svozového protokolu. Lze získat obsah pouze jednoho protokolu.

Ukázka HTTP Požadavku (REQUEST)

Endpoint otevřít

GET: https://rest.stiteknabalik.cz/v4/collection-protocols?collectionProtocolId=1425

Ukázka hlavičky

Host => rest.stiteknabalik.cz
Authorization => Basic b66f6b694032e4271710deb21d7a7d703c974854a9a09a72825115bce69cb369
Accept => application/json
Content-type => application/json

Popis odpovědi (RESPONSE)

Odpověď v klíči data je totožná s odpovědí při vytvoření svozového protokolu. Popis viz výše.

Ukázka úspěšné odpovědi (RESPONSE)

Data štítku v ukázce jsou jen vzorová a neobsahují skutečný štítek.

Ukázka hlavičky

HTTP/1.1 200
X-Frame-Options => SAMEORIGIN
Vary => X-Requested-With
X-Powered-By => Lean Mapper
X-Robots-Tag => noindex
Content-Type => application/json; charset=UTF-8

Ukázka těla

{
    "code": 200,
    "status": "success",
    "message": "Protocol successfully fetched!",
    "data": {
        "collectionProtocolId": 1425,
        "agent": "PPL",
        "collectionPlace": "sokolovska-21",
        "protocol": "JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10+Pl0+Pj4+Pj4=",
        "created": "2020-09-25T08:07:45+02:00",
        "deliveries": [
            15023456,
            15023457,
            15023458
        ]
    }
}

Validace a chybové kódy

V případě dotazu na neexistující protokol je vrácen kód 404 a při pokusu o neoprávněný přístup je vrácen kód 403.

Collection Places / Svozová místa

collection-places GET

Získání informací o všech aktivních svozových místech.

Ukázka HTTP Požadavku (REQUEST)

Endpoint otevřít

GET: https://rest.stiteknabalik.cz/v4/collection-places

Ukázka hlavičky

Host => rest.stiteknabalik.cz
Authorization => Basic b66f6b694032e4271710deb21d7a7d703c974854a9a09a72825115bce69cb369
Accept => application/json
Content-type => application/json
x-http-method-override => GET

Popis odpovědi (RESPONSE)

V klíči data naleznete informace o aktivních svozových místech s následujícími daty.

Ukázka úspěšné odpovědi (RESPONSE)

Data štítku v ukázce jsou jen vzorová a neobsahují skutečný štítek.

Ukázka hlavičky

HTTP/1.1 200
X-Frame-Options => SAMEORIGIN
Vary => X-Requested-With
X-Powered-By => Lean Mapper
X-Robots-Tag => noindex
Content-Type => application/json; charset=UTF-8
Cache-Control => max-age=0
Expires => Thu, 26 Sep 2020 13:15:01 GMT
ETag => "8887cca6c93d143c689ced8bc5080651"

Ukázka těla

{
    "code": 200,
    "status": "success",
    "message": "Active collection places successfully fetched",
    "data": [
        {
            "name": "Stará 251",
            "identificator": "stara-251",
            "email": "obchod@mujeshopik.cz",
            "phone": "+420702358586",
            "contactPerson": null,
            "state": "CZ",
            "city": "Bohumín",
            "street": "Stará 251",
            "postalCode": "73552"
        },
        {
            "name": "Sokolovská 21, Praha",
            "identificator": "sokolovska-21",
            "email": "obchod@mujeshopik.cz",
            "phone": "+420702358586",
            "contactPerson": null,
            "state": "CZ",
            "city": "Praha",
            "street": "Sokolovská 51",
            "postalCode": "18000"
        }
    ]
}

Popis polí odpovědi (RESPONSE)

Pole	Datový typ	Popis
`identificator`	string	Unikátní identifikace svozového místa, používá se například při tisku svozových protokolů
`name`	string	Pojmenování svozového místa
`email`	string	email kontaktní osoby
`phone`	string	Telefon kontaktní osoby
`contactPerson`	string	Kontaktní osoba
`state`	string	Stát ve formátu ISO 3166-2 , tedy například CZ
`city`	string	Město
`street`	string	Ulice a číslo popisné
`postalCode`	string	PSČ

List / Číselníky Štíteknabalík.cz

Přes API lze získat také ucelené a aktuální seznamy podporovaných přepravců agent, doplňkových služeb extra-service, stavů zásilek state a podporované formáty štítků pro jednotlivé přepravce.

Kořenový endpoint https://rest.stiteknabalik.cz/v4/list funguje jako rozcestník pro jednotlivé číselníky.

Získání číselníků je veřejné a nevyžaduje tedy autentizaci.

Prosím mějte na paměti, že defaultní formát odpovědi je XML (a je použit při přístupu přes prohlížeč). Pokud se budete dotazovat přes Váš systém můžete získat odpověď v JSON pomocí hlavičky Accept: application/json

Pro ucelenost API dokumentace zde uvádíme odpověďi requestů pouze v JSON formátu.

Aktuání číselníky s hodnotami v přehledné tabulce najdete v této části dokumentace.

list/agents GET

Získání seznamu přepravců agent s podporovanými přepravními službami deliveryType a jejich popisy.

Presonalizovaný seznam přepravců

Pro získání přepravců a služeb Vašeho účtu stačí změnit endpoint na adresu https://rest.stiteknabalik.cz/v4/list/agents/account-only. Na této adrese budou k dispozici pouze přepravci, které používáte.
Endpoint account-only vyžaduje autentizaci.

Ukázka HTTP Požadavku (REQUEST)

Endpoint otevřít

GET: https://rest.stiteknabalik.cz/v4/list/agents

Ukázka úspěšné odpovědi (RESPONSE)

Ukázka obsahuje pouze demonstrativní část odpovědi.

Ukázka těla

{
    "code": 200,
    "status": "success",
    "message": "Foxdeli list of agents",
    "data": [
        {
            "abbr": "DPD",
            "fullname": "Direct Parcel Distribution CZ s. r. o.",
            "isActive": 1,
            "hasTicketPrint": 1,
            "hasProtocolPrint": 1,
            "deliveryTypes": [
                {
                    "abbr": "DQ",
                    "fullname": "DPD AirExpress",
                    "isActive": 1,
                    "isPickUpPlaceType": 0,
                    "isCargoType": 0,
                    "description": "Standardní balíková přeprava bez notifikací"
                },
                {
                    "abbr": "DJ",
                    "fullname": "DPD Classic",
                    "isActive": 1,
                    "isPickUpPlaceType": 0,
                    "isCargoType": 0,
                    "description": "Letecká přeprava"
                }
            ]
        }
    ]
}

Popis polí odpovědi (RESPONSE)

Pole	Datový typ	Hodnoty	Popis
`data`	array		Seznam přepravců
↳ `abbr`	string		Zkratka přepravce ve Štíteknabalík.cz (abbrevation). Používá se v API jako `agent`.
↳ `fullname`	string		Celý název přepravce
↳ `isActive`	tinyint	0, 1 ^1]	Indikace zda-li je možné přepravce využít pro vytváření zásilek. V případě ukončení spolupráce s přepravcem bude hodnota 0.
↳ `hasTicketPrint`	tinyint	0, 1 ^1]	Indikace zda-li systém Štíteknabalík.cz umožňuje u daného přepravce tisknout štítky.
↳ `hasProtocolPrint`	tinyint	0, 1 ^1]	Indikace zda-li systém Štíteknabalík.cz umožňuje u daného přepravce tisknout svozový protokol.
↳ `deliveryTypes`	array		Seznam podporvaných přepravních služeb daného přepravce.
↳ `abbr`	string		Zkratka přepravní služby ve Štíteknabalík.cz (abbrevation). Používá se v API jako `deliveryType`.
↳ `fullname`	string		Celý název přepravní služby.
↳ `isActive`	tinyint	0, 1 ^1]	Indikace zda-li je možné přepravní službu využít pro vytváření zásilek. V případě vyřazení služby bude hodnota 0.
↳ `isPickUpPlaceType`	tinyint	0, 1 ^1]	Indikace zda-li jde přepravní službu s odběrným místem. Ve většině případů je nezbytné v datech příjemce zaslat také identifikátor odběrného místa `pickUpPlace`.
↳ `isCargoType`	tinyint	0, 1 ^1]	Indikace zda-li jde přepravní službu určenou pro cargo přepravu. Cargo služby vyžadují zaslání parametrů `containerCode` a `containerItems` v definici balíků `packages`.
↳ `description`	string		Doplňující informace k přepravní službě

Informace

^1] 1 - ano, 0 - ne

list/extra-servicesGET

Získání seznamu doplňkových služeb extraServices s podrobnostmi a podporou u jednotlivých přepravců.

Ukázka HTTP Požadavku (REQUEST)

Endpoint otevřít

GET: https://rest.stiteknabalik.cz/v4/list/extra-services

Ukázka úspěšné odpovědi (RESPONSE)

Ukázka obsahuje pouze demonstrativní část odpovědi.

Ukázka těla

{
    "code": 200,
    "status": "success",
    "message": "Foxdeli list of extra services",
    "data": [
        {
            "code": "insurance",
            "fullname": "Připojištění",
            "description": "Dodatečné jednorázové připojištění k jednotlivým balíkům.",
            "isActive": 1,
            "isImplicitOnly": 0,
            "supportedAgents": [
                {
                    "agentFullname": "General Logistics Systems Czech Republic s.r.o.",
                    "agentAbbr": "GLS",
                    "requiredArguments": []
                },
                {
                    "agentFullname": "TNT Express Worldwide spol. s r.o.",
                    "agentAbbr": "TNT",
                    "requiredArguments": []
                }
            ]
        },
        {
            "code": "authentication",
            "fullname": "Ověření totožnosti",
            "description": "Při doručení kurýr předá zásilku příjemci až po předložení originálu dokladu totožnosti – OP, ŘP nebo cestovní pas.",
            "isActive": 1,
            "isImplicitOnly": 0,
            "supportedAgents": [
                {
                    "agentFullname": "WEIDO CZ s.r.o.",
                    "agentAbbr": "IT",
                    "requiredArguments": {
                        "identifier": "note",
                        "name": "Poznámka",
                        "example": ""
                    }
                }
            ]
        }
    ]
}

Popis polí odpovědi (RESPONSE)

Pole	Datový typ	Hodnoty	Popis
`data`	array		Seznam přepravců
↳ `code`	string		Zkratka doplňkové služby ve Štíteknabalík.cz (abbrevation). Používá se v API jako `extraService`.
↳ `fullname`	string		Celý název doplňkové služby
↳ `description`	string		Stručný popis doplňkové služby.
↳ `isActive` ^1]	tinyint	0, 1	Indikace zda-li je služba podporována a lze jí využít pro vytváření zásilek. V případě ukončení podpory služby bude hodnota 0.
↳ `isImplicitOnly` ^1]	tinyint	0, 1	Indikace zda-li se služba vytváří automaticky na základě parametrů zásilky. Implicitní služby přes API nepředáváte. Štíteknabalík.cz je vytvoří samo (například dobírka `cod`).
↳ `supportedAgents`	array		Přepravci, kteří danou službu podporují. V případě zaslání nepodporované služby bude vrácena chyba.
↳ `agentFullname`	string		Celý název přepravce.
↳ `agentAbbr`	string		Zkratka přepravce (abbrevation) využívaná ve Štíteknabalík.cz jako `agent`.
↳ `requiredArguments`	array		Povinné parametry, která je nutné zaslat, pokud danou službu využijete. Používá se v API jako `extraServices.arguments`
↳ `identifier`	string		Identifikátor povinného parametru. Identifikátor je klíč a přiřazená hodnota je očekávána jako string. Ukázka použití je v metodě deliveries/POST
↳ `name`	string		Název povinného parametru.
↳ `example`	string		Ukázka možných hodnot (například telefonní číslo, apod.)

Informace

^1] 1 - ano, 0 - ne

list/delivery-states GET

Získání seznamu Štíteknabalík.cz Track&Trace stavů pro sledování zásilek.

Ukázka HTTP Požadavku (REQUEST)

Endpoint otevřít

GET: https://rest.stiteknabalik.cz/v4/list/delivery-states

Ukázka úspěšné odpovědi (RESPONSE)

Ukázka obsahuje pouze demonstrativní část odpovědi.

Ukázka těla

{
    "code": 200,
    "status": "success",
    "message": "Foxdeli list of extra services",
    "data": [
        {
            "stateCategory": [
                {
                    "key": "in_progress",
                    "code": 1,
                    "name": "Rozpracované",
                    "color": "#ffffff"
                },
                {
                    "key": "ready_to_send",
                    "code": 2,
                    "name": "K odeslání",
                    "color": "#ffc83c"
                }
            ]
        },
        {
            "stateSubcategory": [
                {
                    "key": "in_progress",
                    "code": "1.0",
                    "name": "Rozpracované"
                },
                {
                    "key": "ready_to_send",
                    "code": "2.0",
                    "name": "K odeslání"
                }
            ]
        },
        {
            "state": [
                {
                    "key": "in_progress",
                    "code": "1.0.0",
                    "name": "Rozpracované",
                    "description": "Nově vytvořená zásilka (manuálně nebo metodou deliveries/POST), která ještě není uzavřená."
                },
                {
                    "key": "ready_to_send",
                    "code": "2.0.0",
                    "name": "K odeslání",
                    "description": "Uzavřené zásilky (manuálně nebo metodou deliveries/PATCH), které prozatím nebyly předány kurýrovi."
                }
            ]
        }
    ]
}

Popis polí odpovědi (RESPONSE)

Pole	Datový typ	Popis
`data`	array	Seznam stavů roztříděných do kontejnerů podle detailu stavů.
↳ `stateCategory\|stateSubcategory\|state`	array	Viz popis kontejnerů níže.
↳ `key`	string	Klíč. Unikátní textová reperezntace stavu zásilky (lower case).
↳ `code`	int\|float\|null	Unikátní číselný kód stavu zásilky. Je obsažen v odpovědi metody deliveries/traces/GET
↳ `name`	string	Název stavu (human readable).
↳ `description`	string	Informace ke stavu zásilky.

Informace ke kontejnerům a detailu

stateCategory - kontejner s hlavními kategoriemi stavů zásilek
stateSubcategory - kontejner s podkategoriemi stavů zásilek
state - kontejner s nejpodrobnějšími stavy zásilek - vysoký detail, časté změny stavů

list/ticket-formats GET

Získání podporovaných formátů pro tisk ZPL štítků zásilek.

Více informací získáte v popisu metody deliveries/traces/GET

Ukázka HTTP Požadavku (REQUEST)

Endpoint otevřít

GET: https://rest.stiteknabalik.cz/v4/list/zpl-tickets

Ukázka úspěšné odpovědi (RESPONSE)

Ukázka obsahuje pouze demonstrativní část odpovědi.

Ukázka těla

{
    "code": 200,
    "status": "success",
    "message": "Foxdeli list of ZPL tickets formats.",
    "data": [
        {
            "agentAbbr": "ČP",
            "size": "10x15",
            "dpi": "300",
            "printOrigin": "foxdeli",
            "orientation": "portrait"
        },
        {
            "agentAbbr": "GLS",
            "size": "10x5",
            "dpi": "300",
            "printOrigin": "foxdeli",
            "orientation": "letter"
        },
        {
            "agentAbbr": "GLS",
            "size": "10x15",
            "dpi": "300",
            "printOrigin": "foxdeli",
            "orientation": "letter"
        }
    ]
}

Popis polí odpovědi (RESPONSE)

Pole	Datový typ	Hodnoty	Popis
`data`	array		Seznam všech ZPL formátů daného přepravce.
↳ `agentAbbr`	string	GLS, PPL,...	Zkratka přepravce
↳ `size`	string	10x15, 10x5, 10x17,...	Rozměry štítku přepravce v cm.
↳ `code`	dpi	300, 203	Podporované DPI
↳ `name`	printOrigin	foxdeli, agent	Původ generování štítků. V případě generování na straně přepravce (agent) je potřeba počítat s delším časovým limitem.
↳ `orientation`	string	portrait, landscape	Orientace štítku. Informace je vhodná pro přípravu na automatizovaný tisk.
↳ `isAgentDefault`		1, 0	1 - výchozí formát štítku daného přepravce, který bude vrácen v odpovědi v případě, že nebude vyžádana konkrétní velikost.

Terminologie

Podporované metody

Endpointy pro https://rest.stiteknabalik.cz

Deliveries / Zásilky

deliveries POST

Ukázka HTTP Požadavku (REQUEST)

Popis polí požadavku (REQUEST)

Implicitní doplňkové služby

Ukázka úspěšné odpovědi (RESPONSE)

Popis "vybraných" polí úspěšné odpovědi (RESPONSE)

Validace a chybové kódy

Ukázka chybové odpovědi (RESPONSE)

Vkládání více zásilek v jednom požadavku

Další informace k odpovědi

deliveries PATCH

Ukázka HTTP Požadavku (REQUEST)

Popis polí požadavku (REQUEST)

Ukázka úspěšné odpovědi (RESPONSE)

Popis "vybraných" polí úspěšné odpovědi (RESPONSE)

Pozor

Validace a chybové kódy

Jak funguje validace

deliveries PUT

Popis požadavku (REQUEST)

Popis odpovědi (RESPONSE)

Validace a chybové kódy

deliveries GET

Ukázka HTTP Požadavku (REQUEST)

Ukázka úspěšné odpovědi (RESPONSE)

Popis dalších polí odpovědi (RESPONSE) 1]

Hledání dle ostatních parametrů zásilky

Příklady hledání (query parametry v URL)

HTTP Cacheování

Validace a chybové kódy

Omezení

deliveries DELETE

Ukázka HTTP Požadavku (REQUEST)

Popis odpovědi (RESPONSE)

Validace a chybové kódy

Monitored Deliveries / Monitorované Zásilky

Monitorujte Vaše zásilky lépe i když neexportujete balíky přes Štíteknabalík.cz

monitored-deliveries POST

Ukázka HTTP Požadavku (REQUEST)

Popis polí požadavku (REQUEST)

Ukázka úspěšné odpovědi (RESPONSE)

Omezení monitorovaných zásilek

monitored-deliveries PUT

BUDE IMPLEMENTOVÁNO

monitored-deliveries DELETE

BUDE IMPLEMENTOVÁNO

Tickets / Zásilky

deliveries/tickets GET - PDF štítky

Popis požadavku (REQUEST)

Hodnoty pro printFormat

Ukázka HTTP Požadavku (REQUEST)

Popis odpovědi (RESPONSE)

Ukázka úspěšné odpovědi (RESPONSE)

Popis "vybraných" polí úspěšné odpovědi (RESPONSE)

Validace a chybové kódy

Upozornění

deliveries/zpl GET - ZPL štítky

Popis požadavku (REQUEST)

ZPL formáty

Ukázka HTTP Požadavku (REQUEST)

Popis odpovědi (RESPONSE)

Ukázka úspěšné odpovědi (RESPONSE)

Validace a chybové kódy

Traces / Stavy

deliveries/traces GET

Ukázka HTTP Požadavku (REQUEST)

Popis odpovědi (RESPONSE)

Ukázka úspěšné odpovědi (RESPONSE)

Popis "vybraných" polí v položce data úspěšné odpovědi (RESPONSE)

Validace a chybové kódy

Collection Protocols / Svozové protokoly

collection-protocols POST

Popis požadavku (REQUEST)

Ukázka HTTP Požadavku (REQUEST)

Popis odpovědi (RESPONSE)

Ukázka úspěšné odpovědi (RESPONSE)

Popis dalších polí odpovědi (RESPONSE) ^1]

Hodnoty pro `printFormat`

Popis "vybraných" polí v položce `data` úspěšné odpovědi (RESPONSE)