# API conventions · DameDoklad docs

> Amounts in haléře, object IDs, dates, paging and retrying requests.

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

# API conventions

Amounts in haléře, object IDs, dates, paging and retrying requests.

These rules apply across the API and describe how it behaves today.

## Amounts in haléře

Money in the API is always a **whole number of haléře**, and those fields end in `Haler`. 100 is CZK 1, 1,840,000 is CZK 18,400. On a document in a foreign currency, it means hundredths of the document’s currency, given in `currency`.

Rates and percentages are ordinary numbers, for example `"vatRate": 21`. Never use decimals for money.

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

## Quantities

Document lines have `quantity` as a decimal number, and the API stores it to thousandths. Fields ending in `Milli` are quantities in thousandths, so `1500` is 1.5 pieces.

## Dates

Dates are strings in `YYYY-MM-DD` format, for example `2026-10-30`.

## Object IDs

Each object has an `id` of the form `xxx_` plus 27 characters, 31 in total, for example `inv_2n9F7sB1kZ4mQw8eRtYuIoPaSdF`. The prefix tells you the object type: `con_` contact, `inv_` issued invoice, `wsp_` company. Treat IDs as opaque strings and never build them yourself.

## Response shape

An object carries its type and ID:

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

## Lists and paging

A list returns `{ "object": "list", "data": […], "hasMore": false }`. Today you will meet two variants:

| Operations | Parameters | Response |
| --- | --- | --- |
| Module operations (accounting, bank, inventory…) | `limit` (1 to 500, default 100), `offset`, `search`, `from`, `to` | `data`, `total`, `hasMore` |
| Older document and contact operations | filters specific to the operation | `data`, `hasMore: false`, returns the whole filtered result |

The [API reference](/en/docs/api-reference/) shows which one an operation uses: the `limit` parameter is listed. Load the next page by raising `offset` while `hasMore` is true:

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

## Retrying requests

The API **does not support an `Idempotency-Key` header** today. In practice:

-   You can safely repeat a `GET`.
-   Repeating a `POST` that creates an object creates another object. After a network error, check with a list first whether the first attempt succeeded.
-   State transitions do not run twice: issuing an invoice a second time returns `409`, because only a draft can be issued.
-   For received invoices, the API watches for duplicates by supplier and document number. You can check in advance with `GET /v1/received-invoices/duplicate-check`.

## Posted entries

A posted entry is never edited. It is corrected with a counter-entry, and a closed period takes no new entries. Operations that would break this return an error.