# Objednávka ze svozové adresy

:::info[Rozšířená specifikace]
Jedná se o rozšířenou specifikaci endpointu `https://www.zaslat.cz/api/v1/shipments/create` —
viz [Vytvoření objednávky zásilek](/api-v1/zasilky#vytvoreni-objednavky-zasilek) v API Referenci.
:::

## Typ svozu

Pokud si přeje klient vlastní tisk štítků, kterými balíky sám polepí a následně v jednorázové nebo pravidelné objednávce svozu kurýrovi předá, je potřeba zvolit typ `OCCASIONAL`.

U jednorázové objednávky je používán typ `ONDEMAND`. Značí jednorázovou objednávku z adresy, která nemusí být smluvní. Kurýr na tuto adresu přijede s připraveným štítkem, kterým opatří přepravovaný balík.

## Předpoklady pro vlastní tisk štítků

- pod uživatelem daného `x-apikey` musí být vytvořena svozová adresa s aktivní přepravní službou:
  - adresa musí být aktivní,
  - ke svozové adrese jsou registrováni smluvní přepravci (zajistí se automaticky při vytváření svozové adresy, nebo dodatečně kontaktováním konkrétního dopravce),
  - na adrese může být naplánován pravidelný svoz;
- zákazník musí mít aktivní smlouvu s možností platby na fakturu.

**Při volání metody `create` je pak potřeba uvést právě tyto parametry:**

- platba na fakturu,
- typ svozu,
- ID svozové adresy,
- kód přepravní společnosti registrované na ID svozové adresy.

---

## Kde zkontroluji náležitosti

Kontrolu náležitostí mohu provést v **Manažeru zásilek** ([app.zaslat.cz](https://app.zaslat.cz)).

Zákazník musí mít platnou smlouvu, kterou mohu zkontrolovat na stránce `Přehled`. U své firmy vidím smlouvu `Profi`, `Flexi` … .

Svozovou adresu mohu zkontrolovat na stránce `Svozy → Svozové adresy`, nebo tamtéž vytvořit novou svozovou adresu. U každé svozové adresy je dostupné **Nastavení dopravců**, které zobrazuje, kteří přepravci jsou aktivní, případně u kterých je naplánován pravidelný svoz. Samotné ID svozové adresy naleznu v závorce za názvem svozové adresy (ID 123456789). Do API volání je nutné použít uvedené ID svozové adresy a textové označení přepravní společnosti.

---

## Export zásilek ze svozové adresy s vlastním tiskem štítků

Nutné údaje volání metody `create`:

| Parametr | Typ | Popis | Povinný |
| --- | --- | --- | --- |
| `payment_type` | string | platba na fakturu = `INVOICE` | Ano |
| `shipments.[].type` | string | příležitostný svoz = `OCCASIONAL` | Ano |
| `shipments.[].from.id`\* | int | ID aktivní svozové adresy | Ano |
| `shipments.[].carrier`\*\* | string(20) | kód přepravní společnosti podle [číselníku `Carrier`](/api-v1/~schemas#carrier) | Ano |

:::note
\* V objektu `from` neuvádějte další parametry kromě `id`.

\*\* Přepravce musí být na daném ID svozové adresy aktivován.
:::

### Příklad dotazu

Příklad těla požadavku metodou **`POST`** (zkrácený výpis — vynechané části jsou označené `...`):

```json
{
    "payment_type": "INVOICE",
    "currency": "CZK",
    "payer": {
    ...
    },
    "shipments": [
        {
            "from": {
                "id": 123654
            },
            "to": {
                .....
            },
            "type": "OCCASIONAL",
            "packages": [
                {
                    .....
                }
            ],
            "carrier": "DPD",
            "currency": "CZK",
            "pickup_date": "2023-11-30"
        }
    ]
}
```

## Příklad implementace (PHP)

Ukázka volání endpointu `shipments/create` pro svoz s vlastním tiskem štítků (typ `OCCASIONAL`)
pomocí PHP a knihovny `curl` (zkrácený výpis JSON těla — kompletní tvar viz
[Příklad dotazu](#příklad-dotazu) výše).

```php
<?php
$data = [
    "payment_type" => "INVOICE",
    "currency" => "CZK",
    "shipments" => [
        [
            "from" => [
                "id" => 123654,
            ],
            "to" => [
                .....
            ],
            "type" => "OCCASIONAL",
            "packages" => [
                .....
            ],
            "carrier" => "DPD",
            "currency" => "CZK",
            "pickup_date" => "2023-11-30",
        ],
    ],
];

// Místo <VAS-API-KLIC> doplňte váš API klíč.
$ch = curl_init("https://www.zaslat.cz/api/v1/shipments/create");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Accept: application/json",
        "Content-Type: application/json",
        "X-Apikey: <VAS-API-KLIC>",
    ],
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);

// Odpověď serveru (JSON) převedeme na asociativní pole.
$response = json_decode($response, true);
```

## Jak získám štítek

Po dokončení exportu zásilky získáte identifikátor zásilky `tracking_number`, na základě kterého můžete dle [dokumentace získat štítek](/api-v1/zasilky#ziskani-stitku). Štítky je možné získat hromadně i z více různých zásilek. V rámci API volání můžete specifikovat různé další parametry dle formátu tiskárny štítků apod.

V případě exportu zásilky s vlastním tiskem štítků se tento štítek navíc posílá v příloze e-mailu objednateli. Oproti API volání obdržíte v e-mailu pouze štítky, které se vztahují k balíkům dané zásilky.