Balíkonoš.cz

Základní informace

Balíkonoš API je založeno na RESTové architektuře. K jeho korektnímu používání musíte:

• Přistupovat pouze přes zabezpečený protokol HTTPS.
• Získat oprávnění přístupu od společnosti zaregistrované na našem webu.
• Autentizovat se pomocí HTTP Bearer autentizace.
• Zasílat data pouze s kódováním UTF-8.

Prostředí API

Pro snadné napojení na naše API je Vám k dispozici testovacím prostředí, které je zcela totožné z produkčním, nicméně Vámi vložená data jsou oddělena a nejsou zasílána ke zpracování skutečným přepravcům.

• Produkční prostředí je přístupné z adresy https://balikonos.cz
• Testovací prostředí je přístupné z adresy https://test.balikonos.cz

Autentizace a autorizace

Všechny požadavky kromě kořenového zdroje vyžadují HTTP Bearer autentizaci. K přístupu tedy potřebujete získat takzvaný access_token pomocí protokolu OAuth 2.0, více v jeho dokumentaci.

Vzhledem k povaze této autentizace je NUTNÉ přistupovat vždy přes protokol HTTPS. Byť jediný přístup k API přes HTTP s korektní hlavičkou Authorization může teoreticky vést k odposlechnutí vašich přístupových údajů.

HTTP kódy

Prvotním ověřením na Vaší straně by vždy měla být kontrola vrácného HTTP kódu. Všechny tyto kódy odpovídají specifikaci HTTP. Níže naleznete krátký popis možných kódů v odpovědi:

• 200 OK - požadavek byl úspěšně zpracován
• 201 Created - požadavek byl úspěšně zpracován a nový zdroj byl vytvořen (typická odpověď po úspěšném POST požadavku)
• 304 Not Modified - odpověď se shoduje s cacheovaým obsahem, tělo odpovědi je prázdné, viz cacheování
• 400 Bad Request - byl přijat neplatný požadavek, například nevalidní formát vstupních dat
• 401 Unauthorized - autentizace selhala, chybí hlavička Authorization nebo obsahuje neplatné údaje
• 404 Not Found - požadovaný zdroj (URL) neexistuje
• 405 Method Not Allowed - byla použita neplatná HTTP metoda pro daný zdroj, v odpovědi lze nalézt platné metody
• 406 Not Acceptable - byla použita nepodporovaná hlavička Accept
• 410 Gone - přistupujete na starou verzi API
• 412 Precondition Failed - pokus o aktualizaci změněného zdroje
• 414 Request-URI Too Large - byl odeslán požadavek s příliš dlouhou URI
• 415 Unsupported Media Type - byla přijata nepodporovaná hlavička Content-type
• 422 Unprocessable Entity - data požadavku neprošla validací, například neplatná váha zásilky
• 426 Upgrade Required - byl použit nezabezpečený protokol HTTP
• 500 Internal Server Error - došlo k chybě v aplikaci na naší straně
• 503 Service Unavailable - služba je dočasně nedostupná (probíhá údržba naší aplikace)

Formáty komunikace

Abychom Vám co nejvíce ulehčili napojení na naše API, podporujeme několik formátů dat v komunikaci. Použití je snadné:

• Pro specifikaci formátu dat v odpovědi z našeho serveru uveďte korektní MIME type v hlavičce Accept
• Pro specifikaci formátu dat zasílaných v požadavku na náš server uveďte korektní MIME type v hlavičce Content-Type

Podporované formáty

• JSON - uveďte MIME type application/json v dané hlavičce (doporučený formát)
• XML - uveďte MIME type application/xml v dané hlavičce (deprecated)
• form-urlencoded - uveďte MIME type application/x-www-form-urlencoded v dané hlavičce (deprecated)

---

Accept hlavička

Pokud hlavička Accept není uvedená, nebo používá generické */*, je jako výchozí formát použit JSON. V případě neplatné či nepodporované hlavičky Accept je chybová zpráva vrácena také ve formátu JSON.

XML odpovědi

Pokud se rozhodnete využívat formát XML pro odpovědi z našeho serveru, kořenový tag je vždy <root>

Nevalidní vstupní formát

Pokud přijmeme nevalidní vstupní formát, je vrácen HTTP kód 400 s popisem chyby.

Formát datumů

Pokud není uvedeno jinak, všechny datumové formáty jsou ve formátu ISO 8601, např. 2014-12-31T18:25:50+02:00

Formát desetinných čísel

Lze používat desetinnou čárku i desetinnou tečku. Oddělovač tisíců nesmí být použit.

Výjimky

Pokud dojde k chybě na naší straně na nižší než aplikační úrovni, může být odpověd v jiném formátu, než bylo požadováno v hlavičce Accept. Tyto chyby mohou nastat při serverových chybách či údržbě aplikace, proto doporučujeme před parsováním odpovědi zkontrolovat vrácený HTTP kód. Příkladem může být i chyba 414. Pokud je vrácen kód 5xx, je možné, že odpověď není v očekávaném formátu.

Struktura odpovědí:

Všechny odpovědi dodržují stejnou strukturu odpovědi. Konkrétní odpověď záleží na požadovaném formátu dat, nicméně struktura je vždy následující:

Úspěšná odpověď:

root
--- code
--- status
--- message
--- data
                    

Chybová odpověď:

root
--- code
--- status
--- message
--- errors
--- ---
--- --- --- message
--- --- --- field
--- --- --- value
--- ---
--- --- --- message
--- --- --- field
--- --- --- value
                    

---

XML příklad chybové odpovědi

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <code>422</code>
    <status>error</status>
    <message>Validation failed</message>
    <errors>
        <message>This value should be of type float.</message>
        <field>[0].packages[0].weight</field>
        <value>3 kg</value>
    </errors>
    <errors>
        <message>Invalid currency format, expected ISO 4217</message>
        <field>[0].valueCurrency</field>
        <value>€</value>
    </errors>
</root>
                    

JSON příklad chybové odpovědi

{ "code": 422, "status": "error", "message": "Validation failed", "errors": [ { "message": "This value should be of type float.", "field": "[0].packages[0].weight", "value": "3 kg" }, { "message": "Invalid currency format, expected ISO 4217", "field": "[0].valueCurrency", "value": "€" } ] }

Popis položek

• code je obecné označení chyby totožné s HTTP kódem
• status značí stav požadavku, možné hodnoty jsou: success, error
• message obecný popis chyby (anglicky)
• data data odpovědi, pouze pro úspěšné odpovědi, ne vždy přítomné, struktura se liší pro různé požadavky
• errors pole chyb, pouze pro chybové odpovědi, ne vždy přítomné
• errors.message je anglický popis konkrétní chyby (o české chyby lze zažádat hlavičkou accept-language: cs)
• errors.field je cesta k položce, kde k chybě došlo (viz příklady výše)
• errors.value je chybná hodnota (nemusí se přesně shodovat s odeslanou hodnotou)

---

Všechny klíče jsou vždy ve formátu camelCase. Bližší popis možných chybových odpovědí, kódů a strukturu úspěšné odpovědi najdete přímo u konkrétních metod a zdrojů.

Testování a debugování

Je velmi pravděpodobné, že při vývoji budete chtít ověřit co API vrací na různé požadavky.

Vytvoření testovacího účtu

Velmi rychle můžete začít testovat naše API, pokud zaregistrujete testovací společnost na adrese https://test.balikonos.cz. Jde o separátní prostředí s oddělenou databází, kde nedochází k reálnému objednávání přepravy. Pro testování konkrétního přepravce je zapotřebí v klientské zóně zadat libovolné testovací autentizační údaje. Pro testování zásilek bez automatického zahrnutí přímé zásilky (například u GLS) je zapotřebí vytvořit typ svozu u požadovaného svozového místa. Veškeré vložené údaje přes API se samozřejmě projeví i v uživatelském prostředí tohoto prostředí, takže můžete kontrolovat Vámi vložená data přímo v prohlížeči.

cURL

Asi nejjednoušší možnost jak testovat naše API je pomocí nástroje cURL z příkazové řádky. Ukázka možného použití:

curl -H "Accept: application/xml" -H "Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e" http://balikonos.cz/api/

Jiné nástroje

Existuje celá řada dalších nástrojů k testování RESTových API, například rozšíření Chrome prohlížeče POSTman.

Verzování API

Použití jednotlivých verzí API je určeno v adrese zdroje. Aktuálně je API ve třetí verzi, tedy URL všech zdrojů začínají na http://balikonos.cz/api/v3. O implementaci nových verzí Vás budeme informovat, přečemž původni verze bude po nějakou dobu stále funkčí. Minoritní změny v API, které neovlivňují dosavadní funkčnost se v adrese neprojeví.

Changelog

• v1 - iniciální verze API, již nepodporována
• v2 - zatím podporovaná verze, došlo ke změně autorizace (nyní pomocí OAuth 2.0)
• v3 - aktuální verze, přepracováno vkládání zásilek, více v návodu k migraci

Komprimace přenesených dat

Pokud v požadavku uvedete hlavičku Accept-encoding: gzip, výsledné tělo odpovědi Vám přijde v komprimované podobě gzip. Tato metoda ušetří u souborů XML kolem 80 % přenesených dat! Pro JSON jde cca o 65 % dat.

Komprimovaná data se vrátí spolu s hlavičkou Content-encoding: gzip. Na vás je pouze dekódování přijatého obsahu, což je ve většině jazyků velmi snadné. Viz například PHP. Stejně tak můžete i vy zasílat tělo zprávy komprimované pomocí gzip metody. Je však nutné uvést hlavičku Content-encoding: gzip.

Taktéž je možné nakonfigurovat Váš server tak, aby tuto komprimaci a dekomprimaci prováděl zcela automaticky, viz například apache.

Jelikož množství přenášených dat může být skutečně velké, výrazně doporučujeme používat komprimaci vždy a všude.

HTTP Cacheování

Všechny GET metody vracejí odpovědi s hlavičkou ETag, která obsahuje hash aktuálně vrácené odpovědi. Tuto hodnotu je vhodné ukládat spolu s vrácenými daty a v případě potřeby stejného dotazu v budoucnu doplnit hash do hlavičky If-None-Match. Pokud se totiž odpověď od Vašeho posledního dotazu nezměnil, HTTP odpověď bude mít kód 304 a tělo bude prázdé – ušetříte tedy datový přenos obsahu, který již máte uložený z předchozího požadavku. Toto je obzvláště vhodné při dotazech vracejících větší množství dat (například PDF štítky). Chování si můžete prohlédnout i v prohlížeči na kořenovém zdroji:

curl -D - http://balikonos.cz/api HTTP/1.1 200 OK Cache-Control: max-age=0 ETag: "19d51838d5c25d289a79709d957de955" Content-Length: 112 Content-Type: application/json; charset=UTF-8 { "code": 200, "status": "success", "message": "See documentation: http://balikonos.cz/doc-api/" } curl -D - -H 'If-None-Match: "19d51838d5c25d289a79709d957de955"' http://balikonos.cz/api HTTP/1.1 304 Not Modified Cache-Control: max-age=0 ETag: "19d51838d5c25d289a79709d957de955"

Další funkce

Přetížení metody POST

Pokud vaše aplikace z nějakého důvodu neumožňuje zasílat PUT či DELETE HTTP požadavky, je možné přetížit metodu POST. Pokud nastavíte hlavičku X-HTTP-Method-Override na některou ze zmíněných hodnot (PUT či DELETE) při POST požadavku, bude vykonána stejná akce, jako kdyby se provedl PUT či DELETE požadavek.

Takto přetížit lze pouze metoda POST, nikoli GET. Metoda GET je totiž safe a nesmí měnit stav zdroje.

Formátování výstupu

Standardní JSON a XML odpovědi obsahují odřádkování i odsazení vnitřních elementů pro lepší čitelnost. Toto chování lze vypnout nastavením query parametru prettyPrint na false. Viz například kořenový zdroj. Tímto lze také mírně snížit objem přenášených dat.

Nepodporované funkce

JSONP

Podpora pro JSONP není z technického hlediska možná z důvodu HTTP Bearer autentizace.

CORS

Podpora Cross-origin resource sharing zatím není implementována. Pokud byste měli zájem o tuto funkcionalitu, dejte nám vědět.