Fakturoid API v3 (2026): průvodce integrací a automatizací

Fakturoid je jeden z nejpopulárnějších českých cloudových fakturačních nástrojů, který denně používají desetitisíce firem, freelancerů a daňových poradců. API v3 je v září 2026 stále aktuální verzí — žádné v4 nevyšlo — a přináší moderní OAuth 2.0 autentizaci, stabilní webhooky a jasně definované rate limity s hlavičkami, které vám umožní automaticky reagovat na události v reálném čase. Novinkou roku 2026 je navíc oficiální MCP server, přes který se dá Fakturoid napojit přímo na AI asistenty jako Claude.

V tomto průvodci vám krok za krokem ukážeme, jak Fakturoid API v3 integrovat do vašeho systému — od registrace OAuth aplikace přes vytváření faktur v PHP a Pythonu až po napojení na Make.com, n8n a AI agenty. Vše je aktualizováno pro září 2026, včetně aktuálních tarifů a konkrétních API limitů pro jednotlivé tarify.

01Proč používat Fakturoid API v3?

Ruční fakturace je pomalá a náchylná k chybám. S API můžete:

• Automaticky vystavovat faktury při nové objednávce z e-shopu nebo po platbě v aplikaci
• Synchronizovat kontakty mezi CRM (Raynet, HubSpot) a Fakturodem obousměrně
• Sledovat platby v reálném čase díky webhookům místo pravidelného dotazování
• Párovat bankovní platby s fakturami a odeslat potvrzení zákazníkovi
• Generovat reporty pro účetnictví bez ručního exportu
• Propojit fakturaci s Make.com, n8n, AI agentem nebo vlastním back-endem

Oproti starší verzi v2 (která používala API klíč) přináší v3 především bezpečnější OAuth 2.0 autentizaci, lepší strukturované chybové odpovědi a sjednocený formát webhook notifikací.

02Základní informace o API v3 (k září 2026)

03Aktuální tarify Fakturoidu a API limity (2026)

Používání API je podmíněno vaším tarifem. Od února 2025 Fakturoid používá strukturu tarifů Zdarma / Na lehko / Na každý den / Na maximum, takže staré názvy (Basic, Plus, Premium) už neplatí. Ceny uvádíme při roční platbě; při měsíční platbě jsou o dvacet až dvěstě korun vyšší.

Praktické poznatky k limitům:

• 3 000 požadavků stačí na vystavení zhruba 1 000 faktur — jeden vytvořený doklad totiž typicky spotřebuje dva až tři požadavky (vytvoření kontaktu, vytvoření faktury, odeslání).
• Na tarifu Na maximum si můžete přikoupit dalších 10 000 API požadavků nad rámec tarifu dle aktuálního ceníku — hodí se pro sezónní špičky (fakturační vlny po konci projektu).
• Každý další uživatel nebo účetní stojí 91 Kč/měsíc při roční platbě.
• Pro nové podnikatele (IČO méně než 12 měsíců) je k dispozici sleva 50 % na první roční fakturu — ideální kombinace pro start s API.

Přesné aktuální ceny ověřte v oficiálním ceníku a v dokumentaci rate-limitingu.

04OAuth 2.0 autentizace krok za krokem

OAuth 2.0 je základem pro práci s Fakturoid API v3. Zde je kompletní postup od registrace aplikace až po automatický refresh tokenu.

https://app.fakturoid.cz/api/v3/oauth/authorize
  ?client_id={CLIENT_ID}
  &redirect_uri={REDIRECT_URI}
  &response_type=code
  &scope=read write

curl -X POST https://app.fakturoid.cz/api/v3/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTORIZACNI_KOD",
    "client_id": "VAS_CLIENT_ID",
    "client_secret": "VAS_CLIENT_SECRET",
    "redirect_uri": "https://vase-domena.cz/callback"
  }'

curl -X POST https://app.fakturoid.cz/api/v3/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "VAS_REFRESH_TOKEN",
    "client_id": "VAS_CLIENT_ID",
    "client_secret": "VAS_CLIENT_SECRET"
  }'

05Klíčové endpointy a CRUD operace

Většina endpointů vyžaduje slug vašeho Fakturoid účtu (název účtu) v URL.

Faktury (Invoices)

GET    /api/v3/{slug}/invoices.json          # Seznam faktur
POST   /api/v3/{slug}/invoices.json          # Vytvoření faktury
GET    /api/v3/{slug}/invoices/{id}.json     # Detail faktury
PATCH  /api/v3/{slug}/invoices/{id}.json     # Úprava faktury
DELETE /api/v3/{slug}/invoices/{id}.json     # Smazání faktury

Příklad vytvoření faktury:

{
  "subject_id": 123,
  "due_date": "2026-10-15",
  "currency": "CZK",
  "payment_method": "bank",
  "lines": [
    {
      "name": "Webový vývoj — září 2026",
      "quantity": 40,
      "unit_name": "hod",
      "unit_price": 1500,
      "vat_rate": 21
    },
    {
      "name": "Hosting a správa serveru",
      "quantity": 1,
      "unit_price": 2000,
      "vat_rate": 21
    }
  ]
}

Kontakty (Subjects)

GET    /api/v3/{slug}/subjects.json          # Seznam kontaktů
POST   /api/v3/{slug}/subjects.json          # Nový kontakt
GET    /api/v3/{slug}/subjects/{id}.json     # Detail kontaktu
PATCH  /api/v3/{slug}/subjects/{id}.json     # Úprava kontaktu

Události a párování plateb

GET    /api/v3/{slug}/invoices/{id}/events.json   # Historie událostí faktury
POST   /api/v3/{slug}/invoices/{id}/fire.json     # Spuštění akce (odeslání, upomínka)

Události zahrnují: vytvoření, odeslání e-mailem, zaplacení, upomínka, smazání. Pomocí fire.json můžete fakturu programově odeslat klientovi nebo vygenerovat upomínku.

06Novinka 2026: Fakturoid MCP server pro AI agenty

Fakturoid v roce 2026 spustil oficiální MCP server (Model Context Protocol) — odkaz najdete v patičce webu pod „API pro vývojáře a MCP server". Co to v praxi znamená?

MCP je otevřený standard, kterým AI asistenti jako Claude komunikují s externími nástroji. Místo abyste psali vlastní integrační vrstvu, připojíte AI agenta přímo k Fakturoidu a ten může:

• Vystavovat faktury přirozeným jazykem — „Vystav fakturu za 40 hodin vývoje klientovi XY, splatnost 14 dní"
• kontrolovat stav plateb — „Které faktury jsou po splatnosti déle než týden?"
• připravovat měsíční přehledy pro vedení bez exportu do Excelu

Pro koho je to užitečné:

• Freelanceři a malé firmy — fakturujete přímo z chatu s AI, bez přepínání aplikací
• Agentury — AI agent sleduje dokončené úkoly v projektovém nástroji a automaticky vystavuje faktury
• Účetní — rychlé dotazy na stav dokladů bez nutnosti rozumět API

MCP server se řídí stejnými API limity jako klasické API, takže veškerá matematika limitů z předchozí tabulky platí i tady. Pokud už MCP servery používáte, je to nejrychlejší cesta k automatizované fakturaci — bez jediného řádku kódu.

07Praktický příklad v PHP

Třída pro Fakturoid klienta s token managementem

<?php
declare(strict_types=1);

class FakturoidClient
{
    private const BASE_URL = 'https://app.fakturoid.cz/api/v3';

    public function __construct(
        private string $slug,
        private string $accessToken,
        private string $userAgent = 'MojeApp ([email protected])'
    ) {}

    public function createInvoice(array $data): array
    {
        $ch = curl_init(self::BASE_URL . "/{$this->slug}/invoices.json");

        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                "Authorization: Bearer {$this->accessToken}",
                'Content-Type: application/json',
                "User-Agent: {$this->userAgent}",
            ],
            CURLOPT_POSTFIELDS => json_encode($data, JSON_THROW_ON_ERROR),
        ]);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 201) {
            throw new RuntimeException("Fakturoid API chyba: HTTP {$httpCode} — {$response}");
        }

        return json_decode($response, true, 512, JSON_THROW_ON_ERROR);
    }

    public function markAsPaid(int $invoiceId): array
    {
        $ch = curl_init(self::BASE_URL . "/{$this->slug}/invoices/{$invoiceId}/fire.json");
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                "Authorization: Bearer {$this->accessToken}",
                'Content-Type: application/json',
                "User-Agent: {$this->userAgent}",
            ],
            CURLOPT_POSTFIELDS => json_encode(['event' => 'pay']),
        ]);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 200) {
            throw new RuntimeException("Nepodařilo se označit fakturu jako zaplacenou: HTTP {$httpCode}");
        }

        return json_decode($response, true, 512, JSON_THROW_ON_ERROR);
    }
}

// Použití
$client = new FakturoidClient('muj-ucet', $accessToken);

$invoice = $client->createInvoice([
    'subject_id' => 456,
    'due_date' => '2026-10-01',
    'currency' => 'CZK',
    'lines' => [
        [
            'name' => 'Konzultace — září 2026',
            'quantity' => 8,
            'unit_name' => 'hod',
            'unit_price' => 2000,
            'vat_rate' => 21,
        ],
    ],
]);

echo "Faktura č. {$invoice['number']} vytvořena.\n";

08Praktický příklad v Pythonu

import requests
from datetime import datetime, timedelta


class FakturoidClient:
    BASE_URL = "https://app.fakturoid.cz/api/v3"

    def __init__(self, slug: str, access_token: str):
        self.slug = slug
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json",
            "User-Agent": "MojeApp ([email protected])",
        })

    def list_invoices(self, page: int = 1, status: str = None) -> list:
        """Načte seznam faktur s paginací a volitelným filtrem stavu."""
        params = {"page": page}
        if status:
            params["status"] = status
        resp = self.session.get(
            f"{self.BASE_URL}/{self.slug}/invoices.json",
            params=params,
            timeout=30,
        )
        resp.raise_for_status()
        return resp.json()

    def create_invoice(self, subject_id: int, lines: list,
                       due_days: int = 14, currency: str = "CZK") -> dict:
        """Vytvoří novou fakturu se splatností X dní ode dneška."""
        due_date = (datetime.now() + timedelta(days=due_days)).strftime("%Y-%m-%d")
        data = {
            "subject_id": subject_id,
            "due_date": due_date,
            "currency": currency,
            "lines": lines,
        }
        resp = self.session.post(
            f"{self.BASE_URL}/{self.slug}/invoices.json",
            json=data,
            timeout=30,
        )
        resp.raise_for_status()
        return resp.json()


# Použití
client = FakturoidClient("muj-ucet", "VAS_ACCESS_TOKEN")

novy = client.create_invoice(
    subject_id=789,
    lines=[{
        "name": "SEO audit webu",
        "quantity": 1,
        "unit_price": 15000,
        "vat_rate": 21,
    }],
    due_days=30,
)
print(f"Vytvořena faktura: {novy['number']} splatná {novy['due_date']}")

09Webhooky a real-time notifikace

Webhooky vám umožní reagovat na události v Fakturoidu okamžitě, bez pollingu. Šetříte tak API limity a dosahujete nižší latence — při limitu 3 000 požadavků měsíčně je to rozdíl mezi fungující a přetíženou integrací.

Registrace webhooku

curl -X POST https://app.fakturoid.cz/api/v3/webhooks \
  -H "Authorization: Bearer VAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://vase-domena.cz/webhooks/fakturoid",
    "events": ["invoice.created", "invoice.paid", "invoice.overdue"]
  }'

Dostupné webhook události

Zpracování webhooku v PHP

<?php
// webhook-handler.php
$payload = json_decode(file_get_contents('php://input'), true);

switch ($payload['event'] ?? '') {
    case 'invoice.paid':
        $invoiceId = $payload['invoice_id'];
        markOrderAsPaid($invoiceId);        // označ objednávku v e-shopu
        sendPaymentConfirmation($invoiceId); // pošli potvrzení zákazníkovi
        break;

    case 'invoice.overdue':
        $invoiceId = $payload['invoice_id'];
        sendPaymentReminder($invoiceId);
        notifySlack("Faktura #{$invoiceId} je po splatnosti!");
        break;
}

http_response_code(200);
echo json_encode(['status' => 'ok']);

Zabezpečení webhooků

1. Omezení IP adres — povolte pouze IP adresy Fakturoidu
2. HTTPS — webhook URL musí používat HTTPS
3. Verifikace podpisu — pokud Fakturoid posílá signature header, vždy ho ověřujte
4. Idempotence — stejnou událost zpracujte jen jednou (kontrolujte event_id)

10Integrace s Make.com a n8n (bez kódu)

Make.com: Automatická fakturace z e-shopu

Vytvořte scénář, který při nové objednávce automaticky vystaví fakturu:

1. Trigger: Webhook z e-shopu (Shoptet, WooCommerce, vlastní)
2. Modul HTTP: POST na /api/v3/{slug}/invoices.json
   • Headers: Authorization: Bearer {token}
   • Body: JSON s fakturačními daty z triggeru
3. Modul Email/Slack: Notifikace o úspěchu
4. Error handler: Retry s exponenciálním backoffem

Tip V Make.com použijte Data Store pro uložení tokenu a naplánovaný refresh.

n8n: Self-hosted alternativa

n8n nabízí plnou kontrolu nad workflow a neomezené spuštění:

• Bez limitů na počet běhů (self-hosted)
• Data zůstávají u vás — vhodné pro GDPR citlivé scénáře
• Open-source — možnost vlastních úprav
• Cenově výhodnější pro velké objemy

V n8n použijte uzel HTTP Request s OAuth2 credential typem, který si sám řeší refresh tokenu. Pokročilejší variantou je n8n AI Agent node, který dokáže fakturaci kombinovat s dalšími kroky — například po zaplacení faktury rovnou aktualizovat CRM a rozeslat poděkování.

11Nejčastější chyby a troubleshooting

Chyba 401: Unauthorized

Příčina Expirovaný nebo neplatný access token.

Řešení:

• Zkontrolujte, zda token nevypršel (typická životnost 1 hodina)
• Použijte refresh_token pro získání nového access tokenu
• Ověřte formát hlavičky: Authorization: Bearer {token}

Chyba 422: Unprocessable Entity

Příčina Chybné nebo chybějící povinné parametry.

Řešení:

• Ověřte, že subject_id odkazuje na existující kontakt
• Formát data musí být YYYY-MM-DD
• Každá řádka faktury musí mít name a unit_price

Chyba 429: Too Many Requests

Příčina Překročen měsíční rate limit (Free = 1 500, Na každý den = 3 000, Na maximum = 20 000 požadavků).

Řešení:

• Sledujte hlavičku X-RateLimit-Remaining
• Implementujte caching pro často opakující se dotazy (např. Redis pro seznam kontaktů)
• Použijte webhooky místo pollingu
• Přechod na vyšší tarif nebo přikoupení balíčku dalších 10 000 požadavků (Na maximum)

Webhook nedorazí

Příčina Firewall blokuje příchozí spojení, neplatný SSL certifikát nebo chybná URL.

Řešení:

• Ověřte, že je endpoint dostupný z internetu
• Zkontrolujte platnost SSL certifikátu (Let's Encrypt stačí)
• Testujte endpoint manuálně pomocí curl
• Zkontrolujte logy webového serveru

12Bezpečnostní doporučení

1. Nikdy neukládejte tokeny v kódu — použijte environment variables nebo secrets manager (Vault, AWS Secrets Manager)
2. Implementujte PKCE pro mobilní a SPA aplikace
3. Minimální scope — pokud nepotřebujete zapisovat, požadujte jen read
4. Rotace refresh tokenů — při každém refreshi uložte nový token
5. Audit log — zaznamenávejte všechna API volání pro debugging a compliance

13FAQ: Nejčastější otázky k Fakturoid API (2026)

14Závěr a doporučený postup

Fakturoid API v3 je v roce 2026 robustní a stabilní základ pro automatizaci fakturace v českém prostředí — a s oficiálním MCP serverem je napojení na AI agenty záležitost minut, ne týdnů. Klíčem k úspěšné integraci je správná implementace OAuth 2.0, respektování rate limitů a využití webhooků pro real-time reakce.

Doporučený postup pro začátek:

1. Zaregistrujte OAuth aplikaci ve Fakturoidu
2. Implementujte autentizaci (Authorization Code flow s refresh logikou)
3. Začněte s jednoduchým CRUD — čtení faktur a vytvoření jedné zkušební
4. Přidejte webhooky pro sledování plateb
5. Rozšiřte o Make.com, n8n nebo MCP server pro komplexní workflow napříč nástroji

Díky správné integraci s Fakturoid API ušetříte desítky hodin ruční práce měsíčně a minimalizujete riziko chyb v účetnictví.

15Související návody a nástroje

• Pokud zvažujete přechod, projděte si srovnání Fakturoid alternativ včetně cen a funkcí.
• Pro obchodní týmy dává smysl propojit fakturaci také s Raynet CRM — napojení přes API je podobně jednoduché.
• Automatizaci fakturace můžete začlenit do širšího workflow popsaného v návodu na AI pro e-shopy.

AI nástroje pro účetní s ověřenými cenami: průvodce AI pro účetní.