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ýrazAnglický výrazAPI polePodrobnosti
ZásilkaDeliverydelivery
BalíkPackagepackageZásilka má jeden a více balíků.
PřepravceAgentagentNapř.: Česká pošta, GLS, PPL, Zásilkovna,..
Přepravní službaDelivery TypedeliveryTypeNapř.: Balík do ruky, Balík na poštu, Výdejní místa,..
Doplňková službaExtra ServiceextraServiceNapř.: Dobírka, Připojištění, SMS Avízo,..
Štíteknabalík.cz ID zásilkyDelivery Štíteknabalík.cz IDdeliveryIdID zásilky v systému Štíteknabalík.cz.
Číslo zásilkyDelivery NumberdeliveryNumberTrekovací číslo zásilky.
Číslo balíkuPackage NumberpackageNumberČíslo balíku, který je součástí zásilky (většinou je shodné s číslem zásilky).
Svozové místoCollection PlacecollectionPlaceSvozové místo kde bude přepravce vyzvedávat zásilky.
Odběrné místoPickup PlacepickupPlaceOdběrné místo pro doručení zásilek (dropoff point, pickup point, parcelshop, atd.)
Zpětná zásilkaBack 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ásilkaDirect 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ásilkaSwap 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ásilkaMultipackage Delivery-Zásilka, která obsahuje více než jeden balík.

Podporované metody

Endpointy pro https://rest.stiteknabalik.cz

PathPodporované HTTP metodyOAuth ScopePopis 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
deliveriesPráce s jednou nebo několika zásilkami najednou
/v4/deliveries/tickets
  • GET
deliveriesVygenerování štítků do PDF souboru pro jednu nebo více zásilek
/v4/deliveries/zpl
  • GET
deliveriesVygenerování štítků do v ZPL formátu pro jednu nebo více zásilek
/v4/deliveries/traces
  • GET
deliveriesTrack 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-protocolsVytvoření svozového protokolu včetně vygenerování PDF souboru
/v4/collection-places
  • GET
collection-placesZískání informací o všech aktivních svozových místech
/v4/list
  • GET
listSada 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)

PoleDatový typPovinnéValidacePopis
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]stringPovinné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.addressstring[]PodmíněnoPole adresu pokud je příjemce či odesílatel na běžné adrese. Parametry adresy jsou : street, streetNumber, state,city, postalCode;
        ↳ recipient|sender.address.streetstringPovinnémax 110 zn. včetně č.p.Název ulice; Musí obsahovat číslo popisné, pokud není uvedeno ve streetNumber
        ↳ recipient|sender.address.streetNumberstringPodmíněnoČíslo popisné; Povinné pouze pokud není uvedeno za mezerou ve street
        ↳ recipient|sender.address.statestringPovinnéISO 3166-2, 2 zn.Stát ve formátu ISO 3166-2 , tedy například CZ či SK.
        ↳ recipient|sender.address.citystringPovinnémax 127 zn.Město
        ↳ recipient|sender.address.postalCodestringPovinnévalidace podle státu, max 15 zn.PSČ; Bez mezer
    ↳ recipient|sender.collectionPlace 1]stringPodmíněnoklíč čí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]stringPodmíněnoklíč čí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.firstnamestringNepovinnémax 63 zn.Jméno (vynechte, pokud jde o firmu)
    ↳ recipient|sender.surnamestringPovinnémax 127 zn.Přijmení nebo název firmy
    ↳ recipient|sender.contactPersonstringNepovinnémax 127 zn.Kontaktní osoba - Jméno a příjmení kontaktní osoby (pokud jde o firmu)
    ↳ recipient|sender.email 1]stringPodmíněnoRFC 2822, max 255 zn.Email - Nemusí být vyplněno, pokud je vyplněn telefon
    ↳ recipient|sender.phone 1]stringPodmíněnoFormát dle státu. Vždy s předvolbou a bez mezer.Telefon - Nemusí být vyplněno, pokud je vyplněn email.
valuefloatPovinné0.00Hodnota zásilky v měně uvedené v klíči valueCurrency. Desetinná místa se oddělují tečkou.
valueCurrencystringPovinnéISO_4217Měna hodnoty zásilky ve formátu ISO 4217 , tedy například CZK či EUR
codfloatNepovinné0.00výše dobírky zásilky v měně uvedené v klíči codCurrency
codCurrencystringPodmíněnoISO_4217Měna dobírky zásilky ve formátu ISO 4217 , tedy například CZK či EUR, povinné, pokud je vyplněna dobírka
variableSymbolstringPodmíněnomax 10 zn.Variabilní symbol pro platbu dobírky (povinné, pokud je vyplněna dobírka cod a codCurrency)
packages.weight 3]floatNepovinné0.00Hmotnost balíku v Kg. Desetinná místa se oddělují tečkou.
packages.height 3]intPodmíněnoVýška balíku v cm. Pokud uvedete vyplňte i zbývající rozměry.
packages.length 3]intPodmíněnoDélka balíku v cm. Pokud uvedete vyplňte i zbývající rozměry.
packages.width 3]intPodmíněnoŠířka balíku v cm. Pokud uvedete vyplňte i zbývající rozměry.
packages.containerCode 4]stringPodmíněnoklíč čí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]intPodmíněnoPoč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.
deliveryTypestringPovinnéklíč číselníku, 2 zn.Přepravní služba - Identifikátor. Seznam identifikátorů naleznete v příslušném číselníku.
agentstringPovinnéklíč číselníku, max 7 zn.Přepravce - Identifikátor. Seznam identifikátorů naleznete v příslušném číselníku.
extraServices.codestringPovinnéklíč číselníku, max 63 zn.Doplňkové služby - Identifikátor. Seznam identifikátorů naleznete v příslušném číselníku.
extraServices.argumentsstringNepovinné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.
ticketNotestringNepovinnémax 255 zn.Poznámka na štítek. Doporučujeme co nejkratší poznámky (cca do 35 znaků).
externalIdstringNepovinné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.
platformKeystringNepovinné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)

PoleDatový typPopis
data[].deliveryIdintInterní číslo zásilky. Pomocí tohoto čísla můžete získávat informace o zásilce přes ostatní metody v naší API.
data[].deliveryNumberstringČíslo zásilky přepravce - je doplněno až po uzavření zásilky. Většinou je jde také o "trekovací číslo".
data[].createdstringDatum vytvoření zásilky.
data[].packages.barcodestringČárový kód balíku (bude i na štítku). Oproti deliveryNumber se většinou liší v kontrolní číslici.
data[].importantboolFlag, který reflektuje problematickou zásilku (například velké zpoždění, nepřevzetí, apod.).
data[].inDelayboolFlag, který reflektuje zpožděnou zásilku (oproti standardnímu času doručení ostaních zásilek stejného přepravce).
data[].sourceintId 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[].sourceNamestringPojmenování původu vzniku zásilky.
data[].state1] stringHlavní stav zásilky.
data[].stateName1] stringNázev hlavního stavu zásilky.
data[].stateChanged1] stringČas změny stavu (v případě exportu jde o čas vytvoření záznamu ve Štíteknabalík.cz).
data[].stateCategory1] stringKategorie stavu zásilky.
data[].stateCategoryName1] stringNázev kategorie stavu zásilky.
data[].stateSubcategory1] stringPodkategorie stavu zásilky.
data[].stateSubcategoryName1] stringNázev podkategorie stavu zásilky.
data[].foxdeliDetailUrlstringUrl detailu zásilky v aplikaci Foxdeli.com (vyžaduje přihlášení)
data[].foxdeliTrackingUrlstringUrl detailu zásilky vedoucí na brandovanou Track & Trace stránku (dle licence)
data[].monitoredboolIndikace 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)

PoleDatový typPovinnéPopis
deliveryIdintPovinnéŠtíteknabalík.cz ID zásilky, které jste získali při vytváření zásilky metodou POST.
closedboolPovinné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.
?fieldsstringNepovinné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)

PoleDatový typPopis
data[].collectionOrders[].agentstringZkratka přepravce, u něhož byl svoz objednán
data[].collectionOrders[].scheduledstringDatum objednání svozu ve formátu YYYY-MM-DD, o přesném času svozu budete informováni kurýrem.
data[].collectionOrders[].collectionPlacestringIdentifikátor svozového místa, na jehož adresu byl objednán svoz.
deliveries[].deliveryNumberstringČí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.barcodestringČá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)

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 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]

PoleDatový typPopis
agentTrackingUrlstringAktuá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ýčtemdeliveryId, 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 stringPopis
?deliveryId=>10441Vš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=>B5007Všechny zásilky s vyšším externím identifikátorem než B5007 (lexikograficky).
?created=2014-12-24Zásilky vytvořené na štědrý den v libovolný čas.
?deliveryNumber=M89Fulltextové hledání dle čísla zásilky přepravce.
?value=>10000&valueCurrency=CZKZásilky s hodnotou vyšší než 10 000 Kč.
?value[]=>10000&value[]=<20000&valueCurrency=CZKZásilky s hodnotou v rozmezí 10 000 - 20 000 Kč.
?variableSymbol=1234567890,9876543210Zá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)

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

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)

PoleDatový typPovinnéValidacePopis
trackingNumberstringPovinné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).
referenceIdstringNepovinné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|senderstring[]PovinnéPole odesílatele i příjemce jsou typově shodná, tzn. obsahují stejné povinné a nepovinné parametry. 1]
valuefloatPovinné0.00Hodnota zásilky v měně uvedené v klíči valueCurrency. 1]
valueCurrencystringPovinnéISO_4217Měna hodnoty zásilky 1]
codfloatNepovinné0.00výše dobírky zásilky v měně uvedené v klíči codCurrency 1]
codCurrencystringPodmíněnoISO_4217Měna dobírky zásilky 1]
deliveryTypestringPovinnéklíč číselníku, 2 zn.Přepravní služba - Identifikátor. Seznam identifikátorů naleznete v příslušném číselníku. 1]
agentstringPovinné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)

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/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
defaultTisk na arch formátu A4 (výchozí hodnota při neuvedení parametru). Současně se uvádí i position pozice štítku na archu.
singleTisk š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)

PoleDatový typPopis
data[].createdstringDatum vytvoření PDF souboru.
data[].sizeintInformace o velikosti souboru v bytech před zakódováním do base64
data[].contentsstringObsah 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)

PoleDatový typPopis
deliveryIdintČí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í.
lastCheckedstringČas poslední kontroly zásilky v API přepravce.
traces[]arrayJednotlivé stavy zásilky seřazené od nejnovějších po nejstarší (odshora).
    ↳ traces[].typestringTyp stavu. Rozlišujeme
state - stav zásilky
flag - flag zásilky
    ↳ traces[].datestringDatum vytvoření stavu u přepravce.
    ↳ traces[].textstringInformace od přepravce nebo systému Štíteknabalík.cz.
    ↳ traces[].flagstringHodnota upřesňuje o jaký flag se jedná. Možné flagy naleznete v tabulce stavů zde.
    ↳ traces[].statestringAktuální přesný stav zásilky v největším detailu. Stavy a kategorie naleznete zde.
    ↳ traces[].stateSubcategorystringPřesnější detail stavu hlavní kategorie.
    ↳ traces[].stateCategorystringHlavní 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)

PoleDatový typPopis
collectionProtocolId stringJe id svozového protokolu, používá se v URL zdroje pro získání informací o protokolu (viz níže)
agentstringZkratka přepravce, pro kterého byl protokol vygenerován
protocolstringObsah PDF souboru v base64 MIME
createdstringDatum vytvoření protokolu
deliveriesstringPole 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)

PoleDatový typPopis
identificator stringUnikátní identifikace svozového místa, používá se například při tisku svozových protokolů
namestringPojmenování svozového místa
emailstringemail kontaktní osoby
phonestringTelefon kontaktní osoby
contactPersonstringKontaktní osoba
statestringStát ve formátu ISO 3166-2 , tedy například CZ
citystringMěsto
streetstringUlice a číslo popisné
postalCodestringPSČ

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)

PoleDatový typHodnotyPopis
dataarraySeznam přepravců
    ↳ abbrstringZkratka přepravce ve Štíteknabalík.cz (abbrevation). Používá se v API jako agent.
    ↳ fullnamestringCelý název přepravce
    ↳ isActivetinyint0, 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.
    ↳ hasTicketPrinttinyint0, 1 1]Indikace zda-li systém Štíteknabalík.cz umožňuje u daného přepravce tisknout štítky.
    ↳ hasProtocolPrinttinyint0, 1 1]Indikace zda-li systém Štíteknabalík.cz umožňuje u daného přepravce tisknout svozový protokol.
    ↳ deliveryTypesarraySeznam podporvaných přepravních služeb daného přepravce.
        ↳ abbrstringZkratka přepravní služby ve Štíteknabalík.cz (abbrevation). Používá se v API jako deliveryType.
        ↳ fullnamestringCelý název přepravní služby.
        ↳ isActivetinyint0, 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.
        ↳ isPickUpPlaceTypetinyint0, 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.
        ↳ isCargoTypetinyint0, 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.
        ↳ descriptionstringDoplň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)

PoleDatový typHodnotyPopis
dataarraySeznam přepravců
    ↳ codestringZkratka doplňkové služby ve Štíteknabalík.cz (abbrevation). Používá se v API jako extraService.
    ↳ fullnamestringCelý název doplňkové služby
    ↳ descriptionstringStručný popis doplňkové služby.
    ↳ isActive 1]tinyint0, 1Indikace 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]tinyint0, 1Indikace 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).
    ↳ supportedAgentsarrayPřepravci, kteří danou službu podporují. V případě zaslání nepodporované služby bude vrácena chyba.
        ↳ agentFullnamestringCelý název přepravce.
        ↳ agentAbbrstringZkratka přepravce (abbrevation) využívaná ve Štíteknabalík.cz jako agent.
        ↳ requiredArgumentsarrayPovinné parametry, která je nutné zaslat, pokud danou službu využijete. Používá se v API jako extraServices.arguments
            ↳ identifierstringIdentifiká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
            ↳ namestringNázev povinného parametru.
            ↳ examplestringUká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)

PoleDatový typHodnotyPopis
dataarraySeznam stavů roztříděných do kontejnerů podle detailu stavů.
    ↳ stateCategory|stateSubcategory|statearrayViz popis kontejnerů níže.
        ↳ keystringKlíč. Unikátní textová reperezntace stavu zásilky (lower case).
        ↳ codeint|float|nullUnikátní číselný kód stavu zásilky. Je obsažen v odpovědi metody deliveries/traces/GET
        ↳ namestringNázev stavu (human readable).
        ↳ descriptionstringInformace 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)

PoleDatový typHodnotyPopis
dataarraySeznam všech ZPL formátů daného přepravce.
    ↳ agentAbbrstringGLS, PPL,...Zkratka přepravce
    ↳ sizestring10x15, 10x5, 10x17,...Rozměry štítku přepravce v cm.
    ↳ codedpi300, 203Podporované DPI
    ↳ nameprintOriginfoxdeli, agentPů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.
    ↳ orientationstringportrait, landscapeOrientace štítku. Informace je vhodná pro přípravu na automatizovaný tisk.
    ↳ isAgentDefault1, 01 - 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.