Fakturoid API v3 (2026): Kompletní 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 červenci 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.

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 a n8n. Vše je aktualizováno pro rok 2026, včetně aktuálních tarifů a limitů API.

Proč 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 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í.

Základní informace o API v3 (k červenci 2026)

Aktuální tarify Fakturoidu (2026)

Používání API je podmíněno vaším tariffem. Od února 2025 Fakturoid přešel na novou strukturu tarifů, takže staré názvy (Basic, Plus, Premium) už neplatí:

Pro nové podnikatele (IČO méně než 12 měsíců) je k dispozici sleva 50 % na první roční fakturu. Přesné limity API pro jednotlivé tarify ověřte v oficiálním ceníku a v dokumentaci rate-limitingu.

OAuth 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.

Krok 1: Registrace OAuth aplikace

1. Přihlaste se do svého Fakturoid účtu
2. Přejděte do Nastavení → Connect other apps → OAuth 2 for app developers
3. Klikněte na Vytvořit novou aplikaci
4. Vyplňte název aplikace a redirect_uri (např. https://vase-domena.cz/callback)
5. Uložte si Client ID a Client Secret — nikdy je nepoužívejte v klientském kódu

Krok 2: Získání autorizačního kódu

Přesměrujte uživatele na autorizační endpoint:

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

Po souhlasu vás Fakturoid přesměruje zpět na redirect_uri s parametrem code.

Krok 3: Výměna kódu za token

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"
  }'

Odpověď obsahuje access_token (životnost typicky 1 hodina) a refresh_token.

Krok 4: Automatický refresh tokenu

Token je třeba pravidelně obnovovat. Implementujte automatický refresh:

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"
  }'

Důležité: Vždy uložte nový refresh_token z odpovědi — starý přestane platit.

Klíč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-08-15",
  "currency": "CZK",
  "payment_method": "bank",
  "lines": [
    {
      "name": "Webový vývoj — červenec 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.

Praktický 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 (info@example.cz)'
    ) {}

    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-09-01',
    'currency' => 'CZK',
    'lines' => [
        [
            'name' => 'Konzultace — srpen 2026',
            'quantity' => 8,
            'unit_name' => 'hod',
            'unit_price' => 2000,
            'vat_rate' => 21,
        ],
    ],
]);

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

Praktický 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 (info@example.cz)",
        })

    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 s splatností X dní od dnes.\"\"\"
        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']}")

Webhooky 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.

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 ( kontrolojte event_id)

Integrace 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 citivé 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.

Nejč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 požadavků).

Řešení:

• Sledujte hlavičku X-RateLimit-Remaining
• Implementujte caching pro často opakující se dotazy
• Použijte webhooky místo pollingu
• Přechod na vyšší tarif pro vyšší limity

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

Bezpeč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

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

Je Fakturoid API stále ve verzi v3?

Ano, v červenci 2026 je v3 nejnovější verzí. Verze v4 nebyla vydána. Endpointy, OAuth 2.0 flow a datové struktury zůstávají stabilní, takže integrace napsané v předchozích letech nadále fungují.

Kolik API požadavků mám k dispozici?

Na Free tarifu je to 1 500 požadavků měsíčně. Placené tarify (Na lehko, Na každý den, Na maximum) nabízejí vyšší limity — přesné hodnoty najdete v ceníku a v dokumentaci. Stav sledujte přes hlavičku X-RateLim