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: exporty do souboru

Referenční popis exportů do souboru: objednávky, balíček dokladů pro účetní, katalog a podklad k DPH, malý hned a velký na pozadí, s odkazem ke stažení.

Ověřeno 16. 9. 2026Markdown verze

Tytéž soubory jako tlačítko Exportovat v administraci: objednávky v CSV, XLSX nebo jako prodejky POHODA (oprávnění orders:read), balíček dokladů pro účetní v ISDOC, CSV, XLSX, POHODA nebo Money S3 a měsíční podklad k DPH (documents:read) a katalog produktů v CSV (products:read). Export je čtení: nechce zápisové oprávnění ani povolený zápis přes REST. Malý export odpoví 200 s podepsaným odkazem ke stažení, který platí 15 minut a nechce klíč; velký odpoví 202 s id exportu, na jehož stav se ptáte cestou stavu exportu níž, dokud nevrátí odkaz. Hotový soubor na pozadí leží 24 hodin.

Cesty odpovídají na GET, POST, PUT, PATCH a DELETE 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, rest_write_disabled, rest_write_not_enabled, 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.

POST /api/v1/exports

Export do souboru jako tlačítko Exportovat v administraci: objednávky (CSV, XLSX, POHODA), balíček dokladů pro účetní (ISDOC, CSV, XLSX, POHODA, Money S3), katalog (CSV) a měsíční podklad k DPH. Malý hned s odkazem ke stažení, velký na pozadí.

  • Oprávnění: žádné, stačí libovolný platný klíč.
  • Odpověď: stav 200 s hotovým malým exportem, nebo 202 s exportem na pozadí (Location vede na GET /api/v1/exports/{id}); obojí v data.
curl -s -X POST https://muj-eshop.cz/api/v1/exports \
  -H "Authorization: Bearer $SHOPZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"orders"}'

Tělo požadavku (JSON, pole navíc se odmítnou)

  • kind (jedna z hodnot orders, documents, products a vat_paper; povinný): orders = objednávky (jako Exportovat v Objednávkách), documents = balíček dokladů pro účetní za období podle DUZP, products = katalog produktů, vat_paper = měsíční podklad k DPH z neměnných řádků DPH.
  • format (jedna z hodnot csv, xlsx, pohoda_xml, isdoc, pohoda a money_s3; nepovinný): Formát souboru po druzích: orders csv | xlsx | pohoda_xml (výchozí csv), documents isdoc | csv | xlsx | pohoda | money_s3 (povinný), products csv, vat_paper csv.
  • date_from (datum RRRR-MM-DD; nepovinný): Od data včetně, RRRR-MM-DD. U orders podle data objednávky, u documents podle DUZP (tam povinné).
  • date_to (datum RRRR-MM-DD; nepovinný): Do data včetně, RRRR-MM-DD. U documents povinné.
  • status (jedna z hodnot pending, received, confirmed, processing, shipped, delivered, completed, cancelled a rejected; nepovinný): Jen orders: stav objednávky.
  • payment_status (jedna z hodnot pending, authorized, paid, failed, refunded a partially_refunded; nepovinný): Jen orders: stav platby.
  • search (text, 1 až 120 znaků; nepovinný): Jen orders: hledání v čísle, jménu a e-mailu, jako v administraci.
  • is_quotation (true nebo false; nepovinný): Jen orders: true = jen poptávky, false = jen objednávky. Vynechané = obojí.
  • returned_only (true nebo false; nepovinný): Jen orders: true = jen objednávky s vratkou.
  • variant (jedna z hodnot souhrnny a detailni; nepovinný): Jen documents ve formátu csv a xlsx: souhrnny (výchozí) = řádek na doklad, detailni = řádek na položku.
  • year (celé číslo od 2000 do 2999; nepovinný): Jen vat_paper, povinné: rok.
  • month (celé číslo od 1 do 12; nepovinný): Jen vat_paper, povinné: měsíc 1 až 12.

Obálka odpovědi

  • data (záznam): Export; jeho pole popisuje seznam Pole záznamu.

Pole záznamu

  • id (UUID nebo null): Id exportu na pozadí pro GET /exports/{id}. null u malého exportu, který je hotový hned v odpovědi.
  • kind (jedna z hodnot orders, documents, products a vat_paper)
  • format (text)
  • status (jedna z hodnot ready, queued, running, failed a expired): ready = soubor je ke stažení na download_url. queued a running = vyrábí se na pozadí, ptejte se GET /exports/{id}. failed = nevznikl, důvod je v error. expired = hotový soubor už byl po 24 hodinách smazán.
  • filename (text nebo null)
  • row_count (celé číslo nebo null): Kolik řádků soubor nese, u běžícího exportu kolik už zpracoval.
  • size_bytes (celé číslo nebo null)
  • download_url (text nebo null): Podepsaný odkaz ke stažení, platí do download_expires_at (15 minut) a nechce klíč: smíte ho předat dál, třeba účetní. Adresu berte, jak přišla. Čerstvý odkaz vrátí každé GET /exports/{id}; u malého exportu nový POST /exports.
  • download_expires_at (čas ISO 8601 nebo null)
  • expires_at (čas ISO 8601 nebo null): Do kdy soubor exportu na pozadí leží (24 hodin od dokončení). U malého exportu null: soubor se při stažení vyrobí znovu z aktuálních dat.
  • error (text nebo null): Česky, proč export selhal. Jen u failed a expired.
  • created_at (čas ISO 8601 nebo null): Kdy export na pozadí vznikl. U malého exportu null.

Chyby této cesty

  • 400 invalid_body: Tělo zápisu není platný JSON nebo neodpovídá smlouvě cesty: chybí povinné pole, hodnota má špatný typ, nebo je v těle pole, které cesta nezná. Pole pointer v chybě ukazuje (JSON Pointer) na místo, které neprošlo.
  • 409 export_refused: Export nejde vyrobit: v období nejsou žádné doklady, některý doklad nejde do zvoleného formátu převést, nebo by soubor byl neúplný. Věta ve zprávě říká proč; zužte období nebo zvolte jiný formát.
  • 413 payload_too_large: Tělo zápisu je větší, než cesta přijme. Dávku rozdělte na menší požadavky.
  • 415 unsupported_media_type: Tělo zápisu musí být JSON s hlavičkou Content-Type: application/json.
  • 422 export_refused: Export nejde vyrobit: v období nejsou žádné doklady, některý doklad nejde do zvoleného formátu převést, nebo by soubor byl neúplný. Věta ve zprávě říká proč; zužte období nebo zvolte jiný formát.

GET /api/v1/exports/{id}

Stav exportu na pozadí a po dokončení podepsaný odkaz ke stažení na 15 minut. Hotový soubor leží 24 hodin.

  • Oprávnění: žádné, stačí libovolný platný klíč.
  • Odpověď: jeden záznam v data.
curl -s "https://muj-eshop.cz/api/v1/exports/$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 nebo null): Id exportu na pozadí pro GET /exports/{id}. null u malého exportu, který je hotový hned v odpovědi.
  • kind (jedna z hodnot orders, documents, products a vat_paper)
  • format (text)
  • status (jedna z hodnot ready, queued, running, failed a expired): ready = soubor je ke stažení na download_url. queued a running = vyrábí se na pozadí, ptejte se GET /exports/{id}. failed = nevznikl, důvod je v error. expired = hotový soubor už byl po 24 hodinách smazán.
  • filename (text nebo null)
  • row_count (celé číslo nebo null): Kolik řádků soubor nese, u běžícího exportu kolik už zpracoval.
  • size_bytes (celé číslo nebo null)
  • download_url (text nebo null): Podepsaný odkaz ke stažení, platí do download_expires_at (15 minut) a nechce klíč: smíte ho předat dál, třeba účetní. Adresu berte, jak přišla. Čerstvý odkaz vrátí každé GET /exports/{id}; u malého exportu nový POST /exports.
  • download_expires_at (čas ISO 8601 nebo null)
  • expires_at (čas ISO 8601 nebo null): Do kdy soubor exportu na pozadí leží (24 hodin od dokončení). U malého exportu null: soubor se při stažení vyrobí znovu z aktuálních dat.
  • error (text nebo null): Česky, proč export selhal. Jen u failed a expired.
  • created_at (čas ISO 8601 nebo null): Kdy export na pozadí vznikl. U malého exportu null.

Chyby této cesty

  • 404 not_found: Záznam s tímhle identifikátorem v obchodě není.