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

:::tip[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:

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:

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

:::warning

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:

```bash
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.

:::note[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**:

```bash
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:

```json
{
  "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.

:::tip[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](/api), kde si volání můžete rovnou vyzkoušet.