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: deník změn a vrácení

Referenční popis deníku změn: výpis změn zapsaných přes REST, asistenta a Agenta jen s metadaty a vrácení jedné změny, s podmínkami, chybami a ukázkou volání.

Ověřeno 16. 9. 2026Markdown verze

Pro dohled nad integrací: co se přes REST, asistenta a Agenta změnilo a vrácení konkrétní změny.

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.

GET /api/v1/changes

Deník změn: co se v obchodě změnilo přes REST, asistenta nebo Agenta, kdy, kterým klíčem a jestli je to vrácené. Jen metadata, hodnoty před a po změně ven nejdou.

  • Oprávnění: undo:write, u klíče „Vrácení změn agenta (zápis)“.
  • 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 updated_at od nejstarší změny, bez něj od nejnovějšího záznamu.
curl -s "https://muj-eshop.cz/api/v1/changes?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 +.
  • source (jedna z hodnot api, mcp, agent a system; nepovinný): Jen změny z jedné plochy, například api.
  • status (jedna z hodnot pending, applied, failed a reversed; nepovinný)

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): Id změny, jaké vrací change.id zápisu.
  • operation (jedna z hodnot create a update): Založení, nebo úprava.
  • entity_type (text): Čeho se změna týká, například order_status nebo product.
  • entity_id (UUID)
  • changed_fields (pole, položka: text)
  • status (jedna z hodnot pending, applied, failed a reversed): applied = zapsáno, reversed = vráceno, pending = rozpracované, failed = nezapsalo se.
  • source (jedna z hodnot api, mcp, agent a system, nebo null): Kudy změna přišla: api = REST API, mcp = asistent přes MCP, agent = Agent v administraci, system = platforma. null u změn před 28. 10. 2026.
  • api_key_id (UUID nebo null): Klíč, který změnu zapsal, u změn z REST a MCP.
  • reversed_at (čas ISO 8601 nebo null)
  • created_at (čas ISO 8601)
  • updated_at (čas ISO 8601)

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

POST /api/v1/changes/{id}/revert

Vrácení jedné změny z deníku, ať ji zapsal REST, asistent nebo Agent. Když položku mezitím někdo upravil, vrácení se odmítne, aby nepřepsalo novější práci.

  • Oprávnění: undo:write, u klíče „Vrácení změn agenta (zápis)“.
  • Odpověď: stav 200, zdroj v data v témže tvaru, jaký vrací čtení, a změna v deníku v change.
  • Zápis: jen klíčem s povoleným zápisem přes REST. Idempotency-Key je nepovinný; změnu vrátit nejde.
curl -s -X POST "https://muj-eshop.cz/api/v1/changes/$ID/revert" \
  -H "Authorization: Bearer $SHOPZI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

Parametry v cestě

  • id (UUID; povinný): Identifikátor záznamu (UUID) z výpisu.

Obálka odpovědi

  • data (záznam): Zdroj po zápisu, přečtený znovu; jeho pole popisuje seznam Pole záznamu.
  • change (objekt): Změna, kterou zápis vyrobil.

Pole záznamu

  • id (UUID): Id změny, jaké vrací change.id zápisu.
  • operation (jedna z hodnot create a update): Založení, nebo úprava.
  • entity_type (text): Čeho se změna týká, například order_status nebo product.
  • entity_id (UUID)
  • changed_fields (pole, položka: text)
  • status (jedna z hodnot pending, applied, failed a reversed): applied = zapsáno, reversed = vráceno, pending = rozpracované, failed = nezapsalo se.
  • source (jedna z hodnot api, mcp, agent a system, nebo null): Kudy změna přišla: api = REST API, mcp = asistent přes MCP, agent = Agent v administraci, system = platforma. null u změn před 28. 10. 2026.
  • api_key_id (UUID nebo null): Klíč, který změnu zapsal, u změn z REST a MCP.
  • reversed_at (čas ISO 8601 nebo null)
  • created_at (čas ISO 8601)
  • updated_at (čas ISO 8601)

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.
  • 400 invalid_idempotency_key: Hlavička Idempotency-Key nemá povolený tvar: 8 až 128 znaků z písmen, číslic a znaků tečka, podtržítko, dvojtečka a pomlčka.
  • 400 invalid_if_match: Hlavička If-Match nenese ETag v tvaru, v jakém ho vrací odpověď (W/ a hodnota v uvozovkách), ani hvězdičku.
  • 402 credit_cap_exceeded: Akce by překročila měsíční strop kreditů klíče, nebo ho teď nejde ověřit. Nestrhlo se nic.
  • 402 payment_declined: Uložená karta platbu odmítla. Nic se nezměnilo a nic se nestrhlo.
  • 402 plan_required: Tarif obchodu tuhle akci nezahrnuje. U katalogu dodavatelů jsou to feedy dodavatelů, které otevírá tarif Basic a vyšší (ostatní cesty feedů vracejí, co obchod už má uložené); u zápisu třeba strop počtu produktů nebo funkce, kterou tarif nemá. Opakování nepomůže, pomůže vyšší tarif.
  • 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á.
  • 403 approval_required: Akci musí schválit člověk v administraci obchodu a k tomuhle volání žádné platné schválení nepatří (schválení vypršelo, nebo ho použil jiný požadavek). Pošlete požadavek znovu s novým Idempotency-Key; vrátí 202 s novým schválením.
  • 403 forbidden: Klíč na zápis dosáhne, ale tuhle konkrétní akci obchod nepustí, třeba kvůli vypnutému modulu nebo funkci mimo tarif. Věta ve zprávě říká proč; opakování nepomůže.
  • 403 origin_not_allowed: Požadavek nese hlavičku Origin, tedy přišel z webové stránky. Klíč patří na server integrace, nikdy do prohlížeče; volejte ze serveru.
  • 403 shop_unavailable: Obchod je deaktivovaný nebo pozastavený, takže požadavky přes API ani MCP neobsluhuje. Klíč s tím nic nezmůže; otevře ho až obnovení obchodu.
  • 404 not_found: Záznam s tímhle identifikátorem v obchodě není.
  • 409 approval_pending: Na schválení akce se pořád čeká. Rizikové cesty REST to hlásí odpovědí 202 se stavem schválení, ne touhle chybou.
  • 409 confirmation_declined: Člověk akci odmítl. Dnešní zápisové cesty REST potvrzení nechtějí.
  • 409 confirmation_required: Akce by se musela napřed potvrdit. Dnešní zápisové cesty REST potvrzení nechtějí.
  • 409 conflict: Zápis odporuje stavu obchodu: stav jde jen dopředu, záznam se mezitím změnil, nebo by porušil pravidlo obchodu. Věta ve zprávě říká, co se stalo; stejné volání znovu neprojde.
  • 409 idempotency_in_progress: Zápis pod tímhle Idempotency-Key právě běží. Počkejte tolik sekund, kolik říká hlavička Retry-After, a pošlete týž požadavek znovu; dostanete jeho výsledek.
  • 409 plan_change_limited: Tarif obchodu se za posledních 24 hodin už měnil. Nestrhlo se nic.
  • 409 quote_changed: Potvrzená částka už neplatí. Nestrhlo se nic.
  • 412 precondition_failed: Zdroj se od vašeho čtení změnil: If-Match neodpovídá aktuálnímu ETagu. Přečtěte ho znovu a rozhodněte se nad aktuálním stavem.
  • 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 idempotency_key_reused: Týž Idempotency-Key už patří jinému požadavku (jiná cesta nebo jiné tělo). Na novou změnu pošlete nový klíč.
  • 422 invalid_input: Tělo je ve správném tvaru, ale hodnotu obchod nepřijme (neexistující kategorie, cena mimo rozsah, odkaz bez https). Věta ve zprávě jmenuje pole a důvod.