Fakturoid API v3: Kompletní průvodce integrací a automatizací

Fakturoid je druhý největší SaaS fakturační software v České republice s více než 30 000 aktivními uživateli. API v3, vydané v dubnu 2024, přináší moderní OAuth 2.0 autentizaci, vylepšené webhooky a nové možnosti automatizace. V tomto průvodci vám ukážeme, jak Fakturoid API v3 integrovat do vašeho systému — od základního nastavení až po pokročilé scénáře.

Proč používat Fakturoid API v3?

Ruční fakturace je časově náročná a náchylná k chybám. S Fakturoid API můžete:

• Automaticky vystavovat faktury při nové objednávce z e-shopu
• Synchronizovat kontakty mezi CRM a Fakturodem
• Sledovat platby v reálném čase díky webhookům
• Generovat reporty pro účetnictví bez manuální práce
• Propojit fakturaci s dalšími nástroji jako Make.com či n8n

Přechod z API v2 na v3 přináší hlavně bezpečnější autentizaci přes OAuth 2.0 (místo API klíče) a stabilnější webhook systém.

Základní informace o API

OAuth2 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 získání přístupového 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 — budete je potřebovat

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 uživatele Fakturoid přesměruje zpět na vaši 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 a refresh_token. Access token vyprší typicky za hodinu.

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ý už nebude fungovat.

Klíčové endpointy a CRUD operace

Faktury (Invoices)

Základní operace s fakturami:

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-02-15",
  "currency": "CZK",
  "payment_method": "bank",
  "lines": [
    {
      "name": "Webový vývoj - leden 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 (Events)

GET    /api/v3/{slug}/invoices/{id}/events.json   # Události faktury

Události zahrnují: vytvoření, odeslání, zaplacení, upomínka a další.

Praktické příklady v PHP

PHP: Vytvoření faktury

<?php
function createInvoice(string $token, string $slug, array $data): array
{
    $ch = curl_init("https://app.fakturoid.cz/api/v3/{$slug}/invoices.json");

    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer {$token}",
            "Content-Type: application/json",
            "User-Agent: MojeApp ([email protected])"
        ],
        CURLOPT_POSTFIELDS => json_encode($data)
    ]);

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

    if ($httpCode !== 201) {
        throw new RuntimeException("Chyba při vytváření faktury: HTTP {$httpCode}");
    }

    return json_decode($response, true);
}

// Použití
$invoiceData = [
    'subject_id' => 456,
    'due_date' => '2026-03-01',
    'lines' => [
        [
            'name' => 'Konzultace - březen 2026',
            'quantity' => 8,
            'unit_name' => 'hod',
            'unit_price' => 2000,
            'vat_rate' => 21
        ]
    ]
];

$invoice = createInvoice($accessToken, 'muj-ucet', $invoiceData);
echo "Faktura #{$invoice['number']} vytvořena.\n";

PHP: Automatický token refresh s uložením

<?php
function refreshAccessToken(string $refreshToken, string $clientId, string $clientSecret): array
{
    $ch = curl_init('https://app.fakturoid.cz/api/v3/oauth/token');

    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'grant_type' => 'refresh_token',
            'refresh_token' => $refreshToken,
            'client_id' => $clientId,
            'client_secret' => $clientSecret
        ])
    ]);

    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);

    // Uložení nových tokenů do souboru
    file_put_contents('tokens.json', json_encode($response));

    return $response;
}

Praktické příklady v Pythonu

Python: Kompletní třída pro Fakturoid API

import requests
from datetime import datetime

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) -> list:
        \"\"\"Načte seznam faktur s paginací.\"\"\"
        resp = self.session.get(
            f"{self.BASE_URL}/{self.slug}/invoices.json",
            params={"page": page}
        )
        resp.raise_for_status()
        return resp.json()

    def create_invoice(self, subject_id: int, lines: list,
                       due_date: str = None, currency: str = "CZK") -> dict:
        \"\"\"Vytvoří novou fakturu.\"\"\"
        if due_date is None:
            due_date = datetime.now().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
        )
        resp.raise_for_status()
        return resp.json()

    def get_invoice(self, invoice_id: int) -> dict:
        \"\"\"Načte detail faktury.\"\"\"
        resp = self.session.get(
            f"{self.BASE_URL}/{self.slug}/invoices/{invoice_id}.json"
        )
        resp.raise_for_status()
        return resp.json()

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

new_invoice = client.create_invoice(
    subject_id=789,
    lines=[{
        "name": "SEO audit webu",
        "quantity": 1,
        "unit_price": 15000,
        "vat_rate": 21
    }],
    due_date="2026-04-15"
)
print(f"Vytvořena faktura: {new_invoice['number']}")

Python: Webhook handler s Flask

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/fakturoid', methods=['POST'])
def handle_webhook():
    payload = request.json
    event = payload.get('event')

    if event == 'invoice.paid':
        invoice_id = payload['invoice_id']
        # Zpracování zaplacené faktury
        process_paid_invoice(invoice_id)

    elif event == 'invoice.overdue':
        invoice_id = payload['invoice_id']
        # Odeslání upomínky
        send_reminder(invoice_id)

    return jsonify({'status': 'ok'}), 200

Webhooky a real-time notifikace

Webhooky vám umožní reagovat na události v Fakturoidu okamžitě, bez nutnosti pravidelného dotazování (pollingu).

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'];
        // Označit objednávku jako zaplacenou v e-shopu
        markOrderAsPaid($invoiceId);
        // Poslat potvrzení zákazníkovi
        sendPaymentConfirmation($invoiceId);
        break;

    case 'invoice.overdue':
        $invoiceId = $payload['invoice_id'];
        // Odeslat upomínku
        sendPaymentReminder($invoiceId);
        // Notifikovat obchodní oddělení přes Slack
        notifySlack("Faktura #{$invoiceId} je po splatnosti!");
        break;
}

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

Zabezpečení webhooků

Vždy ověřujte, že webhook skutečně pochází z Fakturoidu:

1. Omezení IP adres — povolte pouze IP adresy Fakturoidu
2. HTTPS — webhook URL musí používat HTTPS
3. Verifikace podpisu — pokud Fakturoid podporuje signature header, ověřujte ho

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ěřujte, že posíláte token ve správném formátu: Authorization: Bearer {token}

Chyba 422: Unprocessable Entity

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

Řešení:

• Zkontrolujte, že subject_id odkazuje na existující kontakt
• Ověřujte formát data (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 3 000 požadavků.

Řešení:

• Implementujte caching pro často opakující se dotazy
• Použijte webhooky místo pollingu
• Hromadné operace rozložte v čase
• Sledujte header X-RateLimit-Remaining

Webhook nedorazí

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

Řešení:

• Ověřte, že váš endpoint je dostupný z internetu
• Zkontrolujte platnost SSL certifikátu
• Testujte endpoint manuálně pomocí curl
• Zkontrolujte logy webového serveru

Chyba při token refresh

Příčina: Použití starého refresh tokenu.

Řešení:

• Vždy ukládejte nový refresh token z odpovědi
• Implementujte retry logiku s exponenciálním backoff
• Pokud refresh selže opakovaně, je nutná nová autorizace

Integrace s Make.com a n8n bez kódu

Make.com: Automatická fakturace z e-shopu

Vytvořte scénář, který automaticky vystavuje faktury:

1. Trigger: Webhook z vašeho e-shopu (nová objednávka)
2. Modul HTTP: POST na Fakturoid API pro vytvoření faktury
   • URL: https://app.fakturoid.cz/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ěšném vytvoření
4. Error handler: Retry s notifikací při selhání

Tip: Použijte Make.com Data Store pro uložení tokenu a automatický refresh.

n8n: Self-hosted alternativa

n8n nabízí plnou kontrolu nad workflow:

// n8n HTTP Request node konfigurace
{
  "method": "POST",
  "url": "https://app.fakturoid.cz/api/v3/{{$node.Config.slug}}/invoices.json",
  "authentication": "genericCredentialType",
  "genericAuthType": "oAuth2Api",
  "options": {
    "timeout": 10000
  }
}

Výhody n8n oproti Make.com:

• Bez limitů na počet spuštění
• Self-hosted — data zůstávají u vás
• Open-source — možnost vlastních úprav
• Cenově výhodnější pro velké objemy

Bezpečnostní doporučení

1. Nikdy neukládejte tokeny v kódu — použijte environment variables nebo secrets manager
2. Implementujte PKCE pro mobilní a SPA aplikace
3. Minimální scope — zadejte pouze read pokud nepotřebujete zapisovat
4. Rotace tokenů — pravidelně obnovujte refresh tokeny
5. Audit log — zaznamenávejte všechna API volání pro debugging

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

Kolik stojí používání Fakturoid API?

API je součástí vašeho Fakturoid tarifu bez příplatku. V ceně je 3 000 API požadavků měsíčně. Pro vyšší objemy kontaktujte podporu Fakturoidu.

Mohu používat API v3 s bezplatným účtem?

Ano, API je dostupné i na bezplatném tarifu, ale s omezeným počtem faktur (5 měsíčně). Pro seriózní automatizaci doporučujeme placený tarif.

Jak migruji z API v2 na v3?

Hlavní změna je přechod z API klíče na OAuth 2.0. Endpointy a datové struktury zůstávají z velké části kompatibilní. Doporučujeme:

1. Zaregistrovat OAuth aplikaci
2. Implementovat OAuth flow
3. Postupně přepnout endpointy na v3 URL
4. Otestovat na sandbox účtu

Je možné testovat API bez ovlivnění ostrých dat?

Fakturoid nabízí testovací účty. Vytvořte si nový účet s označením "test" a použijte ho pro vývoj a testování. Všechny operace na testovacím účtu jsou oddělené od produkce.

Jak zjistím, že se blížím rate limitu?

Sledujte response header X-RateLimit-Remaining. Nastavte si alert, když hodnota klesne pod 500 požadavků. Implementujte caching a snižte frekvenci pollingu.

Závěr a další kroky

Fakturoid API v3 je robustní nástroj pro automatizaci fakturace v českém prostředí. Klíčem k úspěšné integraci je správná implementace OAuth 2.0, respektování rate limitů a využití webhooků pro real-time notifikace.

Doporučený postup pro začátek:

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

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

Související návody a nástroje

• Pokud hledáte Fakturoid alternativu, projděte si přehled funkcí, ceny a slabá místa.
• Pro obchodní týmy dává smysl propojit fakturaci také s Raynet CRM a jeho ceníkem.
• Automatizaci fakturace můžete napojit na širší workflow v článku automatizace e-shopu.