---
name: centrum-finansowe
description: Obsługa faktur, KSeF, kosztów, kontrahentów i ustawień firm w Centrum Finansowe AI Agent HUB (ksiegowosc.aiagenthub.pl) w imieniu zalogowanego użytkownika, przez serwer MCP albo REST. Użyj, gdy użytkownik prosi o wystawienie faktury, wysyłkę do KSeF, zaksięgowanie kosztu, sprawdzenie należności albo zmianę konfiguracji firmy w tym panelu.
---

# Centrum Finansowe AI Agent HUB — instrukcja dla agentów

Panel do faktur, KSeF i finansów firm (operator: AI AGENT HUB P.S.A.). Agent działa w imieniu
użytkownika i ma jego uprawnienia: czyta dane i wprowadza zmiany w firmach z jego konta.

## Połączenie

- **MCP (Streamable HTTP):** `https://ksiegowosc.aiagenthub.pl/mcp` — klient sam przeprowadzi logowanie OAuth 2.1
  (PKCE, dynamiczna rejestracja). Claude: Ustawienia → Konektory → Dodaj własny konektor → ten adres.
- **Klucz API (bez przeglądarki, np. Hermes na serwerze):** użytkownik tworzy go w panelu
  (https://ksiegowosc.aiagenthub.pl/dashboard/agents) i wybiera firmy oraz zakres. Nagłówek `Authorization: Bearer cfa_…`.
- **Rejestracja agenta (auth.md):** https://ksiegowosc.aiagenthub.pl/auth.md — agent podaje e-mail właściciela konta,
  właściciel potwierdza kodem w panelu.
- **REST:** `POST https://ksiegowosc.aiagenthub.pl/api/v1/tools/{nazwa}` z argumentami w JSON; opis: https://ksiegowosc.aiagenthub.pl/openapi.json.

## Wiele firm na jednym koncie

Jedno konto może prowadzić wiele firm (np. biuro rachunkowe). Zacznij od `list_companies`
i przekazuj `company_id` do każdego narzędzia działającego na danych firmy. Gdy użytkownik nie wskazał
firmy, a jest ich kilka, zapytaj, której dotyczy polecenie. Klucz API może być ograniczony do wybranych
firm — narzędzia zwrócą wtedy listę dostępnych.

## Typowe zadania

1. **Faktura sprzedaży:** `list_counterparties` (albo `lookup_company_by_nip` → `create_counterparty`)
   → `preview_invoice` → pokaż użytkownikowi nabywcę, pozycje i kwoty → `create_sales_invoice`
   → po zgodzie `send_to_ksef` → `get_ksef_status`.
2. **Faktura kosztowa ze skanu:** `upload_document` (base64) → przy uwagach pokaż je i popraw
   `update_document` → po zgodzie `post_document`.
3. **Należności i VAT:** `get_dashboard_summary`, `list_documents` z `payment_status: unpaid`.
4. **Konfiguracja nowej firmy:** `create_company` → `update_company` (profil podatkowy,
   `confirm_tax_profile`) → `connect_systim` → `connect_ksef`.

## Zasady

- Kwoty w złotych (np. 1234.56), daty RRRR-MM-DD.
- Narzędzia z `destructiveHint` (wysyłka do KSeF, wycofanie z ksiąg, usunięcie firmy, odłączenie KSeF)
  wywołuj dopiero po wyraźnej zgodzie użytkownika, pokazując wcześniej, czego dotyczą.
  Faktura przyjęta przez KSeF jest wystawiona prawnie — zmienia ją tylko korekta (`correct_invoice`).
- Księgowanie zapisuje dokument w programie księgowym klienta (Systim).
- Hasła API i tokeny KSeF podaje użytkownik; serwer je szyfruje i nigdy nie zwraca.
- Panel nie zastępuje księgowego. Nie przedstawiaj interpretacji podatkowych jako pewnika.
- Limit: 120 wywołań na minutę na konto.

## Narzędzia (56)

### Konto i firmy

- `list_companies` — Lista firm na koncie
- `get_company` — Ustawienia firmy
- `update_company` — Zmień ustawienia firmy (zmienia dane)
- `create_company` — Dodaj firmę (zmienia dane)
- `delete_company` — Usuń firmę (nieodwracalne — tylko po zgodzie)
- `lookup_company_by_nip` — Sprawdź NIP w rejestrach
- `check_vat_registry` — Sprawdź firmę w Białej Liście VAT (zmienia dane)
- `get_dashboard_summary` — Podsumowanie finansów firmy
- `get_profile` — Profil konta
- `update_profile` — Zmień profil konta (zmienia dane)

### Dokumenty

- `list_documents` — Lista dokumentów
- `get_document` — Szczegóły dokumentu
- `get_document_pdf` — PDF dokumentu
- `upload_document` — Wgraj fakturę kosztową (OCR) (zmienia dane)
- `update_document` — Popraw dane dokumentu (zmienia dane)
- `void_document` — Anuluj niezaksięgowany dokument (nieodwracalne — tylko po zgodzie)
- `refresh_document` — Odśwież dokument z programu księgowego (zmienia dane)
- `import_from_systim` — Importuj dokumenty z Systim (zmienia dane)

### Faktury i księgowanie

- `preview_invoice` — Sprawdź fakturę przed wystawieniem
- `create_sales_invoice` — Wystaw fakturę sprzedaży (zmienia dane)
- `create_purchase_invoice` — Zaewidencjonuj fakturę kosztową (zmienia dane)
- `post_document` — Zaksięguj dokument (zmienia dane)
- `unpost_document` — Wycofaj dokument z księgowości (nieodwracalne — tylko po zgodzie)
- `register_payment` — Zarejestruj płatność (zmienia dane)
- `check_invoice_edit` — Czy fakturę można edytować
- `edit_invoice` — Edytuj zaksięgowaną fakturę sprzedaży (zmienia dane)
- `correct_invoice` — Wystaw fakturę korygującą (zmienia dane)

### KSeF

- `send_to_ksef` — Wyślij fakturę do KSeF (nieodwracalne — tylko po zgodzie)
- `get_ksef_status` — Status faktury w KSeF (zmienia dane)
- `import_from_ksef` — Pobierz faktury z KSeF (zmienia dane)
- `list_ksef_register` — Rejestr KSeF firmy
- `get_ksef_invoice` — Faktura z KSeF: XML, PDF i UPO
- `get_sync_status` — Stan pobierania i zgodności źródeł
- `list_sync_conflicts` — Konflikty importu KSeF
- `resolve_sync_conflict` — Zamknij konflikt importu (zmienia dane)

### Księgi w Systim

- `systim_accounting_setup` — Forma księgowości w Systim
- `systim_list_invoices` — Rejestr faktur w Systim
- `systim_list_ledger` — Księga w Systim: dziennik, KPiR, ryczałt
- `systim_list_payments` — Płatności w Systim
- `systim_get_record` — Rekord z Systim
- `systim_export_report` — Raport z Systim: JPK_KR, bilans, RZiS

### Uzgodnienie i naprawy

- `reconcile_sources` — Uzgodnij KSeF, panel, Systim i księgę
- `propose_change` — Zaproponuj zmianę (plan do zatwierdzenia)
- `apply_change` — Wykonaj zatwierdzony plan zmiany (zmienia dane)
- `list_change_plans` — Plany zmian i ich wyniki

### Kontrahenci

- `list_counterparties` — Kontrahenci
- `create_counterparty` — Dodaj kontrahenta (zmienia dane)
- `update_counterparty` — Zmień kontrahenta (zmienia dane)
- `delete_counterparty` — Usuń kontrahenta (nieodwracalne — tylko po zgodzie)

### Integracje

- `get_integrations` — Stan integracji
- `connect_systim` — Podłącz program księgowy Systim (zmienia dane)
- `connect_ksef` — Podłącz KSeF (zmienia dane)
- `manage_ksef` — Zarządzaj integracją KSeF (nieodwracalne — tylko po zgodzie)

### Abonament

- `get_subscription` — Abonament i zużycie
- `list_billing_invoices` — Faktury za abonament
- `get_billing_link` — Link do płatności lub zmiany planu (zmienia dane)

## English summary

Centrum Finansowe AI Agent HUB is a Polish invoicing and finance panel (KSeF e-invoices, purchase invoices with OCR,
counterparties, payments, accounting export to Systim). Connect to `https://ksiegowosc.aiagenthub.pl/mcp` with OAuth 2.1
or a panel API key. One account can manage many companies — call `list_companies` first and pass
`company_id`. Ask the user before irreversible actions (KSeF submission, unposting, deleting a company).
