Dokumentace API — proč je klíčová i pro malé e-shopy
I menší e-shop mívá několik napojení a o žádném z nich nic sepsaného. Dokud nepřijde výpadek nebo nový vývojář. Ukážeme, co dokumentovat, v jakém rozsahu a jak to udržet živé.
I menší e-shop mívá několik napojení. Účetnictví, dopravce, platební bránu, jeden nebo dva dodavatelské feedy, možná sklad. Každé vzniklo jindy a dělal ho někdo jiný. Sepsané o nich není nic. Funguje to, dokud nepřijde výpadek, nový vývojář nebo změna na straně platformy. Pak se hodiny hledá, kde integrace běží, kdo zná přístupy a co vlastně dělá s daty.
Dokumentace API proto není luxus velkých firem s vlastním vývojovým týmem. U malého e-shopu je naopak důležitější, protože znalost často visí na jednom člověku. V článku rozebíráme, co dokumentovat, jak podrobně a jak dokumentaci udržet živou.
Dva druhy dokumentace, které se pletou
Když se řekne „dokumentace API“, myslí se dvě různé věci.
Dokumentace cizího API. Popis rozhraní platformy nebo služby, na kterou se napojujete. Píše ji poskytovatel. Shoptet má dokumentaci REST API na api.docs.shoptet.com a novinky zveřejňuje v pravidelných „API Release News“ na developers.shoptet.com. Shopify i WooCommerce mají vlastní vývojářské portály. Tuhle dokumentaci nepíšete, ale musíte ji umět číst a sledovat její změny.
Dokumentace vašich integrací. Popis toho, co si e-shop postavil nad cizími API. Který skript stahuje objednávky do účetnictví, jak často, s jakým klíčem, co dělá s chybami. Tu za vás nikdo nenapíše. A přesně ta u malých e-shopů chybí nejčastěji.
Co se stane, když dokumentace chybí
Pár situací, které se opakují:
- Odchází externí vývojář a s ním jediná znalost o tom, kde běží cron na synchronizaci skladu.
- Platforma oznámí změnu v API. Nikdo neví, jestli se týká vašich napojení, protože nikdo neví, které endpointy používají.
- Při migraci na novou platformu se zapomene na napojení, o kterém nikdo nevěděl. Objeví se až ve chvíli, kdy přestanou chodit faktury.
- Uniká API klíč a nevíte, kde všude se používá. Rotace klíče pak rozbije věci, o kterých jste neměli tušení.
Poslední bod řeší i bezpečnostní standardy. OWASP ve svém žebříčku API Security Top 10 (vydání 2023) uvádí jako samostatné riziko API9 Improper Inventory Management. Tedy situaci, kdy firma nemá aktuální přehled o svých API, jejich verzích a tocích citlivých dat. Nejde jen o pořádek. Bez přehledu nevíte, co chránit.
Co má obsahovat dokumentace integrace
Nemusíte psát román. U malého e-shopu stačí na každou integraci jedna stránka. Používáme tuto kostru:
| Položka | Co do ní patří |
|---|---|
| Účel | Jednou větou, co integrace dělá a proč existuje |
| Systémy a směr | Odkud kam tečou data (e-shop → účetnictví, dodavatel → e-shop) |
| Spouštění | Webhook, plánovaná úloha (a jak často), nebo ruční spuštění |
| Kde běží | Server, hosting, nástroj typu n8n, doplněk platformy |
| Přístupy | Jaký klíč nebo účet používá, kdo ho vlastní, kde je uložený (ne samotný klíč) |
| Mapování dat | Která pole se přenášejí a jak se převádějí (stavy objednávek, DPH, kódy dopravy) |
| Chyby | Co se stane při výpadku, kde jsou logy, kdo dostane upozornění |
| Kontakt | Kdo integraci postavil a kdo ji spravuje |
| Závislosti | Které endpointy a verze API používá, na jaké webhooky je přihlášená |
Nejvíc času ušetří řádky „Kde běží“, „Přístupy“ a „Závislosti“. Právě ty se při výpadku hledají nejdéle.
Podceňované je i mapování dat. Zapište konkrétně, že stav objednávky „Vyřízena“ v e-shopu odpovídá vystavené faktuře v účetnictví, nebo že doprava „Na výdejní místo“ se převádí na určitý kód služby dopravce. Tyhle drobnosti se po roce nepamatují a při změně je nikdo nedohledá jinak než čtením kódu.
Pokud máte víc napojení, přidejte jednoduchý přehledový diagram. Stačí krabičky a šipky: e-shop uprostřed, kolem něj systémy, u každé šipky název integrace. Když data tečou přes middleware, zakreslete ho jako samostatný uzel.
OpenAPI: když stavíte vlastní API
Jakmile vzniká vlastní API, třeba pro mobilní aplikaci, B2B odběratele nebo mezi vlastními službami, vyplatí se ho popsat standardem OpenAPI. Jde o otevřenou specifikaci pro strojově čitelný popis REST API ve formátu YAML nebo JSON. Aktuálně vydaná verze je 3.2 ze září 2025 (k 9/2026).
Výhoda je v tom, že jeden soubor slouží více účelům:
- Z popisu se vygeneruje přehledná dokumentace pro lidi.
- Soubor jde importovat do nástrojů pro testování API. Shoptet například nabízí ke stažení svůj soubor
openapi.yaml, který jde naimportovat do Postmanu a z něj se vytvoří kompletní kolekce požadavků. - Podle specifikace lze automaticky kontrolovat, jestli API vrací data ve slíbeném tvaru.
- Z popisu jde vygenerovat kostra klienta v různých jazycích.
Pravidlo, které dodržujeme: specifikace leží ve stejném repozitáři jako kód API. Změna kódu bez změny specifikace neprojde revizí. Jinak se dokumentace do půl roku rozejde se skutečností.
Changelog: sledujte změny na druhé straně
Dokumentace jednou sepsaná nestačí. API platforem se mění a změny oznamují v changelogu. Shoptet vydává API Release News pravidelně, v létě 2026 třeba dvakrát během jednoho týdne. Shopify vydává nové verze API čtvrtletně a staré po čase ruší. O tom podrobněji píšeme v článku Verzování API a zpětná kompatibilita.
Praktický postup: u každé integrace máte v dokumentaci seznam použitých endpointů. Když vyjde changelog, projdete ho proti tomuto seznamu. Bez seznamu musíte číst všechno a hádat.
Stejně tak veďte changelog vlastních integrací. Stačí datum, co se změnilo a proč. Až bude za rok něco fungovat jinak, uvidíte, kdy a proč se to stalo.
Jak na to prakticky
Pokud dnes nemáte sepsané nic, začněte takto:
- Udělejte inventuru. Projděte v administraci e-shopu API přístupy, doplňky a webhooky. Každý záznam je jedna integrace.
- Ke každé integraci vyplňte tabulku výše. Co nevíte, označte a dohledejte u dodavatele.
- Zkontrolujte, že přístupy vlastníte vy. API klíče a účty by měly být vedené na firmu, ne na osobní e-mail vývojáře.
- Uložte dokumentaci na jedno místo, kam máte přístup vy i dodavatelé. Hesla patří do správce hesel, ne do dokumentu.
- U nových zakázek chtějte dokumentaci jako součást předání. Stejně samozřejmě jako funkční kód.
- Jednou za čtvrtletí dokumentaci projděte a porovnejte se skutečností.
Obecnější úvod do API z pohledu majitele najdete v článku API pro e-shopy: co je potřeba vědět jako majitel.
Kdy nám zavolat
Pokud jste zdědili integrace bez dokumentace, nebo plánujete migraci a nevíte, co všechno je na e-shop napojené, uděláme inventuru a sepíšeme ji za vás. Když stavíte vlastní API, navrhneme ho včetně OpenAPI specifikace v rámci služby API a microservices. Stávající napojení zdokumentujeme a případně přestavíme v rámci služby integrace. Napište na info@prevedshop.cz nebo volejte +420 723 000 173.
Potřebujete s tím pomoct?