# Dobírka (COD)

:::info[Rozšířená specifikace]
Jedná se o rozšířenou specifikaci API dokumentace pro doplňkovou službu `COD` u endpointů
`rates/get` a `shipments/create`.
:::

Dobírku objednáte přidáním služby s kódem `COD` do pole `services` zásilky. Objekt `data` služby
odpovídá schématu [ServiceCOD](/api-v1/~schemas#servicecod).

## Parametry služby

| Parametr | Typ | Popis | Povinný |
| --- | --- | --- | --- |
| `value` | [Money](/api-v1/~schemas#money) | dobírková částka a měna | ano |
| `bank_account` | string(64) | číslo účtu pro výplatu dobírky | ano\* |
| `bank_code` | string(4) | čtyřmístný kód banky | ano\*\* |
| `bank_variable` | string(10) | variabilní symbol — pouze číslice | ne |
| `bank_currency` | string(3) | měna bankovního účtu (ISO 4217) | ne |
| `include_shipping_costs` | boolean | připočíst k dobírce cenu přepravy | ne |

:::note
\* Povinné při vytvoření zásilky (`shipments/create`). Při poptávce ceny (`rates/get`) účet
uvádět nemusíte. Pokud máte číslo účtu uloženo v nastavení účtu, předvyplní se automaticky.

\*\* Povinné u účtu v českém formátu. Pokud je v `bank_account` uveden IBAN, `bank_code` se
**neuvádí**.
:::

## Formát bankovního účtu

Účet lze zadat dvěma způsoby:

- **Český formát** — `číslo` nebo `předčíslí-číslo` (např. `12-34567890`), vždy společně se
  čtyřmístným kódem banky v `bank_code`. Číslo účtu podléhá kontrole podle standardu ČNB
  (modulo 11).
- **IBAN** — mezinárodní formát včetně kontrolních číslic (např. `CZ6508000000192000145399`).
  V tom případě nechte `bank_code` prázdný.

## Povolené směry a měny

| Směr | Měny dobírky |
| --- | --- |
| CZ → CZ | CZK |
| CZ → SK | CZK, EUR |

## Limity částky

- Minimální dobírková částka je **30 CZK**, resp. **1 EUR**.
- Částka v **CZK musí být celé číslo** — desetinná místa nejsou povolena.
- Maximální částka se liší podle konkrétní přepravní služby dopravce.

## Omezení dopravců

U vícekusových zásilek (více balíků v jedné zásilce) není dobírka dostupná v těchto případech:

| Dopravce | Omezení |
| --- | --- |
| Balíkovna | dobírka pouze pro jednokusové zásilky |
| DPD | pouze jednokusové, pokud je použito podací nebo výdejní místo |
| PPL | pouze jednokusové ve směru CZ → SK |

## Příklad dotazu

Příklad těla požadavku `POST /shipments/create` se zásilkou na dobírku:

```json
{
    "currency": "CZK",
    "payment_type": "CREDIT",
    "shipments": [
        {
            "carrier": "GLS",
            "pickup_date": "2026-07-10",
            "from": {
                "id": 1001
            },
            "to": {
                "firstname": "Karel",
                "surname": "Dvořák",
                "street": "Jánská 42",
                "city": "Brno",
                "zip": "60200",
                "country": "CZ",
                "phone": "+420602111222",
                "email": "karel.dvorak@example.com"
            },
            "services": [
                {
                    "code": "COD",
                    "data": {
                        "value": {
                            "value": 1500,
                            "currency": "CZK"
                        },
                        "bank_account": "12-34567890",
                        "bank_code": "0100",
                        "bank_variable": "20260001"
                    }
                }
            ],
            "packages": [
                {
                    "weight": 1,
                    "width": 10,
                    "height": 20,
                    "length": 30
                }
            ]
        }
    ]
}
```

Stejný objekt služby použijete i v `rates/get`, pokud chcete cenu přepravy včetně příplatku za
dobírku — tam stačí uvést pouze `value`.