# MCP: objednávky, vratky a doklady > Nástroje MCP pro objednávky, zásilky, vratky, párování plateb a vystavené doklady: oprávnění, potvrzení, důsledky zápisu a všechny parametry. - Sekce: Pro vývojáře - Stránka: https://shopzi.cz/dokumentace/vyvojari/mcp-objednavky - Ověřeno: 2026-09-16 --- Hledání a detail objednávek, fronta párování plateb, vratky a reklamace i s detailem jedné vratky a vystavené doklady, a k tomu nástroj, který u existující objednávky mění stav, platbu, zásilky a vratky (včetně schválení uznaných množství), páruje platby z výpisu a znovu posílá vystavenou fakturu. Nástroje volá klient přes server MCP na doméně obchodu, například `https://muj-eshop.cz/api/mcp`, a v odpovědi na `tools/list` dostane jen ty, na jejichž oprávnění klíč dosáhne. Jak server mluví, kdy se ptá člověka a jak se změny vracejí, popisuje článek [MCP server](/dokumentace/vyvojari/mcp-server). U každého nástroje stojí oprávnění, které chce, jestli se server před provedením zeptá člověka a kudy, jestli volání strhne kredity obchodu nebo peníze z karty, co vrací pro deník změn a jakou větu o důsledku člověk v potvrzení uvidí. Všechno z toho se vyhodnocuje z téhož kódu, podle kterého se server rozhoduje. Popisy parametrů jsou převzaté ze schématu, které server posílá v `tools/list`; kde se v něm text obrací přímo k modelu, je tady převedený do vykání. Povinnost parametru platí uvnitř objektu, ve kterém parametr leží. Před zápisem, který přepisuje nebo maže, před útratou kreditů nebo platbou kartou a před hledáním mimo obchod se server ptá člověka a do té doby neprovede nic. Nejdřív použije schválení, které pro totéž volání se stejnými hodnotami už v administraci leží schválené. Jinak se zeptá formulářem, když ho klient deklaruje a politika akce ho dovoluje; formulář potvrzuje ten, kdo drží klíč, takže před ukradeným klíčem takové potvrzení nechrání. Otázka ve formuláři nese pod nadpisem „Co se změní“ tytéž řádky jako stránka schválení. Klient s elicitací URL dostane odkaz na stránku schválení v administraci a klient bez elicitace odmítnutí `approval_required` s odkazem v `_meta`; po schválení volání zopakuje se stejnými hodnotami. Na stránce schválení rozhoduje jen přihlášený člověk, kterého u každé akce jmenuje odrážka Potvrzení přes MCP, a účet podpory SHOPZI nikdy. Když politika nedovoluje nic, co klient umí, přijde odmítnutí `confirmation_required` a neprovede se nic. Výsledek potvrzeného volání nese v `_meta["cz.shopzi/confirmation"]` údaj, že akci potvrdil člověk a kde (`form` nebo `approval`), a v obsahu českou větu pro model, u placené akce i s cenou a zůstatkem kreditů z dotazu. Na otázku formulářem je 15 minut, schválení na stránce platí 60 minut, pokud u akce není uvedeno jinak. Zápisové nástroje vracejí v poli `change_id` ID záznamu v deníku změn; co pole u kterého nástroje nese, říká jeho odrážka Deník změn. Změnu z deníku vrací `shopzi_undo_change` podle jejího druhu: obnoví předchozí hodnoty, u skladu zapíše vyrovnávací pohyb, u běžné ceny zapíše návrat do 30denní historie cen (nic z ní nemaže) a změnu, která už opustila obchod nebo stála peníze (odeslaný e-mail, stržené kredity, platbu kartou), odmítne s vysvětlením. ## `shopzi_search_orders` [#shopzi-search-orders] V režimu `search` vrátí stránku objednávek se stejnými filtry jako obrazovka Objednávky, v režimu `labels` objednávky čekající na předání Zásilkovně s odkazem na jedno PDF se všemi štítky a v režimu `payment_queue` frontu párování plateb (nespárované platby z bankovního výpisu a dobírky), ze které platbu potvrdí nebo odsune `shopzi_manage_order`. Tržby za období počítá `shopzi_get_analytics`, součet řádků výpisu je nenahradí. * **Oprávnění:** `orders:read`, u klíče „Objednávky (čtení)“. * **Druh:** čtení (`readOnlyHint`). * **Potvrzení přes MCP:** ne. * **Kredity a platba kartou:** ne. ## `shopzi_search_orders`: parametry [#shopzi-search-orders-parametry] * `mode` (jedna z hodnot `search`, `labels` a `payment_queue`, výchozí `search`; nepovinný): `search` = stránka objednávek podle filtrů. `labels` = fronta štítků Zásilkovny. `payment_queue` = fronta párování plateb; bere jen `limit`. * `status` (jedna z hodnot `pending`, `received`, `confirmed`, `processing`, `shipped`, `delivered`, `completed`, `cancelled` a `rejected`; nepovinný): Stav objednávky, například `pending` nebo `completed`. * `paymentStatus` (jedna z hodnot `pending`, `authorized`, `paid`, `failed`, `refunded` a `partially_refunded`; nepovinný): Stav platby, například `paid` nebo `pending`. * `updatedSince` (text se vzorem; nepovinný): ISO datum. Jen objednávky změněné od té doby. * `search` (text; nepovinný): Podřetězec ČÍSLA OBJEDNÁVKY, e-mailu nebo jména na faktuře. Použijte, když obchodník zmíní číslo objednávky nebo zákazníka (`shopzi_get_order` bere jen vnitřní ID). Obecná slova z věty („web“, „administrace“, „objednávky“) sem nedávejte, nic nenajdou. * `placedFrom` (text; nepovinný): Objednané OD, včetně, jako pražský kalendářní den `RRRR-MM-DD`. Používejte ho na otázky typu „za červenec“ nebo „za posledních 30 dní“; `updatedSince` je datum poslední ZMĚNY objednávky, což je jiná otázka. * `placedTo` (text; nepovinný): Objednané DO, včetně celého toho dne, `RRRR-MM-DD`. * `orderType` (jedna z hodnot `orders` a `quotations`; nepovinný): `orders` = jen objednávky, `quotations` = jen velkoobchodní poptávky. Vynechané = obojí dohromady. * `fulfillment` (`returned`; nepovinný): `returned` = jen objednávky, jejichž zásilka se vrátila nebo se nepodařilo doručit. * `limit` (celé číslo od 1 do 100, výchozí `25`; nepovinný): Počet položek na stránku, 1 až 100. Velká stránka se do jedné odpovědi nemusí vejít a nástroj ji pak odmítne, což stojí krok navíc: berte jen tolik položek, kolik na odpověď opravdu potřebujete. * `cursor` (text; nepovinný): Průběžná pozice z předchozí odpovědi (`next_cursor`). Vynechte pro první stránku. ## `shopzi_get_order` [#shopzi-get-order] Vrátí jednu objednávku i s položkami a s tím, co ukazuje její detail v administraci: zásilky, platby, příplatky, vystavené doklady včetně dobropisů, historii stavů a interní poznámky (ty jen v panelu Agenta v administraci). Nákupní ceny neobsahuje. Každá částka objednávky i položky přijde v haléřích i jako hotový text pod jménem bez `_minor`, třeba `total` vedle `total_minor`. * **Oprávnění:** `orders:read`, u klíče „Objednávky (čtení)“. * **Druh:** čtení (`readOnlyHint`). * **Potvrzení přes MCP:** ne. * **Kredity a platba kartou:** ne. ## `shopzi_get_order`: parametry [#shopzi-get-order-parametry] * `orderId` (UUID; povinný): ID objednávky (UUID) ze `shopzi_search_orders`. VYMYŠLENÉ id nástroj odmítne. ## `shopzi_list_returns` [#shopzi-list-returns] Vrátí vratky a reklamace od nejnovějších i se zákonnou lhůtou na vyřízení a s částkami v haléřích, u každé i jako hotový text. S `returnId` vrátí detail jedné vratky i s ID položek, které potřebuje schválení a naskladnění v `shopzi_manage_order`. * **Oprávnění:** `orders:read`, u klíče „Objednávky (čtení)“. * **Druh:** čtení (`readOnlyHint`). * **Potvrzení přes MCP:** ne. * **Kredity a platba kartou:** ne. ## `shopzi_list_returns`: parametry [#shopzi-list-returns-parametry] * `status` (jedna z hodnot `requested`, `received`, `approved`, `partially_approved`, `rejected`, `refunded`, `closed` a `cancelled`; nepovinný): Filtr stavu, například `requested` nebo `received`. * `search` (text; nepovinný): Hledá podle čísla vratky, čísla objednávky nebo e-mailu. * `returnId` (UUID; nepovinný): ID vratky z výpisu: vrátí její detail, filtry se nepoužijí. * `limit` (celé číslo od 1 do 100, výchozí `25`; nepovinný): Počet položek na stránku, 1 až 100. Velká stránka se do jedné odpovědi nemusí vejít a nástroj ji pak odmítne, což stojí krok navíc: berte jen tolik položek, kolik na odpověď opravdu potřebujete. * `offset` (celé číslo od 0 do 100000, výchozí `0`; nepovinný): Kolik položek přeskočit. 0 = první stránka. ## `shopzi_list_documents` [#shopzi-list-documents] V režimu `list` vrátí vystavené doklady se stejnými filtry jako obrazovka Fakturace (typ, číslo nebo odběratel, zaplacenost, období vystavení), v režimu `detail` jeden doklad celý: položky, rekapitulaci DPH po sazbách, odběratele a odkazy ke stažení PDF a ISDOC. Vystavenou fakturu znovu pošle e-mailem nebo zaplacenost faktury bez objednávky přepne `shopzi_manage_order`. * **Oprávnění:** `documents:read`, u klíče „Doklady: metadata, položky a stažení PDF/ISDOC (čtení)“. * **Druh:** čtení (`readOnlyHint`). * **Potvrzení přes MCP:** ne. * **Kredity a platba kartou:** ne. ## `shopzi_list_documents`: parametry [#shopzi-list-documents-parametry] * `mode` (jedna z hodnot `list` a `detail`, výchozí `list`; nepovinný): `list` = stránka metadat. `detail` = jeden doklad celý, vyžaduje `documentId`. * `documentId` (UUID; nepovinný): ID dokladu z `mode: "list"`. Povinné pro `mode: "detail"`. * `docType` (jedna z hodnot `order`, `invoice`, `credit_note`, `proforma`, `pos_receipt` a `quotation`; nepovinný): Filtr typu, například `invoice` nebo `credit_note`. * `search` (text; nepovinný): Hledá podle ČÍSLA DOKLADU, čísla objednávky nebo odběratele. Použijte ho vždy, když obchodník nebo účetní zmíní číslo faktury: `mode: "detail"` bere jen vnitřní identifikátor, který v obchodě nikde nevidí. * `paid` (jedna z hodnot `paid` a `unpaid`; nepovinný): `unpaid` = doklady, které nikdo nezaplatil, `paid` = zaplacené. Dobropisy z výsledku vypadnou, ty se neplatí. * `issuedFrom` (text; nepovinný): Vystavené OD, včetně, jako pražský kalendářní den `RRRR-MM-DD`. Na otázky typu „doklady za srpen“ nebo „kolik jsem letos vyfakturoval“. * `issuedTo` (text; nepovinný): Vystavené DO, včetně celého toho dne, `RRRR-MM-DD`. * `limit` (celé číslo od 1 do 100, výchozí `25`; nepovinný): Počet položek na stránku, 1 až 100. Velká stránka se do jedné odpovědi nemusí vejít a nástroj ji pak odmítne, což stojí krok navíc: berte jen tolik položek, kolik na odpověď opravdu potřebujete. * `cursor` (text; nepovinný): Průběžná pozice z předchozí odpovědi (`next_cursor`). Vynechte pro první stránku. ## `shopzi_manage_order` [#shopzi-manage-order] Mění existující objednávku: stav, platbu, cenu dopravy a příplatky, nacenění poptávky, zásilky u dopravce, vratky včetně schválení uznaných množství a párování plateb z bankovního výpisu. Vystavenou fakturu objednávky pošle zákazníkovi znovu e-mailem a fakturu bez objednávky označí za zaplacenou nebo nezaplacenou. Některé operace posílají zákazníkovi e-mail, objednávají skutečnou zásilku nebo vedou k vystavení faktury; které, říká věta o důsledku u operací v seznamu níž. * **Oprávnění:** `orders:write`, u klíče „Objednávky: stav, platba, zásilky, vratky a faktury (zápis)“. * **Druh:** zápis, který umí přepsat nebo smazat existující data (`destructiveHint`). * **Potvrzení přes MCP:** ano: formulář v klientu, který potvrdí ten, kdo drží klíč; jinak odkaz na stránku schválení přes elicitaci URL; jinak odkaz na stránku schválení v odmítnutí `approval_required`. Na stránce schválení rozhoduje vlastník nebo manažer obchodu. * **Kredity a platba kartou:** ne. * **Deník změn:** výsledek nese `change_id`. ID záznamu v deníku. Předejte ho do `shopzi_undo_change`. * **Věta o důsledku, kterou člověk uvidí v potvrzení:** podle `operation`, viz seznam níž. ### `shopzi_manage_order`: operace [#shopzi-manage-order-operace] * `set_status` (změnit stav objednávky) * Věta o důsledku v potvrzení: > Změna stavu objednávky ODEŠLE zákazníkovi e-mail a vzít se zpátky nedá. * `set_payment_status` (změnit stav platby) * Věta o důsledku v potvrzení: > Označení platby ODEŠLE zákazníkovi e-mail a vzít se zpátky nedá. Zaplacená objednávka se zapíše do tržeb a zboží na zakázku odejde do výroby. U objednávky placené kartou nebo na dobírku se navíc vystaví faktura. * `set_billing_extras` (upravit dopravu a příplatky) * `set_quotation_prices` (nacenit poptávku) * `create_shipment` (založit zásilku) * Věta o důsledku v potvrzení: > U dopravce s napojením (Zásilkovna, PPL, GLS) se OBJEDNÁ SKUTEČNÁ zásilka se štítkem a sledovacím číslem; u osobního odběru a vlastního rozvozu se nikam nevolá. * `set_shipment_status` (změnit stav zásilky) * Věta o důsledku v potvrzení: > Změna stavu zásilky ODEŠLE zákazníkovi e-mail, posune i stav objednávky a vzít se zpátky nedá. Doručení na dobírku navíc označí platbu za přijatou a vystaví doklad; zrušení zruší zásilku i u dopravce. * `track_shipment` (zjistit stav u dopravce) * Věta o důsledku v potvrzení: > Zeptá se dopravce na stav zásilky. Když se tím stav pohne, zákazník dostane e-mail stejně jako při ruční změně. * `create_return` (založit vratku) * Věta o důsledku v potvrzení: > Vratka dostane číslo z řady a vzít se zpátky nedá; u reklamace od jejího vzniku běží zákonná třicetidenní lhůta. * `set_return_status` (změnit stav vratky) * Věta o důsledku v potvrzení: > Stav vratky jde jen dopředu, takže se tahle změna nevrací. * `restock_return` (vrátit zboží z vratky na sklad) * Věta o důsledku v potvrzení: > Naskladnění z vratky zapíše skutečný skladový pohyb a označí položky za vyřízené, takže se nevrací; chybu opravíte odpisem ve Skladu. * `create_return_shipment` (vygenerovat zpětnou zásilku) * Věta o důsledku v potvrzení: > Zpětná zásilka vznikne u Zásilkovny doopravdy a ta o ní zákazníkovi SAMA pošle e-mail s heslem k podání. * `approve_return` (schválit množství vratky) * Věta o důsledku v potvrzení: > Schválení určí, kolik kusů a za kolik se z vratky uznává; z té částky pak člověk vystaví dobropis. Peníze ani doklad se tím nepohnou, ale samo se nevrací: jiná množství zapíšete novým schválením, dokud dobropis neexistuje. * `resend_invoice` (znovu poslat fakturu e-mailem) * Věta o důsledku v potvrzení: > Zákazníkovi ODEJDE e-mail s už vystavenou fakturou a vzít se zpátky nedá. Doklad se tím nemění a číslo z řady se nespotřebuje. * `set_invoice_paid` (označit fakturu za (ne)zaplacenou) * `match_payment_by_vs` (potvrdit přijatý převod) * Věta o důsledku v potvrzení: > Spárování OZNAČÍ OBJEDNÁVKU ZAPLACENOU: zákazníkovi odejde e-mail o přijetí platby, částka se zapíše do tržeb a zboží na zakázku odejde do výroby, takže vrátit to NELZE. Potvrdí se jen platba, která sedí na haléř, je v korunách a patří právě jedné objednávce placené převodem nebo fakturou. * `dismiss_bank_payment` (uklidit frontu párování) Hodnota bez odrážky Věta o důsledku v potvrzení žádnou takovou větu nemá. ## `shopzi_manage_order`: parametry `operation` až `documentId` [#shopzi-manage-order-parametry-operation-az-documentid] * `operation` (jedna z hodnot `set_status`, `set_payment_status`, `set_billing_extras`, `set_quotation_prices`, `create_shipment`, `set_shipment_status`, `track_shipment`, `create_return`, `set_return_status`, `restock_return`, `create_return_shipment`, `approve_return`, `resend_invoice`, `set_invoice_paid`, `match_payment_by_vs` a `dismiss_bank_payment`; povinný): set\_status = stav objednávky; set\_payment\_status = stav platby; set\_billing\_extras = doprava a příplatky; set\_quotation\_prices = nacenění velkoobchodní poptávky; create\_shipment = založit zásilku (u dopravce s napojením objedná skutečný svoz); set\_shipment\_status = ručně posunout stav zásilky; track\_shipment = zjistit stav u dopravce; create\_return = založit vratku nebo reklamaci k objednávce; create\_return\_shipment = vygenerovat zpětnou zásilku Zásilkovnou; set\_return\_status = zapsat přijetí vráceného zboží nebo uzavření případu; restock\_return = vrátit schválené kusy z vratky na sklad; match\_payment\_by\_vs = potvrdit přijatý bankovní převod, tedy označit objednávku zaplacenou podle variabilního symbolu a částky; dismiss\_bank\_payment = uklidit frontu párování (položka výpisu s objednávkami nesouvisí, nebo se vrací zpátky do fronty); approve\_return = schválit množství vratky; resend\_invoice = znovu poslat fakturu; set\_invoice\_paid = (ne)zaplacená faktura bez objednávky. * `orderId` (UUID; nepovinný): ID objednávky (UUID) ze `shopzi_search_orders`. Povinné u všech operací kromě `set_return_status`, `restock_return`, `create_return_shipment` a `approve_return`, které chtějí `returnId`, a `set_invoice_paid` (`documentId`). U `resend_invoice` stačí místo `documentId`. * `status` (jedna z hodnot `pending`, `received`, `confirmed`, `processing`, `shipped`, `delivered`, `completed`, `cancelled` a `rejected`; nepovinný): Jen `set_status`. Nový stav objednávky. Jen dopředu: z „delivered“ zpět na „processing“ to nejde. `cancelled` a `rejected` nástroj odmítne, zrušení patří do administrace. * `paymentStatus` (jedna z hodnot `pending`, `authorized`, `paid`, `failed`, `refunded` a `partially_refunded`; nepovinný): Jen `set_payment_status`. `paid` = potvrzení přijaté platby (typicky bankovní převod), `failed` = platba se nezdařila. `refunded` a `partially_refunded` nástroj odmítne, vrácení peněz je dobropis ve Vratkách. * `shippingPriceMinor` (celé číslo; nepovinný): Jen `set_billing_extras` a `set_quotation_prices`. Cena dopravy včetně DPH v haléřích. Vynechané pole nechá dopravu, jak je. * `charges` (pole objektů; nepovinný): Jen `set_billing_extras`. CELÝ seznam příplatků: co v něm není, to se z objednávky smaže. Prázdný seznam zruší všechny příplatky, vynechané pole je nechá beze změny. * `charges[].label` (text; povinný): Název příplatku. Vytiskne se na doklad jako název položky. * `charges[].amountMinor` (celé číslo; povinný): Částka VČETNĚ DPH v haléřích (149 Kč = 14900). Nikdy ne nula. * `charges[].vatRate` (celé číslo; povinný): Sazba DPH jako celé procento: 21, 12 nebo 0. Nikdy ne 0.21. * `lines` (pole objektů; nepovinný): Jen `set_quotation_prices`. Ceny VŠECH řádků poptávky. Chybějící řádek nástroj odmítne, protože nenaceněná položka by se prodala za nulu. * `lines[].lineId` (UUID; povinný): ID řádku poptávky (UUID) ze `shopzi_get_order`. * `lines[].unitPriceMinor` (celé číslo; povinný): Cena za JEDEN kus včetně DPH, v haléřích. * `shipmentId` (UUID; nepovinný): Jen `set_shipment_status` a `track_shipment`: ID zásilky (UUID). VYNECHTE HO, když má objednávka jedinou zásilku, což je běžný případ: nástroj si ji dohledá sám. Když jich má víc, odmítne a všechny je vypíše i s dopravcem, takže si vyberete z toho výpisu. * `shipmentStatus` (jedna z hodnot `label_created`, `handed_over`, `ready_for_pickup`, `delivered` a `cancelled`; nepovinný): Jen `set_shipment_status`. `handed_over` = předáno dopravci (pošle zákazníkovi e-mail „odesláno“), `ready_for_pickup` = připraveno k vyzvednutí, `delivered` = doručeno (u dobírky tím platba platí za přijatou a vystaví se doklad), `cancelled` = zrušit zásilku i u dopravce. Stavy jdou jen dopředu. * `trackingNumber` (text, nejvýš 120 znaků; nepovinný): Jen `set_shipment_status`. Sledovací číslo, když si obchodník posílá sám. Zapíše se před posunem stavu, aby ho e-mail zákazníkovi nesl s sebou. * `trackingUrl` (text, nejvýš 1000 znaků; nepovinný): Jen `set_shipment_status`. Odkaz na sledování zásilky. * `parcelWeightGrams` (celé číslo; nepovinný): Jen `create_shipment`. Hmotnost balíku v gramech. Vynechané pole = spočítá se z položek objednávky. * `parcelLengthMm` (celé číslo; nepovinný): Jen `create_shipment`. Délka balíku v milimetrech. Rozměry se použijí jen tehdy, když pošlete všechny tři; jinak se spočítají z položek objednávky. * `parcelWidthMm` (celé číslo; nepovinný): Jen `create_shipment`. Šířka balíku v milimetrech. * `parcelHeightMm` (celé číslo; nepovinný): Jen `create_shipment`. Výška balíku v milimetrech. * `returnId` (UUID; nepovinný): ID vratky (UUID) ze `shopzi_list_returns`. Chtějí ho `set_return_status`, `restock_return`, `create_return_shipment` a `approve_return`. * `returnRegime` (jedna z hodnot `withdrawal` a `reklamace`; nepovinný): Jen `create_return`, a je povinný. `withdrawal` = odstoupení od smlouvy do čtrnácti dnů (zboží je v pořádku, zákazník si to rozmyslel), `reklamace` = vada zboží. Rozhoduje o lhůtách i o tom, co vůbec jde vrátit. * `returnReason` (jedna z hodnot `changed_mind`, `better_price`, `wrong_size`, `looks_different`, `arrived_late`, `no_longer_needed`, `defective`, `damaged_in_transit`, `wrong_item`, `missing_parts`, `not_as_described`, `quality_issue` a `other`; nepovinný): Jen `create_return`. Důvod, který zákazník uvedl. Vynechané pole = bez důvodu. * `returnNote` (text, nejvýš 2000 znaků; nepovinný): Jen `create_return`. Poznámka zákazníka k vratce, například co přesně je vadné. * `returnItems` (pole objektů; nepovinný): Jen `create_return`. Které položky se vracejí a kolik kusů. VYNECHEJTE ho, když se vrací celá objednávka: nástroj vezme všechno, co z ní ještě vrátit jde. Prázdný seznam odmítne, protože „nic jsem nevybral“ a „vrať všechno“ jsou dvě různá zadání. * `returnItems[].orderLineId` (UUID; povinný): ID řádku objednávky (UUID) ze `shopzi_get_order`, tedy položka, která se vrací. * `returnItems[].quantity` (celé číslo aspoň 1; povinný): Kolik kusů se vrací. Nejvýš tolik, kolik z té položky ještě vrátit jde; víc nástroj odmítne. * `returnStatus` (jedna z hodnot `received` a `closed`; nepovinný): Jen `set_return_status`. `received` = vrácené zboží dorazilo do obchodu, `closed` = případ je vyřízený a uzavřený. Stavy jdou jen dopředu. Zrušit vratku nástroj neumí. * `approvals` (pole objektů; nepovinný): Jen `approve_return`: uznaná množství po položkách. VYNECHEJTE = vše uplatněné. Prázdný seznam i samé nuly nástroj odmítne. * `approvals[].returnItemId` (UUID; povinný): `detail.items[].id` ze `shopzi_list_returns` s `returnId`. * `approvals[].quantity` (celé číslo aspoň 0; povinný): Uznané kusy, nejvýš uplatněné; 0 = neuznat. * `documentId` (UUID; nepovinný): Jen `resend_invoice` a `set_invoice_paid`: ID faktury ze `shopzi_list_documents` nebo `shopzi_get_order`. ## `shopzi_manage_order`: parametry `invoicePaid`, `payment` a `idempotencyKey` [#shopzi-manage-order-parametry-invoicepaid-payment-a-idempotencykey] * `invoicePaid` (`true` nebo `false`; nepovinný): Jen `set_invoice_paid`: true = zaplacená. Jen faktura BEZ objednávky, jinak `set_payment_status`. * `payment` (objekt; nepovinný): Jen `match_payment_by_vs` a `dismiss_bank_payment`. Údaje o platbě, kterou párujeme. * `payment.orderNumber` (text, 1 až 64 znaků; nepovinný): Číslo objednávky, kterou platba hradí (například 2026-0042), ze `shopzi_search_orders`. Povinné u `match_payment_by_vs`. U `dismiss_bank_payment` ho NEPOSÍLEJTE: ten žádnou objednávku neoznačuje. * `payment.variableSymbol` (text, nejvýš 32 znaků; nepovinný): Variabilní symbol platby, opsaný přesně tak, jak ho obchodník vidí (i s nulami na začátku). Povinný u `match_payment_by_vs`; u `dismiss_bank_payment` ho pošlete tehdy, když ta platba nějaký symbol má. * `payment.paidAmountMinor` (celé číslo; nepovinný): Částka v HALÉŘÍCH, celé číslo (1 250,50 Kč = 125050). Povinná u obou operací; podle ní se platba dohledá ve frontě. U potvrzení musí sedět na haléř, nástroj nic nezaokrouhluje. U bankovního poplatku bývá záporná, opište ji i se znaménkem. * `payment.bankVerdict` (jedna z hodnot `ignore` a `requeue`; nepovinný): Jen `dismiss_bank_payment`. `ignore` = ta položka výpisu s objednávkami nesouvisí (bankovní poplatek, převod mezi vlastními účty); `requeue` = vrátit dřív ignorovanou položku zpátky do fronty k posouzení. * `idempotencyKey` (text, 1 až 200 znaků; nepovinný): Klíč idempotence. Stejný klíč = stejný zápis: opakované volání vrátí původní výsledek a NEZAPÍŠE podruhé. Použijte vlastní náhodný řetězec pro každou zamýšlenou změnu; při opakování po chybě sítě pošlete tentýž.