Založte si e-shop zdarma a získejte 10 000 AI kreditů na start. Bez karty, bez závazku.E-shop zdarma + 10 000 AI kreditů na start

Začít zdarma
Přeskočit na obsah
Přihlásit seVyzkoušet zdarma
Obsah dokumentace

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í.

Ověřeno 16. 9. 2026Markdown verze

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, klíč a oprávnění Autentizace a oprávnění a průchod výpisem Stránkování a filtry.

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.
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}

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.
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

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.
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

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.
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.