API Dokumentace

Autentizace přes OAuth 2.1 (doporučeno)

Pro AI klienty (Claude.ai, ChatGPT i vlastní agenty) je doporučenou metodou OAuth 2.1 — připojíte se jedním kliknutím, bez kopírování jakéhokoli tajného klíče. Stačí v daném AI klientovi přidat vlastní MCP konektor a zadat adresu serveru:

https://www.fakturujsi.cz/api/mcp/v1

Klient pak automaticky projde autorizačním tokem (authorization code + PKCE): otevře se přihlašovací a souhlasná obrazovka Fakturujsi, kde vyberete, ke kterým datům agentovi udělíte přístup. Souhlas je tím oprávněním — přidělené scopy z tokenu řídí, které nástroje agent uvidí. Žádné nastavení v AI Studio > Connections ani tarifní brána se pro OAuth neuplatní.

Odpojení je okamžité: zrušením udělení (grantu) v Nastavení > AI Studio token při dalším požadavku přestane platit. Přístupové tokeny jsou krátkodobé a při každém požadavku se znovu ověřuje platnost grantu i členství uživatele v organizaci.

MCP přes OAuth rozumí 11 scopům: invoices:read, invoices:write, contacts:read, contacts:write, expenses:read, expenses:write, products:read, payments:read, payments:write, bank:read a reports:read. Uživatel může udělit jen scopy, které dovoluje jeho role v organizaci (např. čtenář neudělí *:write).

Autentizace přes API klíč (CLI / headless / starší integrace)

Alternativně lze MCP endpoint volat se stejnou Bearer autentizací jako REST API — API klíčem ve formátu fak_xxx. Tato cesta se hodí pro CLI a serverové (headless) skripty. Klíč musí mít scope mcp:connect, plus scopy odpovídající nástrojům, které agent bude volat (např. invoices:write pro create_invoice).

U API klíče platí dvojí kontrola oprávnění: kromě scope klíče musí mít daný zdroj v Nastavení > AI Studio > Connections nastavený accessLevel alespoň write (nebo read pro read-only nástroje). Nástroje, které nesplňují accessLevel, se vůbec nezobrazí v tools/list. (U OAuth se naopak sada nástrojů odvozuje přímo ze scopů v tokenu.)

IP allowlist a rate limit

Pro API klíč lze v Nastavení > AI Studio > Connections nastavit pole povolených IP adres (allowedIps) a minutový limit požadavků (rateLimitPerMinute, max 1 000). Prázdné pole allowlistu = povolení všech IP. Exact string match, bez podpory CIDR ve verzi 1. Vynucení je aktivní pouze pokud enforceStrictAccessControl = true (výchozí pro nové organizace).

OAuth připojení používají pevný limit 120 požadavků / minuta na organizaci a vynucují ho vždy. IP allowlist se u OAuth neuplatňuje (cloudoví AI klienti chodí z rotujících IP) — bezpečnostní branou je souhlas a okamžitě odvolatelný grant.

Konfigurace přes API klíč (Claude Desktop / CLI)

V cloudových klientech (Claude.ai, ChatGPT) přidejte Fakturujsi jako vlastní MCP konektor zadáním adresy https://www.fakturujsi.cz/api/mcp/v1 — autentizaci vyřeší OAuth (viz výše). Pro lokální Claude Desktop nebo headless skripty lze použít API klíč v konfiguračním souboru (~/Library/Application Support/Claude/claude_desktop_config.json na macOS, %APPDATA%/Claude/claude_desktop_config.json na Windows):

{
  "mcpServers": {
    "fakturujsi": {
      "url": "https://www.fakturujsi.cz/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer fak_xxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

JSON-RPC metody

Dostupné nástroje (tools)

Celkem 15 nástrojů — 7 read + 8 write. Které z nich agent uvidí, závisí na oprávněních: u OAuth na scopech v tokenu, u API klíče na scope klíče a konfiguraci exposedResources v organizaci.

Příklady (curl)

initialize

curl -X POST "https://www.fakturujsi.cz/api/mcp/v1" \
  -H "Authorization: Bearer fak_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0.0" }
    }
  }'

tools/list

curl -X POST "https://www.fakturujsi.cz/api/mcp/v1" \
  -H "Authorization: Bearer fak_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }'

tools/call — create_invoice

curl -X POST "https://www.fakturujsi.cz/api/mcp/v1" \
  -H "Authorization: Bearer fak_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "create_invoice",
      "arguments": {
        "contact_email": "klient@firma.cz",
        "items": [
          { "description": "Konzultace", "quantity": 5, "unit_price": 2000, "tax_rate": 21 }
        ],
        "notes": "Automaticky z MCP agenta",
        "status": "draft"
      }
    }
  }'

Příklad (Python, httpx)

import httpx

MCP_URL = "https://www.fakturujsi.cz/api/mcp/v1"
API_KEY = "fak_xxxxxxxxxxxxxxxxxxxxx"

def mcp_call(method: str, params: dict | None = None, req_id: int = 1):
    response = httpx.post(
        MCP_URL,
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        json={"jsonrpc": "2.0", "id": req_id, "method": method, "params": params or {}},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

# 1) Discover tools
tools = mcp_call("tools/list", req_id=1)["result"]["tools"]
print(f"Available tools: {[t['name'] for t in tools]}")

# 2) Create an invoice
result = mcp_call(
    "tools/call",
    {
        "name": "create_invoice",
        "arguments": {
            "contact_email": "klient@firma.cz",
            "items": [{"description": "Konzultace", "quantity": 5, "unit_price": 2000, "tax_rate": 21}],
            "status": "draft",
        },
    },
    req_id=2,
)
print(result["result"]["content"][0]["text"])

Chybové kódy JSON-RPC