Fakturoid Connector

Fakturoid Connector

Faktura vám řekne, co se stalo. Tenhle connector vám řekne, co s tím.

Open-source CLI, MCP server a Discord notifikace pro Fakturoid.cz. Ptáte se AI asistenta na faktury, generujete platební příkazy, dostáváte denní připomínky splatností. Bez otevírání prohlížeče.

*"Kolik nám dluží klient X?" / "Vygeneruj platební příkaz na splatné faktury." / "Jaké faktury jsou po splatnosti?"* Ptáte se přirozeně, Claude sahá přímo do Fakturoid.

Proč to existuje

Fakturoid je skvělý na fakturaci. Ale zjistit, kdo zaplatil, co je po splatnosti a co ještě musí odejít, to je pořád proklikávání webového rozhraní.

Tenhle connector z Fakturoid udělá něco, s čím se dá mluvit. Přes Claude Code (MCP server) nebo terminál (CLI) máte přímý přístup k fakturám, nákladům, kontaktům, reportům a platebním souborům.

V kombinaci s Fio Connectorem pro bankovní data dostanete kompletní obraz: co bylo fakturováno, co bylo zaplaceno, co je ještě otevřené.

Co umí

Začínáme

1. Instalace

pip install git+https://github.com/Continero/fakturoid-connector.git

Nebo klonovat a nainstalovat v editovatelném režimu:

git clone https://github.com/Continero/fakturoid-connector.git
cd fakturoid-connector
python -m venv .venv
source .venv/bin/activate
pip install -e .

2. Konfigurace

cp .env.example .env

Vyplňte přístupové údaje k Fakturoid API:

FAKTUROID_CLIENT_ID=your_client_id
FAKTUROID_CLIENT_SECRET=your_client_secret
FAKTUROID_SLUG=your_account_slug

Kde je najdete:

1. Přihlaste se na app.fakturoid.cz
2. Nastavení -> Uživatelský účet -> API
3. Vytvořte novou aplikaci, dostanete Client ID a Client Secret
4. Slug je subdoména ve vašem Fakturoid URL: app.fakturoid.cz/api/v3/accounts/{slug}/...

3. Použití

fakturoid summary              # přehled účtu
fakturoid invoices --overdue   # co je po splatnosti
fakturoid search "Acme"        # hledání faktur

CLI příkazy

Faktury

fakturoid invoices                    # všechny faktury
fakturoid invoices --overdue          # po splatnosti
fakturoid invoices --unpaid           # nezaplacené
fakturoid invoices --status paid      # filtr podle statusu

fakturoid search "dotaz"              # fulltextové hledání
fakturoid invoice 12345               # detail faktury (JSON)

Kontakty

fakturoid contacts                    # seznam kontaktů

Reporty

fakturoid report monthly              # aktuální měsíc
fakturoid report monthly --year 2025 --month 12
fakturoid report yearly               # aktuální rok
fakturoid report yearly --year 2025

Výstupem jsou markdown tabulky s počty faktur, obratem a rozpisem zaplacených/nezaplacených.

Export

fakturoid export --format json -o ./output
fakturoid export --format csv -o ./output
fakturoid export-pdf 12345 -o ./output    # stažení PDF faktury

Účet

fakturoid summary    # tarif, počet faktur, nezaplacené, po splatnosti, částky

ABO platební příkazy

Generuje platební soubory ve formátu ABO z nezaplacených nákladů ve Fakturoid. Soubor .abo nahrajete do internetového bankovnictví a zaplatíte hromadně.

fakturoid abo                         # náklady splatné dnes
fakturoid abo --due-date 2026-03-28   # náklady splatné do data
fakturoid abo -o ~/Downloads          # vlastní výstupní adresář

Vyžaduje tři další proměnné v .env:

FAKTUROID_SENDER_ACCOUNT=000000-1234567890/0100   # váš bankovní účet
FAKTUROID_SENDER_NAME=Nazev Firmy s.r.o.
FAKTUROID_SENDER_ICO=12345678

Generovaný ABO soubor odpovídá specifikaci českého bankovního formátu (3-2267a). Funguje s Fio, KB, ČSOB, Raiffeisen a dalšími bankami.

Discord notifikace

fakturoid check-due

Pošle strukturovanou zprávu na Discord se třemi sekcemi:

• FAKTURY -- pohledávky (co mají klienti zaplatit vám): po splatnosti, splatné dnes, splatné do 3 dnů
• NÁKLADY -- závazky (co musíte zaplatit vy): po splatnosti, splatné dnes, splatné do 3 dnů
• INKASO -- strhne se samo (náklady s tagem inkaso ve Fakturoid): po splatnosti, splatné dnes, splatné do 3 dnů

Každá sekce ukazuje součty po měnách. Náklady označené tagem inkaso se automaticky oddělí, takže hned vidíte, co vyžaduje ruční akci.

Pro zapnutí nastavte DISCORD_WEBHOOK_URL v .env:

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

Cron

Kontrola splatností každé ráno v 8:00:

0 8 * * * cd /path/to/fakturoid-connector && .venv/bin/fakturoid check-due

MCP Server (napojení na AI)

MCP server zpřístupňuje data z Fakturoid jako nástroje pro Claude Code a další MCP-kompatibilní AI asistenty.

Nastavení

Přidejte do .mcp.json nebo do konfigurace Claude Code:

{
  "mcpServers": {
    "fakturoid": {
      "command": "/path/to/fakturoid-connector/.venv/bin/python",
      "args": ["-m", "fakturoid_connector.mcp_server"],
      "cwd": "/path/to/fakturoid-connector"
    }
  }
}

Dostupné nástroje

Příklady dotazů

Po připojení se ptáte běžnou řečí:

• *"Jaké faktury jsou po splatnosti?"*
• *"Kolik nám dluží Acme Corp?"*
• *"Ukaž nezaplacené faktury nad 50 000 Kč"*
• *"Vystav fakturu pro klienta 42 -- konzultace, 10 hodin po 2 000 Kč"*
• *"Stáhni PDF faktury FV-2025-042"*
• *"Vygeneruj ABO platební soubor pro náklady splatné tento pátek"*
• *"Kolik máme celkem nesplacených pohledávek?"*

Konfigurace

Veškerá konfigurace je přes proměnné prostředí (soubor .env):

Pokrytí API

Postaveno na Fakturoid API v3:

Všechny seznamové endpointy automaticky stránkují (40 položek na stránku), takže dostanete kompletní data.

Zatím neimplementováno

Pull requesty vítány:

• Platby faktur, zprávy k fakturám, platby nákladů
• Generátory a opakované generátory (šablony)
• Události (audit log), úkoly, uživatelé
• Bankovní účty, číselné řady
• Skladové položky a pohyby
• Příchozí soubory, webhooky

Struktura projektu

fakturoid-connector/
├── src/fakturoid_connector/
│   ├── client.py           # Fakturoid API v3 klient (OAuth 2, auto-stránkování)
│   ├── cli.py              # Click CLI (faktury, kontakty, reporty, ABO, check-due)
│   ├── mcp_server.py       # MCP server s 11 nástroji pro AI asistenty
│   ├── notifications.py    # Discord webhook -- upozornění na splatnosti
│   ├── reports.py          # Generování měsíčních/ročních reportů
│   └── abo.py              # Generátor ABO platebních souborů
├── tests/
│   ├── test_client.py
│   ├── test_cli.py
│   ├── test_notifications.py
│   ├── test_reports.py
│   └── test_abo.py
├── pyproject.toml
├── .env.example
└── README.md

Vývoj

git clone https://github.com/Continero/fakturoid-connector.git
cd fakturoid-connector
python -m venv .venv
source .venv/bin/activate
pip install -e .
pip install pytest

Spuštění testů:

python -m pytest tests/ -v

Testy používají mockované API odpovědi, pro vývoj nepotřebujete Fakturoid účet.

Související projekty

• Fio Connector -- CLI + MCP server pro Fio banku (transakce, kategorie, reporty, platební příkazy)
• Fakturoid.cz -- česká fakturační platforma
• Fakturoid API v3 dokumentace
• Claude Code -- AI asistent s podporou MCP
• MCP specifikace

Licence

MIT -- viz LICENSE.