Copy page

Úvod k API v2

Zaslat API v2 je nová generace veřejného API, která vzniká postupně vedle API v1. Zatím pokrývá práci s košíkem rozpracovaných zásilek (OmniCart), rušení objednávek svozu, stažení nových objednávek z propojených e-shopových integrací a vytvoření balíkové soupisky Zásilkovny s čárovým kódem pro kurýra; další oblasti budou přibývat.

Košík (OmniCart)

Košík obsahuje rozpracované zásilky — připravené, ale dosud závazně neobjednané. Endpoint cart/create založí v košíku koncept zásilky se zadanou trasou, balíky a doplňkovými službami; nic se v tu chvíli neobjednává ani neúčtuje. Odpověď vrací kromě identifikátoru konceptu i dostupné nabídky přepravy (rates), případně seznam nedostatků v datech (errors). Zásilky z košíku pak zkontrolujete, opravíte a závazně objednáte v Manažeru zásilek.

Stejný princip košíku využívají e-shopové integrace a MCP server — API v2 je cesta, jak košík plnit z vlastního systému.

Rušení svozů

Endpoint collection-request/cancel zruší objednaný svoz u daného dopravce pro zadané datum.

Stažení objednávek z e-shopových integrací

Endpoint integration/run spustí všechny aktivní e-shopové integrace propojené s vaším účtem, stáhne z každého e-shopu nové objednávky a uloží je jako koncepty zásilek do košíku. V tu chvíli se nic neobjednává ani neúčtuje; koncepty se nacení asynchronně a zkontrolujete, zaplatíte a závazně objednáte je v Manažeru zásilek. Objednávky stažené dříve se přeskakují, opakované volání proto nevytváří duplicity.

E-shopy se dotazují synchronně během požadavku; při více propojených integracích může odpověď trvat déle. Selhání jedné integrace neukončí celý požadavek — neúspěšné integrace se pouze započítají do pole integrationsFailedCount a podrobnosti najdete v logu integrace v Manažeru zásilek (Nastavení → Integrace). Integrace, kterou právě zpracovává jiný požadavek, se přeskočí: započítá se do integrationsCount, nezvýší integrationsFailedCount a nepřidá žádnou zásilku.

Odpověď obsahuje tři čítače:

Balíková soupiska Zásilkovny

Kurýr Zásilkovny může při svozu načíst všechny balíky jedním skenem, pokud mu předáte soupisku s čárovým kódem dávky. Endpoint handover/create přijme seznam vašich zásilek (tracking čísla IZ…), založí pro ně v Zásilkovně dávku a vrátí hotovou soupisku k tisku jako PDF, nebo na vyžádání data dávky v JSON: hodnotu barcode (Code 128), čitelný text barcodeText, hotový obrázek barcodeImage (PNG jako data URI) a seznam zásilek v dávce s příjemcem, městem a vaším referenčním číslem — vše potřebné pro tisk vlastní soupisky.

Do dávky lze zařadit jen zásilky z vašeho účtu, přepravované Zásilkovnou a už exportované k dopravci (mají číslo balíku Zásilkovny). Cizí nebo neexistující zásilka vrátí 404, zásilka jiného dopravce nebo bez čísla balíku 400; dotčená tracking čísla najdete v poli errors.

Každá zásilka si dávku pamatuje. Opakované volání se stejnými zásilkami vrátí stejný kód bez dalšího volání Zásilkovny; přidáte-li k už vytištěné soupisce nové zásilky, vznikne pro ně samostatná dávka a odpověď obsahuje více položek v batches — kurýr pak načte jeden kód za každou dávku. Zásilky předávané přes různé účty Zásilkovny (například CZ a SK) tvoří vždy samostatné dávky.

Balík, který už byl fyzicky předán dopravci nebo jde o vratku, Zásilkovna do dávky nepřijme. Takové zásilky požadavek neshodí: objeví se v poli rejectedShipments a dávka se vytvoří pro zbylé balíky. Pokud nezbude žádný, pole batches je prázdné.

Výstup volíte polem format v těle požadavku. Výchozí hodnota PDF vrátí soubor application/pdf ve formátu A4 — jedna stránka na dávku s čárovým kódem uprostřed, jeho textem, ID dávky u Zásilkovny a tabulkou zásilek, případně další stránka se seznamem nezařazených zásilek. Hodnota JSON vrátí data dávek popsaná výše pro tisk vlastní soupisky. Dávka vzniká a pamatuje se u obou formátů stejně; chybové odpovědi jsou vždy JSON.

Endpoint je omezen na 10 požadavků za 60 sekund na účet. Aktuální stav vracejí hlavičky X-Rate-Limit-Limit, X-Rate-Limit-Remaining a X-Rate-Limit-Reset; po překročení limitu dostanete 429.

Soupiska v PDF uložená do souboru (výchozí formát, pole format lze vynechat):

Code
curl -X POST https://test.zaslat.cz/api/v2/public/handover/create \
  -H "x-apikey: VAS_API_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"shipments": ["IZ3F9A2C71B4", "IZ8D01E6F2A9"]}' \
  -o soupiska.pdf

Stejný požadavek s daty dávky v JSON:

Code
curl -X POST https://test.zaslat.cz/api/v2/public/handover/create \
  -H "x-apikey: VAS_API_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"shipments": ["IZ3F9A2C71B4", "IZ8D01E6F2A9"], "format": "JSON"}'

Autentizace

Všechny požadavky je nutné posílat s autentizačním HTTP headerem x-apikey — stejně jako u API v1. API klíč najdete po přihlášení do Manažeru zásilek (app.zaslat.cz) v sekci Nastavení → Integrace, část Napojení pomocí API.

Vztah k API v1

API v1 zůstává v provozu beze změn — nadále slouží k získávání nabídek přepravy, závaznému objednávání zásilek, sledování a správě adresáře. API v2 jej doplňuje o scénář „připravit teď, objednat později": zásilky vložené do košíku přes API v2 dokončíte hromadně v Manažeru zásilek.