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:

Pole	Význam
integrationsCount	Počet aktivních integrací, které byly spuštěny.
integrationsFailedCount	Počet integrací, jejichž spuštění selhalo (například nedostupný e-shop nebo odmítnuté připojení).
importedShipmentsCount	Celkový počet nových objednávek uložených jako koncepty zásilek do košíku.

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.