Migrace z iDoklad API: kam přejít a jak na to

iDoklad ukončuje API v2 k 8. 9. 2026. Ať už integraci přepíšete na jejich v3, nebo ji přenesete jinam, přepis kódu vás čeká tak jako tak — otázka je jen, na čem budete stavět dál. Tenhle průvodce je mapa pro druhou variantu: co u nás odpovídá kterému zdroji, jak se autentizujete, jak fungují naše webhooky a jaké platí limity.

Mapování zdrojů: iDoklad v3 → Fakturujsi API v2

Naše aktuální REST API je v2 na adrese https://www.fakturujsi.cz/api/v2. Strojově čitelná specifikace je na /api/v2/openapi.json (OpenAPI 3.1), interaktivní dokumentace na /docs/api/v2. Kde ekvivalent nemáme, je to v tabulce napsané — ne obcházené.

Nad rámec tabulky nabízí starší v1 ještě bankovní účty a transakce (/api/v1/bank/accounts, /api/v1/bank/transactions) a hotové reporty (/api/v1/reports/revenue, overdue, expenses) — popsané v dokumentaci v1. Pro novou integraci sahejte po v2: má kurzorové stránkování, dávkové operace a jednotný formát chyb.

Autentizace

iDoklad v3 jede na OAuth2 (Authorization Code i Client Credentials). U nás máte dvě cesty a každá je vhodná na něco jiného:

Klíč se posílá v hlavičce Authorization:

Authorization: Bearer fak_xxxxxxxxxxxxxxxxxxxxx

Scopy

Každý klíč nese vlastní sadu oprávnění. Chybějící scope vrací 403 FORBIDDEN se jménem toho, který chybí:

Ukázka: vystavení faktury

Povinná pole jsou contactId, issueDate, dueDate a aspoň jedna položka. Číslo dokladu ani variabilní symbol neposíláte — přidělí se z číselné řady na serveru, v jedné transakci s vložením faktury.

curl -X POST "https://www.fakturujsi.cz/api/v2/invoices" \
  -H "Authorization: Bearer fak_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "3f1c1b02-9b3d-4a7e-9f11-2c8d5e6a7b90",
    "issueDate": "2026-09-09",
    "dueDate": "2026-09-23",
    "currency": "CZK",
    "status": "issued",
    "items": [
      {
        "description": "Vyvoj integrace",
        "quantity": 8,
        "unit": "h",
        "unitPrice": 1500,
        "taxRate": 21
      }
    ]
  }'

Odpověď je zabalená v klíči data. Peněžní částky chodí jako řetězce, aby se cestou neztratila přesnost:

{
  "data": {
    "id": "8c0f4d21-5a6b-4c3d-8e9f-1a2b3c4d5e6f",
    "number": "20260042",
    "status": "issued",
    "currency": "CZK",
    "subtotal": "12000.00",
    "taxTotal": "2520.00",
    "total": "14520.00"
  }
}

Webhooky

Odběry se spravují přes /api/v2/webhooks (GET, POST, PUT, DELETE) a otestovat doručení jde kdykoli přes POST /api/v2/webhooks/{id}/test. Podpisový secret dostanete jen jednou, při vytvoření odběru.

Pokud stavíte konektor pro Zapier nebo Make, hodí se REST hooks: POST /api/v1/hooks/subscribe a /api/v1/hooks/unsubscribe. Kompletní popis obou je v dokumentaci API.

Limity a tarify

Limity API v2 se počítají ve dvou oknech současně — minutovém i denním — a v hlavičkách X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset vidíte ten přísnější z nich. Při překročení dostanete 429 s hlavičkou Retry-After.

Rozdíl, který v praxi rozhoduje o architektuře, není ani tak výška limitu jako jeho okno. iDoklad podle svého ceníku počítá požadavky měsíčně: tarif Oblíbený má 7 500 požadavků za měsíc, tarif Prémiový 75 000 za měsíc, a nejnižší placený tarif API neobsahuje vůbec. Měsíční kvóta znamená, že jeden špatně napsaný cyklus na začátku měsíce vám může vyčerpat rozpočet na zbytek období. Denní okno se naproti tomu vyresetuje druhý den.

Údaje o tarifech iDokladu vycházejí z jeho veřejného ceníku na idoklad.cz/cenik ověřeného k 26. 8. 2026. Ceny tam jsou uváděné bez DPH a liší se podle toho, jestli platíte měsíčně, čtvrtletně, nebo ročně; nabídka se může měnit, aktuální stav si ověřte přímo u zdroje.

MCP: co dostanete navíc oproti REST

Kromě REST API vystavujeme MCP server (Model Context Protocol) na POST /api/mcp/v1. Je to JSON-RPC 2.0 přes Streamable HTTP — díky němu se na vaše fakturační data napojí Claude.ai, ChatGPT i vlastní agent, aniž byste pro ně psali jediný řádek integračního kódu.

• Připojení na jedno kliknutí: v AI klientovi zadáte adresu serveru a projdete OAuth 2.1 tokem (authorization code + PKCE). Žádný secret nikam nekopírujete. Podporovaná je dynamická registrace klienta (RFC 7591) i discovery přes /.well-known/oauth-protected-resource a /.well-known/oauth-authorization-server.
• 15 nástrojů — 7 čtecích a 8 zapisujících, od list_invoices a get_revenue_summary po create_invoice a mark_invoice_paid. Agent uvidí jen ty, na které mu token dává scope.
• Čtení už na tarifu Zdarma. Zápisové scopy se pod tarifem Business z tokenu automaticky odřezávají, čtecí projdou vždy — a kontroluje se to při každém požadavku, takže i po změně tarifu platí okamžitě.
• Odvolatelné kdykoli: zrušením souhlasu v nastavení token při dalším požadavku přestane platit. OAuth připojení mají pevný limit 120 požadavků za minutu na organizaci.
• Verze protokolu se vyjednává v metodě initialize; podporujeme 2025-06-18 (výchozí), 2025-03-26 a 2024-11-05.

Kompletní popis — JSON-RPC metody, tabulka nástrojů se scopy, ukázky v curl i Pythonu, chybové kódy — je v sekci MCP protokol v dokumentaci API.

Postup přepisu krok za krokem

Časté dotazy