Zápis přes REST API
Jak přes REST API zapisovat: zapnutí zápisu u klíče, Idempotency-Key, tvar odpovědi, ETag, dávky, rizikové zápisy se schválením, vrácení změn, důsledky zápisu, stropy a chyby.
REST API umí od 29. října 2026 i zapisovat. Zápisových cest je 39 a pokrývají objednávky, zásilky a vratky, katalog a ceny, sklad, zákazníky, slevové kódy a vrácení změn. Hodí se pro ERP, skladový systém, PIM, CRM nebo pokladnu, které mají v obchodě něco měnit, ne jen číst. 10 z nich jsou rizikové (zrušení objednávky, faktura, cenová nabídka, dobropis, vrácení peněz, vyřízení reklamace) a provedou se až po schválení vlastníkem nebo manažerem obchodu v administraci, viz oddíl Rizikové zápisy se schválením.
Každý zápis přes REST provede tentýž nástroj jako asistent přes MCP a Agent v administraci: se
stejnou validací, stejnými pravidly obchodu, záznamem v deníku změn a se stejnými e-maily zákazníkům
a webhooky. REST k tomu přidává jen to, co potřebuje program: striktní tělo v JSON, hlavičku
Idempotency-Key, ETag a dávky.
Zápis je opt-in na klíčZápisové oprávnění samo nestačí. Klíč zapisuje přes REST jen tehdy, když má vlastník obchodu u klíče zaškrtnuté „Povolit zápis přes REST API“. Klíče vydané dřív, které zápisová oprávnění mají kvůli serveru MCP, tak přes REST bez rozhodnutí vlastníka nezačnou zapisovat.
Zapnutí zápisu
Klíč zapisuje přes REST, když platí obojí:
- Má zápisové oprávnění té oblasti, do které zapisuje (
orders:write,products:write,stock:write,customers:write,marketing:write,undo:write, a na doklady a vrácení penězdocuments:write). Zápisová oprávnění dřív platila jen pro server MCP; teď platí pro server MCP vždy a pro REST API, když to klíč dovolí. - Má zaškrtnuté „Povolit zápis přes REST API“.
Zaškrtávátko nastavuje vlastník obchodu v Nastavení → API a MCP, v kartě API klíče, při vytvoření klíče (Vytvořit klíč) nebo u hotového klíče ikonou Upravit klíč:
- Klíč musí platit pro REST API: v poli Kde klíč platí volba Jen REST API, nebo REST API i server MCP. Klíč jen pro server MCP zaškrtávátko nenabídne.
- Ve skupině Zápis zaškrtněte oprávnění, která integrace potřebuje. Zaškrtávátko Povolit zápis přes REST API se ukáže až s prvním zápisovým oprávněním.
- Zaškrtněte ho, uložte a krok potvrďte heslem nebo kódem z e-mailu. Všichni vlastníci obchodu dostanou e-mail a upozornění v administraci, že klíč smí zapisovat i přes REST API.
Rychlá volba v dialogu Nový API klíč nabízí sadu ERP a sklad (REST): plocha jen REST API a oprávnění ke čtení i zápisu objednávek, katalogu, skladu a zákazníků, čtení dokladů, vrácení změn a dokumentace. Zaškrtávátko zápisu přes REST ani u ní nezaškrtne nic za vás.
Když klíči úpravou odeberete poslední zápisové oprávnění, zápis přes REST se vypne sám. Plochu klíče úprava nezmění; klíč jen pro server MCP nahradíte novým.
Jak to ověřit
GET /api/v1/ping vrací v poli rest_write, jestli klíč přes REST zapisovat smí: true znamená
zaškrtnutý zápis a aspoň jedno zápisové oprávnění.
{
"ok": true,
"key_id": "9d2c1f7a-4b60-4f2e-9a11-8f0d2c3b5e64",
"scopes": ["orders:read", "orders:write", "stock:read", "stock:write"],
"rest_write": true,
"api_version": "v1"
}Klíč bez zaškrtávátka dostane na zápisové cestě 403 rest_write_not_enabled a klíč bez oprávnění
403 insufficient_scope. 403 rest_write_disabled znamená, že SHOPZI dočasně vypnulo zápisy přes
REST pro všechny obchody: čtení a webhooky běží dál a na klíči ani v obchodě se nic měnit nemusí.
Pravidla požadavku
Zápisové cesty odpovídají na POST, PUT, PATCH a DELETE. Platí pro ně:
- Tělo je JSON s hlavičkou
Content-Type: application/json, jinak přijde415 unsupported_media_type. Akce bez parametrů (DELETE, naskladnění vratky, vrácení změny) tělo mít nemusí; prázdné tělo se čte jako{}. - Tělo má nejvýš 256 KB, větší dostane
413 payload_too_large. - Tělo je striktní. Pole jsou v
snake_casepřesně podle smlouvy cesty (najdete je v referenci a v OpenAPI). Chybějící povinné pole, špatný typ i pole, které cesta nezná, vrátí400 invalid_bodyserror.pointer, tedy JSON Pointer na místo, které neprošlo. Překlep v názvu pole tak nezapadne jako „nic se nezměnilo“. - Žádná hlavička
Origin. Požadavek z webové stránky dostane403 origin_not_allowed. Klíč se zápisem patří na server integrace, nikdy do prohlížeče, kde si ho přečte kdokoli. - Identifikátor v cestě je UUID, cokoli jiného vrátí
404 not_found. - Částky jsou celá čísla v haléřích (
_minor) s DPH a sazba DPH celé procento, stejně jako ve čtení.
{
"error": {
"code": "invalid_body",
"message": "Unknown field(s) at /: quantity_chnage.",
"pointer": ""
}
}Kontroly jdou v tomhle pořadí a odpověď rozhodne první, která neprojde:
- hlavička
Origin(403 origin_not_allowed); - brány klíče jako u čtení, s dvěma navíc: hned za vypnutím plochy pro všechny obchody přijde
403 rest_write_disableda za chybějícím oprávněním403 rest_write_not_enabled; pořadí popisuje článek Autentizace a oprávnění; - strop volání (
429 rate_limited); - velikost a typ těla (
413,415, neplatný JSON jako400 invalid_body); - identifikátor v cestě (
404 not_found); - tělo proti smlouvě (
400 invalid_body); Idempotency-Key(428 idempotency_key_required,400 invalid_idempotency_key);If-Match(400 invalid_if_match,412 precondition_failed);- u rizikové cesty to, co by zápis odmítl i po schválení (vratka jiné objednávky jako
404 not_found, chybějící pole jako422 invalid_input, chybějícídocuments:writeu zrušení objednávky s fakturou jako403 forbidden), a potom schválení (202,403 approval_declined); - pravidla obchodu v samotném zápisu (
409 conflict,422 invalid_input,403 forbiddena další).
Do stropu volání se tedy počítá i zápis, který potom skončí na tělu nebo na pravidlech obchodu.
Idempotency-Key
Síť selhává, a program, který po výpadku zopakuje „naskladni 12 kusů“, nesmí naskladnit 24. Proto
zápisy berou hlavičku Idempotency-Key: hodnotu, kterou si vymyslíte pro jednu zamýšlenou změnu
a pošlete znovu, když tutéž změnu opakujete.
- Tvar je
^[A-Za-z0-9._:-]{8,128}$: 8 až 128 znaků z písmen, číslic a znaků.,_,:a-. Jiný tvar vrátí400 invalid_idempotency_key. Dobře poslouží UUID nebo klíč odvozený z vašeho dokladu, třebaprijemka-2026-1042-radek-3. - Cesty, které něco zakládají nebo hýbou zbožím, ho vyžadují a bez něj vrátí
428 idempotency_key_required:POST /api/v1/categories,POST /api/v1/credit-notes/{id}/cancel,POST /api/v1/customers,POST /api/v1/discounts,POST /api/v1/invoices,POST /api/v1/orders/{id}/cancel,POST /api/v1/orders/{id}/invoice,POST /api/v1/orders/{id}/quotation,POST /api/v1/orders/{id}/refunds,POST /api/v1/orders/{id}/reject,POST /api/v1/orders/{id}/returns,POST /api/v1/orders/{id}/shipments,POST /api/v1/products,POST /api/v1/returns/{id}/credit-note,POST /api/v1/returns/{id}/discount-credit-note,POST /api/v1/returns/{id}/reklamace-resolution,POST /api/v1/returns/{id}/restockaPOST /api/v1/stock/movements. U ostatních zápisů je nepovinný, ale doporučujeme ho posílat vždycky. - Opakování se stejným klíčem a stejným požadavkem neprovede druhý zápis. Vrátí aktuální podobu zdroje,
hlavičku
Idempotent-Replayed: truea vchange.replayedhodnotutrue. Druhý zápis ani druhý webhook nevznikne. - Stejný klíč s jinou cestou nebo jiným tělem je jiný požadavek a dostane
422 idempotency_key_reused. Na novou změnu pošlete nový klíč. - Když zápis pod tím klíčem právě běží, přijde
409 idempotency_in_progresss hlavičkouRetry-After. Počkejte a pošlete týž požadavek znovu: dostanete jeho výsledek. - Když zápis selhal a nic se nezapsalo, klíč se uvolní a opakování se stejným klíčem proběhne
normálně. Zápis, který se přerušil uprostřed a je starší než deset minut, už se stejným klíčem
zopakovat nejde (
409 conflict): zkontrolujte výsledek čtením a případnou novou změnu pošlete s novým klíčem.
Klíč idempotence patří vašemu API klíči: dva klíče téhož obchodu se stejnou hodnotou se nesrazí. Pamatuje se tak dlouho, jak dlouho deník drží záznam změny, tedy 30 dní (oddíl Jak dlouho deník změny drží níž).
Ukázka zápisu
Naskladnění dvanácti kusů z příjemky skladového systému:
curl -s -X POST https://muj-eshop.cz/api/v1/stock/movements \
-H "Authorization: Bearer $SHOPZI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: prijemka-2026-1042-radek-3" \
-d '{
"variant_id": "5f0b8a3e-2c71-4d9a-b6e4-0a1c3d5e7f92",
"type": "receipt",
"quantity_change": 12,
"notes": "Příjemka 2026/1042"
}'Odpověď 201 Created s hlavičkami X-Shopzi-Change-Id a ETag:
{
"data": {
"variant_id": "5f0b8a3e-2c71-4d9a-b6e4-0a1c3d5e7f92",
"product_id": "b1f0c0de-8f4a-4f6e-9a1c-2d3e4f5a6b70",
"sku": "NORD-L-CER",
"title": "Lněná košile Nord",
"variant": "Černá / L",
"on_hand": 16,
"available": 16,
"updated_at": "2026-10-28T09:14:02.118204Z",
"created_at": "2026-08-19T11:02:41.512000Z"
},
"change": {
"id": "3c9e5b1d-7a24-4f60-8e1b-6d2f0a4c8b17",
"operation": "movement",
"changed_fields": ["movement"],
"replayed": false,
"reversible": true
}
}Když síť spadne a požadavek pošlete znovu se stejným Idempotency-Key, přijde táž odpověď
s "replayed": true a hlavičkou Idempotent-Replayed: true; zásoba zůstane na 16.
Tvar odpovědi
Úspěšný zápis vrací 200, u založení 201, a tělo { "data": …, "change": … }:
dataje zdroj v témže tvaru, jaký vrací čtení: objednávka jakoGET /api/v1/orders/{id}, produkt jakoGET /api/v1/products/{id}, zásilka, vratka, doklad, kategorie, zákazník, slevový kód nebo stav skladu varianty jako v příslušném výpisu. Zápis do varianty vrací celý produkt. Dávky vracejí výsledek po položkách (oddíl Dávky);DELETEa storno dobropisu vracejídata: null.changepopisuje záznam v deníku změn:id(tentýž jako v hlavičceX-Shopzi-Change-Id),operation,changed_fields(pole, která zápis opravdu změnil),replayedareversible.reversiblejefalseu cest, které vrátit nejde, a u zápisu, který nic nezměnil.
Ve vzácném případě, kdy se zápis provede, ale zdroj se hned potom nedá přečíst (mezitím ho někdo
smazal), přijde 404 not_found a hlavička X-Shopzi-Change-Id nese id změny, která se zapsala.
Odmítnutí nástroje nese v message českou větu, kterou můžete ukázat obchodníkovi; rozhodujte se
ale podle code.
ETag a If-Match
Detail zdroje (GET /api/v1/orders/{id}, /api/v1/products/{id}, /api/v1/customers/{id},
/api/v1/discounts/{id}, /api/v1/returns/{id}, /api/v1/documents/{id}) i každý zápis, který
vrací zdroj, nesou hlavičku ETag ve tvaru W/"…": slabý otisk (SHA-256) zdroje tak, jak ho
odpověď vrací.
Pošlete-li ho u zápisu v hlavičce If-Match, zápis proběhne jen tehdy, když zdroj pořád vypadá tak,
jak jste ho četli; jinak přijde 412 precondition_failed a nic se nezmění. If-Match: * znamená
„cokoli, co existuje“. Hodnota v jiném tvaru vrátí 400 invalid_if_match. U založení se If-Match
nepoužije; zásilka a vratka, které se zakládají k objednávce, porovnávají ETag objednávky.
If-Match je best effortPorovnání a zápis nedělí zámek. Podmínka vás ochrání před rozhodnutím nad zastaralým stavem (ERP přecení produkt, který obchodník mezitím upravil), ne před dvěma zápisy v téže milisekundě. Ty hlídají pravidla zápisu a deník změn.
Dávky
Dvě cesty zapisují až 100 položek jedním požadavkem:
PUT /api/v1/prices/batch a POST /api/v1/stock/levels/batch. Každá varianta smí být v dávce jen jednou.
PUT /api/v1/prices/batchpřecení varianty, každou vlastní cenou. Platí celá dávka, nebo nic. Zapíše se jeden záznam v deníku, za každý dotčený produkt přijde jedna událostproduct.updateda celou dávku vrátí jedno vrácení změny. Každá změna ceny se zapíše do 30denní historie cen podle § 12a zákona o ochraně spotřebitele, stejně jako přecenění v administraci.POST /api/v1/stock/levels/batchnastaví stav skladu variant na čísla, jak je hlásí váš sklad, a vrátí výsledek po položkách:applied(zapsala se korekce),unchanged(stav už seděl),refused(varianta by šla do záporu) anot_found(varianta v obchodě není). Probíhá v jedné transakci a do deníku se zapíše jedním záznamem, takže se i vrací jedním krokem.
Dávka se do stropu volání počítá jako jeden zápis, ať nese jednu položku, nebo sto. Sto jednotlivých volání by spotřebovalo sto zápisů a sto záznamů v deníku.
Vrácení změny a deník změn
GET /api/v1/changes vypisuje deník změn obchodu: co se změnilo přes REST, asistenta přes MCP
nebo Agenta, kdy, kterým klíčem (api_key_id), odkud (source: api, mcp, agent, system)
a jestli je změna vrácená. Jsou to jen metadata; hodnoty před změnou a po ní REST nevydává.
Výpis se stránkuje a synchronizuje jako ostatní, filtrovat jde podle source a status.
POST /api/v1/changes/{id}/revert vrátí jednu změnu, ať ji zapsal REST, asistent nebo Agent. Chce
oprávnění undo:write a zápisové oprávnění oblasti, které se změna týká (vrácení ceny chce
i products:write). Když položku od té změny někdo upravil, vrácení se odmítne, aby nepřepsalo
novější práci. Sklad se nevrací přepsáním čísla, ale vyrovnávacím pohybem, takže historie pohybů
dál sedí. Druhé vrácení téže změny nic neudělá.
Vrátit nejde tyhle zápisy: POST /api/v1/credit-notes/{id}/cancel, POST /api/v1/customers, POST /api/v1/invoices, POST /api/v1/orders/{id}/cancel, POST /api/v1/orders/{id}/invoice, POST /api/v1/orders/{id}/payment-status, POST /api/v1/orders/{id}/quotation, POST /api/v1/orders/{id}/refunds, POST /api/v1/orders/{id}/reject, POST /api/v1/orders/{id}/returns, POST /api/v1/orders/{id}/shipments, POST /api/v1/orders/{id}/status, POST /api/v1/returns/{id}/approval, POST /api/v1/returns/{id}/credit-note, POST /api/v1/returns/{id}/discount-credit-note, POST /api/v1/returns/{id}/reklamace-resolution, POST /api/v1/returns/{id}/restock, POST /api/v1/returns/{id}/status, POST /api/v1/shipments/{id}/status a PUT /api/v1/shipments/{id}/tracking. Každý z nich
má důsledek, který vrácení řádku v deníku nevezme zpět:
- Stav objednávky a stav platby posílají zákazníkovi e-mail a zaplacení může vystavit fakturu s číslem z řady dokladů. Peníze se vracejí dobropisem a refundací k vratce, obojí jen po schválení (oddíl Rizikové zápisy se schválením).
- Zásilky (založení, stav i sledování) žijí zároveň u dopravce: svoz se skutečně objedná, předání pošle zákazníkovi e-mail a zrušení jde i k dopravci. Vrácení řádku v obchodě by to nevzalo zpět.
- Vratky a reklamace dostávají číslo z řady, u reklamace běží zákonná lhůta a naskladnění vratky je skutečný skladový pohyb. Chybu opraví další zápis, ne vrácení.
- Založení zákazníka se nevrací: účet se ruší výmazem podle GDPR, který schvaluje člověk.
Co zápis spustí
Zápis přes REST má tytéž důsledky jako totéž v administraci:
| Cesta | Co se stane navíc |
|---|---|
POST /api/v1/orders/{id}/status | Zákazník dostane e-mail o stavu jako z administrace. S "notify_customer": false se stav zapíše bez e-mailu (dosynchronizování historie). Stav jde jen dopředu; zrušení a zamítnutí jsou vlastní cesty se schválením. |
POST /api/v1/orders/{id}/payment-status | paid pošle zákazníkovi potvrzení platby, zapíše tržbu a podle nastavení obchodu vystaví fakturu. Nechce žádné schválení. refunded a partially_refunded tahle cesta odmítne odpovědí 403 approval_required: peníze se vracejí cestou POST /api/v1/orders/{id}/refunds. |
POST /api/v1/orders/{id}/shipments | Bez pole external objedná u dopravce s napojením skutečný svoz. S external (tracking_number, tracking_url) jen zapíše zásilku, kterou jste podali sami, a dopravci nic neposílá. |
POST /api/v1/shipments/{id}/status | Předání dopravci pošle zákazníkovi e-mail, doručení dobírky označí platbu a vystaví doklad, zrušení zruší zásilku i u dopravce. |
POST /api/v1/orders/{id}/returns | Vratka dostane číslo z řady, u reklamace se rozběhne zákonná lhůta. |
POST /api/v1/returns/{id}/restock | Zapíše skladový pohyb za schválené kusy. |
PUT /api/v1/variants/{id}/price a PUT /api/v1/prices/batch | Cena se zapíše do 30denní historie cen podle § 12a. |
POST /api/v1/orders/{id}/cancel | Po schválení: zrušení tímtéž řetězcem jako v administraci. Zastaví zásilky u dopravce a k vystavené faktuře vystaví storno dobropis (to chce i documents:write). Zákazník dostane e-mail. |
POST /api/v1/orders/{id}/reject | Po schválení: zamítnutí objednávky, zákazník dostane e-mail. Dobropis nevzniká. |
POST /api/v1/orders/{id}/invoice, POST /api/v1/invoices | Po schválení: faktura s číslem z bezmezerové řady, s "send_email": true hned e-mailem zákazníkovi. |
POST /api/v1/orders/{id}/quotation | Po schválení: cenová nabídka s číslem z řady k naceněné poptávce. Zákazníkovi se sama neposílá. |
POST /api/v1/returns/{id}/credit-note, POST /api/v1/returns/{id}/discount-credit-note | Po schválení: dobropis s číslem z řady. Peníze se tím nevracejí. |
POST /api/v1/credit-notes/{id}/cancel | Po schválení: storno dobropisu, jeho číslo zůstane v řadě jako stornované. Jen dokud se proti vratce nehnuly peníze. |
POST /api/v1/orders/{id}/refunds | Po schválení: gateway vrátí peníze přes platební bránu, manual zapíše peníze vrácené převodem nebo hotově, shipping nastaví vrácení za dopravu. Zákazník dostane e-mail o vrácení peněz. |
POST /api/v1/returns/{id}/reklamace-resolution | Po schválení: vyřízení reklamace podle § 2169 OZ s příznakem zákonné lhůty. Zákazník dostane zprávu. |
Webhooky vznikají stejně jako u změny v administraci; které událost která cesta vypouští, uvádí
reference a OpenAPI. Opakování se stejným Idempotency-Key žádnou událost nepošle.
Zápis přes REST API nestojí kredity: žádná zápisová cesta nespouští AI a měsíční strop kreditů klíče se REST API netýká.
Zápisové cesty
| Cesta | Oprávnění | Idempotency-Key | Jde vrátit | Schválení |
|---|---|---|---|---|
POST /api/v1/orders/{id}/status | orders:write | nepovinný | ne | ne |
POST /api/v1/orders/{id}/payment-status | orders:write | nepovinný | ne | ne |
POST /api/v1/orders/{id}/shipments | orders:write | povinný | ne | ne |
PUT /api/v1/orders/{id}/charges | orders:write | nepovinný | ano | ne |
POST /api/v1/orders/{id}/returns | orders:write | povinný | ne | ne |
POST /api/v1/shipments/{id}/status | orders:write | nepovinný | ne | ne |
PUT /api/v1/shipments/{id}/tracking | orders:write | nepovinný | ne | ne |
POST /api/v1/returns/{id}/status | orders:write | nepovinný | ne | ne |
POST /api/v1/returns/{id}/approval | orders:write | nepovinný | ne | ne |
POST /api/v1/returns/{id}/restock | orders:write | povinný | ne | ne |
POST /api/v1/documents/{id}/paid | orders:write | nepovinný | ano | ne |
POST /api/v1/products | products:write | povinný | ano | ne |
PATCH /api/v1/products/{id} | products:write | nepovinný | ano | ne |
PUT /api/v1/products/{id}/categories | products:write | nepovinný | ano | ne |
PATCH /api/v1/variants/{id} | products:write | nepovinný | ano | ne |
PUT /api/v1/variants/{id}/price | products:write | nepovinný | ano | ne |
PUT /api/v1/prices/batch | products:write | nepovinný | ano | ne |
POST /api/v1/categories | products:write | povinný | ano | ne |
PATCH /api/v1/categories/{id} | products:write | nepovinný | ano | ne |
POST /api/v1/stock/movements | stock:write | povinný | ano | ne |
PUT /api/v1/stock/{variant_id} | stock:write | nepovinný | ano | ne |
POST /api/v1/stock/levels/batch | stock:write | nepovinný | ano | ne |
POST /api/v1/customers | customers:write | povinný | ne | ne |
PATCH /api/v1/customers/{id} | customers:write | nepovinný | ano | ne |
PUT /api/v1/customers/{id}/tags | customers:write | nepovinný | ano | ne |
POST /api/v1/discounts | marketing:write | povinný | ano | ne |
PATCH /api/v1/discounts/{id} | marketing:write | nepovinný | ano | ne |
DELETE /api/v1/discounts/{id} | marketing:write | nepovinný | ano | ne |
POST /api/v1/changes/{id}/revert | undo:write | nepovinný | ne | ne |
POST /api/v1/orders/{id}/cancel | orders:write | povinný | ne | ano |
POST /api/v1/orders/{id}/reject | orders:write | povinný | ne | ano |
POST /api/v1/orders/{id}/refunds | documents:write | povinný | ne | ano |
POST /api/v1/orders/{id}/invoice | documents:write | povinný | ne | ano |
POST /api/v1/orders/{id}/quotation | documents:write | povinný | ne | ano |
POST /api/v1/invoices | documents:write | povinný | ne | ano |
POST /api/v1/returns/{id}/credit-note | documents:write | povinný | ne | ano |
POST /api/v1/returns/{id}/discount-credit-note | documents:write | povinný | ne | ano |
POST /api/v1/credit-notes/{id}/cancel | documents:write | povinný | ne | ano |
POST /api/v1/returns/{id}/reklamace-resolution | documents:write | povinný | ne | ano |
Několik pravidel, na která integrace narazí nejčastěji:
PATCH /api/v1/products/{id}mění texty, stav, značku a SEO;status: archivedstáhne produkt z prodeje a data zůstanou. Adresu produktu (URL) REST nemění a cenu mění cesta varianty.PUT /api/v1/stock/{variant_id}nastaví celkový stav varianty přes sklady. Rozdíl se spočítá pod zámkem a zapíše jako korekce na výchozím skladu, takže kniha pohybů dál sedí.PATCH /api/v1/customers/{id}mění jméno, telefon, firmu, IČO a DIČ. E-mail ne: je to přihlašovací údaj zákazníka. Vystavené doklady si nesou údaje z okamžiku vystavení.DELETE /api/v1/discounts/{id}smaže jen kód, který nikdo neuplatnil. Uplatněný kód archivujte (PATCHsestatus: archived): záznamy o použití jsou účetní podklad.- Kategorie se zakládají nejvýš do třetí úrovně stromu; adresu a místo kategorie ve stromu REST nemění.
Pole těla, jejich typy a chyby každé cesty vypisuje reference generovaná ze smlouvy (například REST API: objednávky, vratky a zásilky) a strojově OpenAPI popis REST API.
Rizikové zápisy se schválením
Zrušení a zamítnutí objednávky, faktura k objednávce i samostatná, cenová nabídka, dobropis a jeho
storno, vrácení peněz a vyřízení reklamace jsou nevratné: doklad je neměnný a jeho číslo z řady se
znovu nepoužije, peníze jsou u zákazníka a e-mail mu nikdo nevezme zpátky. Proto je každou z těch
cest (POST /api/v1/credit-notes/{id}/cancel, POST /api/v1/invoices, POST /api/v1/orders/{id}/cancel, POST /api/v1/orders/{id}/invoice, POST /api/v1/orders/{id}/quotation, POST /api/v1/orders/{id}/refunds, POST /api/v1/orders/{id}/reject, POST /api/v1/returns/{id}/credit-note, POST /api/v1/returns/{id}/discount-credit-note a POST /api/v1/returns/{id}/reklamace-resolution) potřeba napřed schválit v administraci obchodu,
stejně jako tytéž akce přes asistenta MCP.
-
Pošlete požadavek s hlavičkou
Idempotency-Key(u rizikových cest je povinná). Odpověď je202 Accepted, nic se neprovede a tělo nese schválení:{ "approval": { "id": "8c1e4f2a-3b5d-4c6e-9f70-1a2b3c4d5e6f", "status": "pending", "approval_url": "https://muj-eshop.cz/administrace/schvaleni/8c1e4f2a-3b5d-4c6e-9f70-1a2b3c4d5e6f", "expires_at": "2026-10-28T10:15:00.000000Z" } }Hlavička
Locationvede naGET /api/v1/approvals/{id}aRetry-Afterříká, za kolik sekund se zeptat znovu. Vlastníci a manažeři obchodu dostanou upozornění v administraci. -
Odkaz
approval_urlotevře vlastník nebo manažer přihlášený do administrace a změnu schválí, nebo zamítne. Editor, účetní ani účet podpory SHOPZI schválit nemůžou. Odkaz nenese žádné přihlášení, takže ho klidně pošlete e-mailem. -
Stav sledujte přes
GET /api/v1/approvals/{id}(pending,approved,consumed,declined,expired), nebo počkejte na webhookapproval.decided. Stav schválení vidí jen klíč, který o něj požádal; jinému klíči vrátí404 not_found. -
Po schválení pošlete týž požadavek se stejným
Idempotency-Key. Zápis proběhne právě jednou a odpověď je jako u každého jiného zápisu (200, u vystavení dokladu201, sdataachange). Doklad přijde v témže tvaru jako řádekGET /api/v1/documents, i s číslem z řady.
Co dál platí:
- Opakování po zápisu vrátí týž výsledek. Když se vám ztratí odpověď, pošlete týž požadavek
znovu: dostanete tentýž doklad s týmž číslem,
Idempotent-Replayed: trueachange.replayed: true. Druhý doklad ani druhá refundace nevznikne. - Schválení patří k jednomu
Idempotency-Key. Dvě refundace po sto korunách k téže vratce jsou dvě změny, každá s vlastním klíčem a vlastním schválením. Nový klíč se stejným tělem tedy založí nové schválení, neprovede to staré. - Zamítnuté schválení vrátí na týž požadavek
403 approval_declineda nic se neprovede. Kdo změnu pořád chce, pošle nový požadavek s novým klíčem. - Schválení platí hodinu. Nerozhodnuté, nebo schválené a nepoužité schválení po hodině vyprší
a týž požadavek založí nové (
202). - Na jeden klíč čeká nejvýš dvacet schválení naráz a za hodinu jich vznikne nejvýš třicet; nad to
přijde
409 conflicta nic nevznikne. - Co by zápis odmítl i po schválení, se odmítne dřív, aby vlastník neschvaloval změnu, která
stejně neprojde: vratka jiné objednávky (
404), ruční refundace bezmethod(422), zrušení objednávky s fakturou klíčem bezdocuments:write(403 forbidden, storno dobropis je doklad). - Rizikové zápisy se nevracejí přes
POST /changes/{id}/revert. Fakturu opraví dobropis, dobropis jeho storno, oboje zase se schválením.
Co přes REST nejde
Rozeslání kampaně, smazání přesměrování a vyřízení nedodatelné části objednávky u dodavatele umí jen asistent přes MCP (po schválení v prohlížeči) a administrace. Feedy dodavatelů se přes REST jen čtou a zapisují se přes server MCP nebo v administraci, viz REST API: feedy dodavatelů.
Export objednávek, balíčku dokladů pro účetní, katalogu a podkladu k DPH do souboru zápisem není:
POST /api/v1/exports je čtení a chce jen čtecí oprávnění té oblasti, viz
Endpointy REST API.
Stropy
Zápis je i volání REST API, takže se počítá do obou stropů: do stropu volání (článek Chybové odpovědi, oddíl Objem požadavků) a navíc do stropu zápisů. Oba se počítají na klíč podle tarifu obchodu, v pevném minutovém okně a za kalendářní den v českém čase, a rozhoduje ten, který dojde dřív:
| Tarif | Zápisů za minutu | Zápisů za den |
|---|---|---|
| Basic | 30 | 5 000 |
| Standard | 60 | 15 000 |
| Business | 120 | 40 000 |
| Enterprise a jednorázová licence | 150 | 80 000 |
Nad strop přijde 429 rate_limited s hlavičkou Retry-After; hlavičky X-RateLimit-* popisují
okno, které je právě těsnější. Dávka je jeden zápis. Ochranná vrstva sítě navíc pustí z jedné IP
adresy zhruba 60 zápisů za minutu, a to ještě před aplikací; takové odmítnutí nemá tvar chyby API.
Tisíce změn proto posílejte dávkami, ne jednotlivě.
Chyby
Všechny kódy zápisu i to, co s nimi dělat, vypisuje tabulka v článku Chybové odpovědi. Nejčastěji:
400 invalid_body: tělo neprošlo smlouvou,error.pointerukazuje kam;409 conflict: zápis odporuje stavu obchodu (stav jde jen dopředu, nebo by zápis porušil pravidlo obchodu); stejné volání znovu neprojde;422 invalid_input: hodnotu obchod nepřijme (neexistující kategorie, odkaz bezhttps);412 precondition_failed: zdroj se od vašeho čtení změnil;403 approval_declined: rizikový zápis vlastník nebo manažer zamítl (oddíl Rizikové zápisy se schválením);428 idempotency_key_required,422 idempotency_key_reused,409 idempotency_in_progress: oddíl Idempotency-Key výš.
Jak dlouho deník změny drží
Deník změn drží zápisy přes REST API 30 dní, změny asistenta přes MCP a Agenta 365 dní. Starší
záznamy maže pravidelný úklid po dávkách. Potom změna z GET /api/v1/changes zmizí, vrátit ji už
nejde a zapomene se i její Idempotency-Key. Integrace, která potřebuje delší historii, si ji
vede u sebe.
Když obchodník vymaže zákazníka podle GDPR, smažou se i snímky jeho karty v deníku změn (jméno, telefon, firma). Úprava takového zákazníka pak vrátit nejde, protože není co vrátit.