Než začnete
- API je součástí tarifu Enterprise. Na ostatních tarifech se sekce Nastavení → API zobrazí, ale klíč vytvořit nepůjde.
- Klíč vytvoří hlavní účet firmy v aplikaci: Nastavení → API → Vytvořit klíč. Klíč začíná
mk_live_a zobrazí se jen jednou — hned si ho uložte. Ukládáme pouze jeho otisk, takže ho později nelze znovu zobrazit, pouze odvolat a vytvořit nový. - Základní adresa:
https://mikisi.cz/api. Všechny požadavky jdou přes HTTPS. - Klíč pracuje s daty celé firmy (všechny účetní jednotky). Vytěžení přes API se počítá do měsíčního limitu tarifu stejně jako v aplikaci.
- Klíče vidí a spravuje jen hlavní účet; uživatelé přidaní v Nastavení → Uživatelé sekci API nemají. Na účet lze mít nejvýše 10 aktivních klíčů.
- Změna tarifu: po přechodu z Enterprise na nižší tarif klíče přestanou platit (požadavky vrátí
403). Zůstávají uložené — po návratu na Enterprise fungují znovu, nebo je v nastavení odvoláte.
Jak API zapojit
API nenahrazuje aplikaci — doplňuje ji. Vše, co přes API vznikne, vidíte i v aplikaci a naopak. Podle toho, kde chcete doklady kontrolovat, se hodí jeden ze tří modelů:
| Model | Vstup dokladů | Kontrola | Výstup |
|---|---|---|---|
| Plně přes API | POST /upload + POST /extract/{id} z vašeho systému | volitelně GET /documents/{id}, opravy PATCH | vytěžená data jako JSON (GET /documents) nebo export XML / ISDOC / CSV přes API |
| Vstup v MIKISI, výstup přes API | nahrání v aplikaci, e‑mailem nebo z mobilu | účetní zkontroluje v aplikaci | váš systém si průběžně stahuje hotová data, např. GET /documents?status=extracted&date_from=… |
| Vstup přes API, výstup v MIKISI | váš systém posílá doklady přes API | účetní zkontroluje v aplikaci | export do Pohody / Money klikem v aplikaci |
Účetní jednotky si nastavte jednou v aplikaci (Nastavení → Účetní jednotky: číselné řady, cílový účetní program, střediska). Přes API pak jednotky jen čtete (GET /units) a používáte jejich ID ve filtrech nebo při přiřazení dokladu; založit jednotku přes API lze (POST /units), ale její nastavení je pohodlnější v aplikaci.
Přiřazení dokladu k jednotce probíhá při vytěžení stejně jako v aplikaci: (1) shoduje‑li se IČO odběratele na dokladu s IČO některé jednotky, doklad jde do ní; (2) jinak podle volby Nastavení → Zobrazení → Přiřazení jednotky — „Automaticky (výchozí jednotka)" doklad zařadí do výchozí jednotky, „Zeptat se při každé extrakci" ho nechá čekat na ruční přiřazení; (3) kdykoli to přebijete přes PATCH /documents/{id} s accounting_unit_id. Pro integraci doporučujeme volbu „Automaticky" (výchozí) nebo vyplněná IČO u jednotek.
Autentizace
Klíč posílejte v každém požadavku v hlavičce Authorization:
Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKlíč umožňuje práci s doklady (nahrání, vytěžení, čtení, úpravy, export) a čtení účetních jednotek a středisek. Správa účtu, hesla, uživatelů, plateb ani samotných klíčů přes API není možná — na tyto adresy odpoví server 403. Neplatný nebo odvolaný klíč vrátí 401.
Formát odpovědí
Odpovědi jsou JSON. Většina endpointů vrací obálku:
{
"success": true,
"message": "Success",
"data": { … },
"timestamp": "2026-09-03T14:05:12.345Z"
}Při chybě je success: false a v message (u některých endpointů v error) je česky popsaná příčina. HTTP stavový kód odpovídá typu chyby — viz Chyby a limity.
Data dokladu (document) používají názvy sloupců MIKISI: document_number, document_type, issue_date, tax_date, due_date, variable_symbol, supplier_name, supplier_ico, supplier_dic, supplier_street, supplier_city, supplier_zip, supplier_country, customer_name, customer_ico, customer_dic, total_without_vat, total_vat, total_with_vat, currency, exchange_rate, bank_account, is_credit_note, reverse_charge, status, accounting_unit_id, cost_center_id. Položky (items) mají line_number, description, quantity, unit, unit_price, vat_rate, vat_amount, total_price, currency, cost_center_id. Data jsou ve formátu YYYY-MM-DD, částky jsou čísla.
Rychlý start
Celý průchod: nahrát PDF → vytěžit → přečíst data. V příkladech je klíč v proměnné MIKISI_KEY.
# 1) Nahrání dokladu (multipart, pole "document")
curl -X POST https://mikisi.cz/api/upload \
-H "Authorization: Bearer $MIKISI_KEY" \
-F "[email protected]" \
-F "document_type=prijata_faktura"
# → { "success": true, "data": { "documentId": 1234, "filename": "faktura.pdf", "status": "pending" } }
# 2) Vytěžení (synchronně, obvykle 5–20 s)
curl -X POST https://mikisi.cz/api/extract/1234 \
-H "Authorization: Bearer $MIKISI_KEY"
# → { "success": true, "data": { …vytěžená data…, "quota": { "used": 12, "limit": 1200, … } } }
# 3) Uložený doklad s položkami (stabilní názvy polí, viz Formát odpovědí)
curl https://mikisi.cz/api/documents/1234 \
-H "Authorization: Bearer $MIKISI_KEY"
# → { "success": true, "data": { "document": { "supplier_name": …, "total_with_vat": … }, "items": [ … ] } }Totéž v Pythonu:
import requests
API = "https://mikisi.cz/api"
H = {"Authorization": f"Bearer {MIKISI_KEY}"}
with open("faktura.pdf", "rb") as f:
r = requests.post(f"{API}/upload", headers=H,
files={"document": f},
data={"document_type": "prijata_faktura"})
doc_id = r.json()["data"]["documentId"]
requests.post(f"{API}/extract/{doc_id}", headers=H, timeout=180).raise_for_status()
data = requests.get(f"{API}/documents/{doc_id}", headers=H).json()["data"]
print(data["document"]["supplier_name"], data["document"]["total_with_vat"])
for item in data["items"]:
print(item["description"], item["quantity"], item["total_price"])Nahrání dokladu
| Endpoint | Popis |
|---|---|
POST/upload | Jeden soubor v poli document (multipart/form-data). Volitelně document_type. |
POST/upload/batch | Až 50 souborů v poli documents. Volitelně document_type pro všechny. |
Formáty: PDF, JPG, PNG, HEIC, max. 10 MB na soubor. Jeden soubor = jeden doklad; vícestránkový doklad pošlete jako jedno PDF.
document_type: prijata_faktura (výchozí), vydana_faktura, pokladni_doklad, zalohova_faktura, vydana_zalohova_faktura, jine_zavazky, nebo auto — typ pak určí vytěžení podle dokladu.
Nahráním se doklad jen uloží (stav pending); do měsíčního limitu se počítá až vytěžení. K účetní jednotce se doklad přiřadí při vytěžení (podle IČO odběratele, jinak podle nastavení účtu — viz Jak API zapojit); jinou jednotku nastavíte úpravou dokladu (PATCH /documents/{id} s accounting_unit_id).
Vytěžení
| Endpoint | Popis |
|---|---|
POST/extract/{id} | Synchronně — počká na výsledek a vrátí vytěžená data (viz níže). Obvykle 5–20 s, u vícestránkových PDF i déle; nastavte timeout alespoň 120 s. |
POST/extract/async/{id} | Asynchronně — zařadí do fronty a vrátí jobId. Vhodné pro dávky. |
GET/extract/job/{jobId}/status | Stav úlohy: state (waiting, active, completed, failed), případně failedReason. Po dokončení načtěte data přes GET /documents/{id}. |
POST/extract/batch | Hromadně: JSON { "documentIds": [1, 2, 3] } (max. 200). Vrátí batchId. |
GET/extract/batch/{batchId}/status | Stav dávky: status (processing, completed, completed_with_errors), progress v %, počty total, completed, failed, processing, queued. |
Synchronní vytěžení vrací v data surový výstup vytěžení (struktura s českými klíči, např. dodavatel, castky, polozky) a objekt quota (used, limit, remaining). Tato struktura se může s vývojem vytěžování měnit — pro integraci proto čtěte uložený doklad přes GET /documents/{id}, kde jsou stabilní názvy polí z části Formát odpovědí.
Každé úspěšné vytěžení odečte jeden doklad z měsíčního limitu. Po vyčerpání limitu vrátí server 403 s kódem QUOTA_EXCEEDED (nebo QUOTA_EXCEEDED_NO_CREDIT); kredit nad rámec tarifu se dokupuje v aplikaci. Pokud předplatné není uhrazeno (selhalo automatické stržení z karty, nebo vypršelo), vrátí vytěžení 403 s kódem SUBSCRIPTION_UNPAID a doklady se nezpracují, dokud hlavní účet předplatné neobnoví v aplikaci (Nastavení → Tarif a fakturace).
Práce s doklady
| Endpoint | Popis |
|---|---|
GET/documents | Seznam dokladů s filtry a stránkováním (viz níže). |
GET/documents/{id} | Detail dokladu včetně položek (document, items). |
GET/documents/{id}/file | Originální soubor (PDF/obrázek). |
PATCH/documents/{id} | Úprava vytěžených hodnot — JSON s libovolnou podmnožinou polí dokladu (např. document_number, issue_date, total_with_vat, accounting_unit_id, cost_center_id). |
PATCH/documents/{id}/items/{itemId} | Úprava jedné položky. |
POST/documents/archive | Archivace: JSON { "documentIds": [ … ] }. Obdobně /documents/unarchive. |
DELETE/documents/{id} | Smazání dokladu včetně souboru. |
Filtry seznamu (query parametry): status (pending, extracted, exported), document_type, accounting_unit_id, date_from / date_to (datum vystavení), search (číslo dokladu, dodavatel, IČO), is_archived, needs_review, sort_by / sort_order, page a limit (výchozí 50). Odpověď obsahuje pole documents a údaje o stránkování.
# Vytěžené, dosud neexportované doklady jednotky 12 z tohoto měsíce
curl "https://mikisi.cz/api/documents?status=extracted&accounting_unit_id=12&date_from=2026-09-01&limit=100" \
-H "Authorization: Bearer $MIKISI_KEY"Export do účetnictví
| Endpoint | Popis |
|---|---|
POST/pohoda/export/{id} | XML pro Pohodu — jeden doklad. |
POST/pohoda/export/batch | XML pro Pohodu — dávka: { "documentIds": [ … ] }. |
GET/pohoda/validate/{id} | Kontrola dokladu před exportem (chybějící údaje apod.). |
POST/export/money-s3 | XML pro Money S3: { "documentIds": [ … ], "startNumber": "FP26001" } (počáteční číslo nepovinné). |
POST/export/isdoc | ISDOC: { "documentIds": [ … ] }; jeden doklad = .isdoc, více = ZIP. Bez documentIds exportuje všechny vytěžené. |
GET/export/csv | CSV se všemi vytěženými doklady. |
GET/export/excel | XLSX se všemi vytěženými doklady. |
POST/export/originals | ZIP originálních souborů: { "documentIds": [ … ] }. |
Exportní endpointy vracejí přímo soubor (hlavička Content-Disposition), ne JSON. Doklady se v dávce řadí podle data vystavení. Export označí doklady stavem exported; opakovaný export je možný kdykoli.
curl -X POST https://mikisi.cz/api/pohoda/export/batch \
-H "Authorization: Bearer $MIKISI_KEY" -H "Content-Type: application/json" \
-d '{"documentIds":[1234,1235]}' -o pohoda-import.xmlÚčetní jednotky a střediska
| Endpoint | Popis |
|---|---|
GET/units | Seznam účetních jednotek (ID použijete ve filtrech a při přiřazení dokladu). |
GET/units/{id} | Detail jednotky. |
GET/units/{id}/number-series | Číselné řady jednotky. |
GET/cost-centers?accounting_unit_id={id} | Střediska jednotky. |
GET/ares/lookup/{ico} | Údaje firmy z ARES podle IČO. |
Chyby a limity
| Kód | Význam |
|---|---|
400 | Chybný požadavek (chybí soubor, neplatné ID, nepodporovaný formát). |
401 | Chybí, neplatný nebo odvolaný klíč. |
403 | Klíč na tento endpoint nesmí, účet nemá tarif s API, je vyčerpán měsíční limit (QUOTA_EXCEEDED), nebo není uhrazeno předplatné (SUBSCRIPTION_UNPAID — obnovte ho v aplikaci). |
404 | Doklad / jednotka neexistuje nebo nepatří vašemu účtu. |
429 | Překročen limit požadavků — počkejte a zkuste znovu (viz níže). |
500 | Chyba na naší straně — zopakujte požadavek, při opakování napište na podporu. |
Limity požadavků: nejvýše 500 požadavků za 10 minut na jeden klíč a 1 200 nahraných souborů za hodinu na účet. Vytěžení je omezeno měsíčním limitem tarifu (Enterprise 1 200 dokladů; navíc lze dokoupit kredit). Server vrací hlavičky X-RateLimit-*.
Doporučení: u větších objemů nahrávejte dávkově (/upload/batch) a vytěžujte asynchronně (/extract/batch nebo /extract/async/{id}); stav se dotazujte nejvýše jednou za pár sekund.
Bezpečnost klíče
- Klíč je jako heslo: neukládejte ho do veřejného kódu, neposílejte e-mailem, nevkládejte do adresy URL.
- Pro každou integraci vytvořte vlastní klíč a pojmenujte ho — půjde odvolat samostatně, aniž by vypadly ostatní.
- Při podezření na únik klíč v Nastavení → API okamžitě odvolejte a vytvořte nový. Odvolání platí ihned.
- Vytvoření i odvolání klíče se zapisuje do bezpečnostního logu účtu. V přehledu klíčů vidíte, kdy byl který naposledy použit.
Podpora
S napojením rádi pomůžeme — napište na [email protected] a přiložte, co se vám vrací (stavový kód a tělo odpovědi). Pokud vám v API chybí funkce, kterou máte v aplikaci, ozvěte se; seznam endpointů dostupných přes API rozšiřujeme podle potřeb zákazníků.