Průvodci

Faktury

Agent umí přečíst vydanou fakturu z připojeného Fakturoidu nebo ABRA Flexi a použít ji jako podklad pro upomínkový hovor - nikdy fakturu nevystaví ani neoznačí za zaplacenou.

Co to umí a neumí

• Vyhledá vydané faktury podle čísla nebo názvu firmy (list_invoices).
• Načte čerstvý stav jedné faktury přímo od poskytovatele (get_invoice).
• Založí upomínkový Úkol (taskType: "invoice"), který na fakturu odkazuje.

Neumí

• Nevystaví, needituje ani nesmaže žádnou fakturu.
• Neoznačí fakturu za zaplacenou - to umí jen Fakturoid nebo ABRA samy.
• Nepřipojí Fakturoid přihlašovacími údaji - jde jen přes OAuth v prohlížeči.

Připojení účtu

Obojí se připojuje na stejném místě jako kalendáře - v portálu v sekci Připojení (/propojeni), nebo přes list_integrations/GET /v1/integrations. Podrobný postup pro agenta (list_integrations -> connectUrl -> krok v prohlížeči) je na stránce Připojení.

Fakturoid

Připojuje se výhradně OAuth přihlášením v prohlížeči - POST /v1/integrations s provider: "fakturoid" REST odmítne chybou integration_unsupported, přihlašovací údaje se sem posílat nedají. Když má účet víc firem s fakturací, prohlížeč se po přihlášení vrátí zpátky na stránku Připojení ve volai (/propojeni, případně /en/connections) a tam se teprve ukáže výběr firmy - záznam v integrations vznikne až po té volbě. ready u fakturoid v GET /v1/integrations hlásí jen to, že má volai nastavené OAuth přihlašovací údaje k Fakturoidu (FAKTUROID_CLIENT_ID a spol.) - NE že je konkrétní účet už připojený. Jestli je připojení hotové, pozná agent podle toho, že se objeví v poli integrations.

ABRA Flexi

Připojuje se přihlašovacími údaji, stejně jako Apple Calendar: POST /v1/integrations s {provider: "abra-flexi", baseUrl, company, username, password}. Adresa serveru (baseUrl) musí sedět na přesnou adresu, kterou provozovatel předem povolil (ABRA_FLEXI_ALLOWED_HOSTS) - jiná vrátí chybu.

Čtení faktur

Dvoukrokový postup: nejdřív vyhledání, pak čerstvý detail té jedné faktury, která tě zajímá.

• list_invoices({integrationId, search?}) - search (do 100 znaků) hledá u poskytovatele podle čísla dokladu nebo názvu firmy; vrátí prvních 40 řádků u Fakturoidu nebo 50 u ABRA, bez stránkování. Když je výsledků moc, zpřesni search.
• get_invoice({integrationId, invoiceId}) - invoiceId je opakovaný externalId z list_invoices. Vrací nejčerstvější stav přímo od poskytovatele, ne to, co si pamatuje volai.

REST ekvivalenty: GET /v1/integrations/{id}/invoices?search=... a GET /v1/integrations/{id}/invoices/{invoiceId}.

status je paid, unpaid, overdue nebo unknown; amountDueMinor je celé číslo v nejmenších jednotkách MĚNY DOKLADU (ne nutně CZK) a null znamená nezjištěný zůstatek. Detail navíc nese provider, fetchedAt a evidence: "provider_response".

Upomínka přes Úkoly

Hromadné upomínkové volání o nezaplacených fakturách jde přes Úkoly.

Úkol typu taskType: "invoice" se založí se source: "integration" a každý příjemce (nebo celý úkol, když je faktura pro všechny stejná) nese externalRefs.invoice = {connectionId, externalId, provider?} - connectionId je id připojení z list_integrations, externalId id faktury z list_invoices. Bez týhle reference create_task/POST /v1/tasks selže chybou validation se zprávou recipients.externalRefs a start_task úkol odmítne spustit stejnou chybou; issues s podrobnostmi vrátí až get_task/GET /v1/tasks/{id} u úkolu, který se přesto podařilo založit.

Každý příjemce navíc nese pole paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - jen ke čtení, systém ho odvodí z posledního čtení faktury u poskytovatele těsně před vytáčením. Bez reference na fakturu je not_applicable, po založení nebo když stav či částku nejde ověřit je unknown, jinak podle odpovědi Fakturoidu/ABRA - zaplacenou fakturu úkol položku přeskočí (skipped) a nastaví paid. Hodnotu disputed dnes sám systém nenastavuje, jen ji umí zobrazit portál - je součástí veřejného výčtu (TaskItem v /openapi.json) pro budoucí ruční označení sporné faktury.

Chyby

• integration_not_found - Připojení s tímhle integrationId neexistuje nebo nepatří tomuhle účtu.
• integration_unsupported - Připojení není fakturační (například kalendář), nebo jde o pokus připojit Fakturoid přihlašovacími údaji místo OAuth.
• integration_unauthorized - Fakturoid nebo ABRA přístup odvolaly - připojení je potřeba udělat v portálu znovu.
• integration_provider_error - Poskytovatel momentálně neodpovídá nebo vrátil chybu - zkus to později, stav faktury mezitím ber jako neznámý.
• integration_invalid_query - ABRA odmítla search s obrácenými lomítky nebo míchanými uvozovkami - zjednoduš dotaz.

Úplnou tabulku se všemi kódy najdeš v sekci faktury v REST API referenci a v chybách MCP.

Zabezpečení

Přístupové tokeny ani hesla k Fakturoidu ani ABRA Flexi REST API ani MCP nikdy nevrací a ukládáme je šifrovaně. Odpojení integrace jde jen v portálu nebo přes REST (DELETE /v1/integrations/{id}) - MCP na to nemá nástroj schválně, je to nevratné.