# Konvence API · Dokumentace DameDokladu

> Částky v haléřích, ID objektů, data, stránkování a opakování požadavků.

Source: https://damedoklad.cz/docs/conventions/

# Konvence API

Částky v haléřích, ID objektů, data, stránkování a opakování požadavků.

Tyto zásady platí pro celé API. Odpovídají tomu, jak se API dnes chová.

## Částky v haléřích

Peníze jsou v API vždy **celá čísla v haléřích** a pole končí na `Haler`. 100 je 1 Kč, 1 840 000 je 18 400 Kč. U dokladu v cizí měně jde o setiny měny dokladu, kterou uvádí pole `currency`.

Sazby a procenta jsou běžná čísla, například `"vatRate": 21`. Desetinná čísla pro peníze nikdy nepoužívejte.

```json
{ "unitPriceHaler": 1840000, "vatRate": 12, "totalHaler": 2060800 }
```

## Množství

Řádky dokladů mají `quantity` jako desetinné číslo, API ho ukládá na tisíciny. Pole s příponou `Milli` jsou množství v tisícinách, `1500` je 1,5 kusu.

## Data

Data jsou řetězce ve formátu `RRRR-MM-DD`, například `2026-10-30`.

## ID objektů

Každý objekt má `id` ve tvaru `xxx_` a 27 znaků, celkem 31 znaků, například `inv_2n9F7sB1kZ4mQw8eRtYuIoPaSdF`. Předpona říká, o jaký objekt jde: `con_` kontakt, `inv_` vydaná faktura, `wsp_` firma. ID považujte za neprůhledný řetězec a neskládejte ho.

## Tvar odpovědi

Objekt nese svůj typ a ID:

```json
{ "object": "invoice", "id": "inv_…", "status": "draft" }
```

## Seznamy a stránkování

Seznam vrací `{ "object": "list", "data": […], "hasMore": false }`. Dnes se setkáte se dvěma variantami:

| Operace | Parametry | Odpověď |
| --- | --- | --- |
| Operace agend (účetnictví, banka, sklad…) | `limit` (1 až 500, výchozí 100), `offset`, `search`, `from`, `to` | `data`, `total`, `hasMore` |
| Starší operace dokladů a kontaktů | vlastní filtry podle operace | `data`, `hasMore: false`, vrací celý výsledek filtru |

Kterou variantu operace používá, poznáte v [API referenci](/docs/api-reference/): parametr `limit` je u ní uvedený. Další stránku načtete zvýšením `offset`, dokud je `hasMore` pravda:

```bash
curl "https://api.damedoklad.cz/v1/…?limit=100&offset=100" \
  -H "Authorization: Bearer $DAMEDOKLAD_API_KEY"
```

## Opakování požadavků

API dnes **nepodporuje hlavičku `Idempotency-Key`**. Co to znamená v praxi:

-   `GET` můžete opakovat bezpečně.
-   Opakovaný `POST`, který vytváří objekt, vytvoří další objekt. Po síťové chybě nejdřív ověřte seznamem, jestli se první pokus nepovedl.
-   Přechody stavu se dvakrát neprovedou: druhé vystavení faktury vrátí `409`, protože vystavit jde jen koncept.
-   U přijatých faktur hlídá API duplicity podle dodavatele a čísla dokladu. Zkontrolovat je můžete předem operací `GET /v1/received-invoices/duplicate-check`.

## Zaúčtované zápisy

Zaúčtovaný zápis se neupravuje. Opravuje se protizápisem a do uzavřeného období zapsat nejde. Operace, které by to porušily, vrátí chybu.