# 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í. - Sekce: Pro vývojáře - Stránka: https://shopzi.cz/dokumentace/vyvojari/rest-denik-zmen - Ověřeno: 2026-09-16 --- 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](/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/changes` [#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. ```bash 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` [#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. ```bash 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.