# REST API: doklady, PDF a ISDOC > Referenční popis cest dokladů: výpis, detail s rekapitulací DPH a stažení PDF a ISDOC, s parametry, poli odpovědi, chybami a ukázkou volání. - Sekce: Pro vývojáře - Stránka: https://shopzi.cz/dokumentace/vyvojari/rest-doklady - Ověřeno: 2026-09-16 --- Pro účetní software: co bylo vystaveno, komu, kdy a na kolik, i s rekapitulací DPH, PDF a ISDOC. Cesty odpovídají na `GET` na doméně vašeho obchodu, například `https://muj-eshop.cz/api/v1/…`, a klíč se posílá v hlavičce `Authorization: Bearer` nebo `x-api-key`. Parametry, pole i chyby na téhle stránce se generují ze smlouvy, podle které API odpovídá, takže platí pro build, na kterém stránka běží. Každá cesta může navíc vrátit chyby společné všem cestám: `invalid_api_key`, `missing_api_key`, `external_access_disabled`, `external_access_not_enabled`, `external_access_suspended`, `key_surface_mismatch`, `plan_required`, `shop_unavailable`, `shop_not_found`, `rate_limited` a `server_error`. Co znamenají, popisuje článek [Chybové odpovědi](/dokumentace/vyvojari/chybove-odpovedi), klíč a oprávnění [Autentizace a oprávnění](/dokumentace/vyvojari/autentizace-a-opravneni) a průchod výpisem [Stránkování a filtry](/dokumentace/vyvojari/strankovani-a-filtry). ## `GET /api/v1/documents` [#get-api-v1-documents] Vystavené doklady: druh, číslo, datum vystavení a DUZP, částka a IČO a DIČ odběratele. Doklad se nemění, proto tu updated\_since stránkuje podle vzniku dokladu. * **Oprávnění:** `documents:read`, u klíče „Doklady: metadata, položky a stažení PDF/ISDOC (čtení)“. * **Odpověď:** stránka výpisu, záznamy jsou v `data` a jak otevřít další stránku, říká seznam Obálka odpovědi. * **Synchronizace:** s `updated_since` se výpis řadí podle pole `created_at` od nejstarší změny, bez něj od nejnovějšího záznamu. Pole `created_at`: Kdy doklad vznikl. Vystavený doklad se nemění, podle tohoto času stránkuje `updated_since`. ```bash curl -s "https://muj-eshop.cz/api/v1/documents?limit=100" \ -H "Authorization: Bearer $SHOPZI_API_KEY" ``` **Parametry dotazu** * `limit` (celé číslo od 1 do 100, výchozí `25`; nepovinný): Počet řádků na stránku, výchozí 25. Vyšší hodnota se ořízne na 100, nesmysl spadne na výchozí. * `cursor` (text; nepovinný): Hodnota `next_cursor` z předchozí stránky, beze změny. Platí jen pro tentýž dotaz. * `updated_since` (čas ISO 8601; nepovinný): ISO 8601 se zónou `Z` nebo s číselným posunem (`+02:00`). Vrátí záznamy změněné od té chvíle včetně, seřazené od nejstarší změny, a stránkuje stabilně: řádek změněný během průchodu se v něm neopakuje a přijde v příštím. Hodnota `next_updated_since` jde do adresy vložit bez kódování; `+` z nezakódované adresy se čte jako `+`. * `doc_type` (jedna z hodnot `order`, `invoice`, `credit_note`, `proforma`, `pos_receipt` a `quotation`; nepovinný): Druh dokladu. **Obálka odpovědi** * `data` (pole záznamů): Záznamy stránky, jejich pole popisuje seznam Pole záznamu. * `next_cursor` (text nebo `null`): Kurzor další stránky, `null` = tohle je poslední stránka. * `next_updated_since` (čas ISO 8601): Hodnota `updated_since` pro příští průchod: začátek tohoto průchodu mínus 5 minut. Na všech stránkách jednoho průchodu je stejná a do adresy jde vložit bez kódování. **Pole záznamu** * `id` (UUID) * `doc_type` (jedna z hodnot `order`, `invoice`, `credit_note`, `proforma`, `pos_receipt` a `quotation`) * `doc_number` (text): Evidenční číslo z gapless řady. * `order_id` (UUID nebo `null`) * `issued_at` (čas ISO 8601) * `duzp` (datum RRRR-MM-DD): Datum uskutečnění zdanitelného plnění, `RRRR-MM-DD`. * `total_minor` (celé číslo): Celkem s DPH v haléřích, vždy kladně. Dobropis fakturaci snižuje. * `currency_code` (text se vzorem `^[A-Z]{3}$`): Kód měny podle ISO 4217, dnes vždy CZK. * `tax_regime` (jedna z hodnot `standard`, `reverse_charge`, `oss`, `ioss` a `non_payer`): `reverse_charge` = přenesená daňová povinnost, `oss` a `ioss` = zvláštní režimy EU, `non_payer` = dodavatel není plátce DPH. * `customer_ico` (text nebo `null`) * `customer_dic` (text nebo `null`) * `created_at` (čas ISO 8601): Kdy doklad vznikl. Vystavený doklad se nemění, podle tohoto času stránkuje `updated_since`. **Chyby této cesty** * **400** `invalid_query`: Parametr dotazu má neplatnou hodnotu: čas v updated\_since bez časového posunu, nebo hodnota filtru, kterou výčet nezná. Zpráva jmenuje parametr, u filtru i povolené hodnoty. * **400** `invalid_cursor`: Kurzor je poškozený, nebo patří k jinému dotazu (jiná cesta, jiný filtr nebo jiné updated\_since). Začněte průchod znovu bez cursor. * **403** `insufficient_scope`: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má. ## `GET /api/v1/documents/{id}` [#get-api-v1-documents-id] Faktura, proforma nebo dobropis celý: položky, dodavatel a odběratel s IČO a DIČ a rekapitulace DPH po sazbách v haléřích. Objednávka, cenová nabídka a účtenka daňový detail nemají. * **Oprávnění:** `documents:read`, u klíče „Doklady: metadata, položky a stažení PDF/ISDOC (čtení)“. * **Odpověď:** jeden záznam v `data`. ```bash curl -s "https://muj-eshop.cz/api/v1/documents/$ID" \ -H "Authorization: Bearer $SHOPZI_API_KEY" ``` **Parametry v cestě** * `id` (UUID; povinný): Identifikátor záznamu (UUID) z výpisu. **Obálka odpovědi** * `data` (záznam): Jeho pole popisuje seznam Pole záznamu. **Pole záznamu** * `id` (UUID): Týž identifikátor, jaký vrací výpis dokladů. * `doc_type` (jedna z hodnot `invoice`, `credit_note` a `proforma`) * `doc_number` (text) * `order_id` (UUID nebo `null`) * `order_number` (text nebo `null`) * `issued_at` (čas ISO 8601) * `issue_date` (datum RRRR-MM-DD): Datum vystavení v českém kalendáři. * `duzp` (datum RRRR-MM-DD nebo `null`): DUZP. U dobropisu `null` (ISDOC §A.5). * `due_date` (datum RRRR-MM-DD nebo `null`) * `currency_code` (text se vzorem `^[A-Z]{3}$`): Kód měny podle ISO 4217, dnes vždy CZK. * `tax_regime` (jedna z hodnot `standard`, `reverse_charge`, `oss`, `ioss` a `non_payer`) * `is_vat_payer` (`true` nebo `false`): Je dodavatel plátcem DPH? * `payment_method` (jedna z hodnot `card_online`, `apple_pay`, `google_pay`, `bank_transfer`, `cod` a `invoice`, nebo `null`) * `variable_symbol` (text nebo `null`) * `is_paid` (`true` nebo `false`) * `supplier` (objekt) * `supplier.name` (text) * `supplier.company` (text nebo `null`) * `supplier.street` (text nebo `null`) * `supplier.city` (text nebo `null`) * `supplier.zip` (text nebo `null`) * `supplier.country` (text): ISO 3166-1 alpha-2. * `supplier.ico` (text nebo `null`) * `supplier.dic` (text nebo `null`) * `customer` (objekt) * `customer.name` (text) * `customer.company` (text nebo `null`) * `customer.street` (text nebo `null`) * `customer.city` (text nebo `null`) * `customer.zip` (text nebo `null`) * `customer.country` (text): ISO 3166-1 alpha-2. * `customer.ico` (text nebo `null`) * `customer.dic` (text nebo `null`) * `lines` (pole objektů) * `lines[].index` (celé číslo): Pořadí na dokladu, od 1. * `lines[].description` (text) * `lines[].quantity` (číslo) * `lines[].unit_code` (text) * `lines[].vat_rate` (celé číslo od 0 do 100) * `lines[].unit_price_gross_minor` (celé číslo) * `lines[].line_gross_minor` (celé číslo): Řádek před slevou, s DPH. * `lines[].line_discount_minor` (celé číslo) * `lines[].line_total_gross_minor` (celé číslo): Co se za řádek účtovalo, s DPH. * `shipping_gross_minor` (celé číslo) * `shipping_vat_rate` (celé číslo od 0 do 100) * `discount_total_minor` (celé číslo) * `rounding_minor` (celé číslo): České zaokrouhlení, sazba 0 %. Může být záporné. * `vat_breakdown` (pole objektů): Rekapitulace DPH po sazbách, doslova z neměnné tabulky. Nikdy se nedopočítává z řádků. * `vat_breakdown[].vat_rate` (celé číslo od 0 do 100) * `vat_breakdown[].base_minor` (celé číslo): Základ daně. * `vat_breakdown[].vat_minor` (celé číslo): DPH. * `vat_breakdown[].gross_minor` (celé číslo): Základ + DPH. * `total_base_minor` (celé číslo) * `total_vat_minor` (celé číslo) * `total_gross_minor` (celé číslo) * `original_doc_number` (text nebo `null`): U dobropisu číslo opravovaného dokladu (§ 45 ZDPH). * `correction_reason` (text nebo `null`) * `created_at` (čas ISO 8601) **Chyby této cesty** * **403** `insufficient_scope`: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má. * **404** `not_found`: Záznam s tímhle identifikátorem v obchodě není. * **422** `unsupported_document_type`: Doklad existuje, ale daňový není: objednávka, cenová nabídka ani účtenka nemají rozpis DPH, PDF faktury ani ISDOC. ## `GET /api/v1/documents/{id}/pdf` [#get-api-v1-documents-id-pdf] Doklad jako PDF, týž soubor, jaký stahuje administrace. Neukládá se do žádné sdílené mezipaměti. * **Oprávnění:** `documents:read`, u klíče „Doklady: metadata, položky a stažení PDF/ISDOC (čtení)“. * **Odpověď:** soubor typu `application/pdf` s příponou `pdf`. ```bash curl -sSf "https://muj-eshop.cz/api/v1/documents/$ID/pdf" \ -H "Authorization: Bearer $SHOPZI_API_KEY" \ -o soubor.pdf ``` Přepínač `-f` je tu kvůli chybám: když doklad neexistuje (404), curl skončí s chybou místo toho, aby chybovou odpověď uložil jako soubor. Bez něj by se do souboru zapsal chybový JSON. **Parametry v cestě** * `id` (UUID; povinný): Identifikátor záznamu (UUID) z výpisu. **Chyby této cesty** * **403** `insufficient_scope`: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má. * **404** `not_found`: Záznam s tímhle identifikátorem v obchodě není. * **422** `unsupported_document_type`: Doklad existuje, ale daňový není: objednávka, cenová nabídka ani účtenka nemají rozpis DPH, PDF faktury ani ISDOC. * **502** `pdf_unavailable`: PDF se teď nepodařilo vyrobit. Nic se nezměnilo, zkuste to s odstupem znovu. * **503** `pdf_busy`: Obchod právě vyrábí jiná PDF a další vykreslení by čekalo ve frontě. Počkejte tolik sekund, kolik říká hlavička Retry-After, a zkuste to znovu. Doklad, jehož PDF už existuje, tuhle odpověď nedostane. ## `GET /api/v1/documents/{id}/isdoc` [#get-api-v1-documents-id-isdoc] Doklad ve formátu ISDOC 6.0.2 k importu do účetního programu, například do POHODY, Money, ABRY nebo iDokladu. * **Oprávnění:** `documents:read`, u klíče „Doklady: metadata, položky a stažení PDF/ISDOC (čtení)“. * **Odpověď:** soubor typu `application/vnd.isdoc+xml` s příponou `isdoc`. ```bash curl -sSf "https://muj-eshop.cz/api/v1/documents/$ID/isdoc" \ -H "Authorization: Bearer $SHOPZI_API_KEY" \ -o soubor.isdoc ``` Přepínač `-f` je tu kvůli chybám: když doklad neexistuje (404), curl skončí s chybou místo toho, aby chybovou odpověď uložil jako soubor. Bez něj by se do souboru zapsal chybový JSON. **Parametry v cestě** * `id` (UUID; povinný): Identifikátor záznamu (UUID) z výpisu. **Chyby této cesty** * **403** `insufficient_scope`: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má. * **404** `not_found`: Záznam s tímhle identifikátorem v obchodě není. * **422** `unsupported_document_type`: Doklad existuje, ale daňový není: objednávka, cenová nabídka ani účtenka nemají rozpis DPH, PDF faktury ani ISDOC. * **422** `isdoc_invalid`: Doklad by neprošel pravidly ISDOC, typicky dobropis bez čísla opravovaného dokladu. Zpráva říká proč; opakování nepomůže, doklad je potřeba opravit v administraci.