OmniCart – vytvoření zásilky přes API

OmniCart je správce zásilek v Zaslatu – místo, kde si chystáte zásilky, vidíte u nich ceny dopravců a odsud je hromadně odbavujete. Toto API vám umožní založit zásilku přímo z vašeho systému (e-shopu, skladového programu, vlastní aplikace), aniž byste cokoli překlikávali ručně.

Zásilka se do OmniCartu uloží jako rozpracovaný koncept (draft). Nic se hned neodesílá – vy nebo vaši kolegové si zásilku ve správci v klidu zkontrolujete, vyberete dopravce a teprve pak ji odešlete.

K čemu se to hodí

E-shop bez plné integrace – po přijetí objednávky rovnou „nahrajete“ zásilku do Zaslatu.
Hromadná příprava – váš systém přes noc nasype desítky zásilek, ráno je jen zkontrolujete a odešlete.
Vlastní workflow – zásilky vznikají automaticky z vašich dat, ale konečné slovo má vždy člověk.

Než začnete

Potřebujete jen dvě věci:

API klíč – najdete ho v nastavení svého účtu Zaslat. Podle klíče systém pozná, komu zásilka patří, takže ji rovnou uloží do správného OmniCartu.

Adresu API – všechny požadavky posíláte na:

Code
https://www.zaslat.cz/api/v2/public/cart/create

API klíč se posílá v hlavičce x-apikey u každého požadavku.

API klíč je jako heslo – nikdy ho nevkládejte do veřejného kódu (např. do frontendu e-shopu) a neposílejte ho e-mailem. Volání veďte vždy ze svého serveru.

Rychlý start

Nejjednodušší možná zásilka – stačí zadat kam se má doručit. Vše ostatní (odesílatel, balík, dopravce) se doplní z výchozího nastavení vašeho účtu:

Code
curl -X POST https://www.zaslat.cz/api/v2/public/cart/create \
  -H "x-apikey: VAS_API_KLIC" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "firstname": "Jan",
      "surname": "Novák",
      "street": "Sukova 4",
      "city": "Brno",
      "zip": "60200",
      "country": "CZ",
      "phone": "+420777777777",
      "email": "jan.novak@example.com"
    },
    "referenceNumber": "OBJ-2026-0001"
  }'

A je to – zásilka se objeví ve vašem OmniCartu jako koncept.

Chytré výchozí hodnoty

Nemusíte vyplňovat všechno. Když některé údaje vynecháte, Zaslat za vás doplní rozumnou volbu:

Když vynecháte…	…stane se toto
`from` (odesílatel)	Použije se výchozí odesílací adresa vašeho účtu.
`packages` (balíky)	Použije se výchozí balík nastavený na účtu.
`serviceId` (služba)	Vybere se nejlevnější dostupná služba.
`pickupBranch: 1`	Použije se výchozí podací místo vašeho účtu.

Trochu bohatší příklad

Když chcete mít věci pod kontrolou, můžete zadat odesílatele, rozměry balíku i konkrétní referenci. Rozměry zadávejte v centimetrech a hmotnost v kilogramech:

Code
curl -X POST https://www.zaslat.cz/api/v2/public/cart/create \
  -H "x-apikey: VAS_API_KLIC" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "company": "Acme Corp",
      "street": "Skladová 10",
      "city": "Praha",
      "zip": "10000",
      "country": "CZ",
      "phone": "+420777000000",
      "email": "sklad@acme.cz"
    },
    "to": {
      "firstname": "Jan",
      "surname": "Novák",
      "street": "Sukova 4",
      "city": "Brno",
      "zip": "60200",
      "country": "CZ",
      "phone": "+420777777777",
      "email": "jan.novak@example.com"
    },
    "packages": [
      { "weight": 2, "length": 30, "width": 20, "height": 15 }
    ],
    "referenceNumber": "OBJ-2026-0001"
  }'

Co se stane potom

Po úspěšném vytvoření dostanete zpět základní údaje o vytvořeném konceptu:

Code
{
  "id": 42,
  "source": "API",
  "referenceNumber": "OBJ-2026-0001",
  "errors": null,
  "rates": null,
  "modified": "2026-06-18 10:30:00"
}

Co která hodnota znamená:

id – identifikátor konceptu zásilky. Hodí se, když si chcete zásilku později spárovat se svým systémem.
referenceNumber – vaše reference (např. číslo objednávky), kterou vám API vrátí zpět.
errors – null znamená, že je koncept v pořádku. Pokud něco chybí nebo nesedí, najdete tu seznam upozornění.
rates – ceny dopravců. Na začátku je null, protože se počítají na pozadí. Chvíli po vytvoření se ve správci zásilek objeví samy.
modified – kdy byl koncept naposledy změněn.

Důležité

Vytvořením přes API se zásilka neodesílá. Vždy ji ještě uvidíte ve správci zásilek OmniCart, kde zkontrolujete ceny, případně doladíte detaily a teprve pak ji odešlete. Tím máte jistotu, že se nic neodešle omylem.

Když něco nevyjde

API odpoví chybovým stavem v těchto případech:

400 – v datech je chyba (např. neplatné PSČ nebo chybí povinný údaj). V odpovědi najdete popis, co opravit.
401 – chybí nebo je neplatný API klíč. Zkontrolujte hlavičku x-apikey.
500 – chyba na naší straně. Zkuste to prosím znovu, případně nás kontaktujte.

Kompletní přehled polí

Tady je popsané jen to nejdůležitější. Úplný seznam všech polí, jejich typů a omezení najdete v interaktivní API referenci, kde si volání můžete rovnou vyzkoušet.

Last modified on September 8, 2026