Copy page

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.

Než začnete

Potřebujete jen dvě věci:

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

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

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.

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.

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.