Sprievodcovia

Faktúry

Agent vie prečítať vystavenú faktúru z pripojeného Fakturoidu alebo ABRA Flexi a použiť ju ako podklad pre upomienkový hovor - nikdy faktúru nevystaví ani neoznačí za zaplatenú.

Čo to vie a nevie

• Vyhľadá vystavené faktúry podľa čísla alebo názvu firmy (list_invoices).
• Načíta čerstvý stav jednej faktúry priamo od poskytovateľa (get_invoice).
• Založí upomienkovú Úlohu (taskType: "invoice"), ktorá na faktúru odkazuje.

Nevie

• Nevystaví, needituje ani nezmaže žiadnu faktúru.
• Neoznačí faktúru za zaplatenú - to vie len Fakturoid alebo ABRA samy.
• Nepripojí Fakturoid prihlasovacími údajmi - ide len cez OAuth v prehliadači.

Pripojenie účtu

Obe fakturačné služby spravujete na rovnakom mieste ako kalendáre, v portáli v sekcii Dáta a integrácie (/propojeni). list_integrations a GET /v1/integrations sú len na čítanie: vrátia stav pripojenia a prípadný connectUrl, sami nič nepripoja. Podrobný postup pre agenta (list_integrations -> connectUrl -> krok v prehliadači) je na stránke Pripojenia.

Fakturoid

Pripája sa výlučne OAuth prihlásením v prehliadači - POST /v1/integrations s provider: "fakturoid" REST odmietne chybou integration_unsupported, prihlasovacie údaje sa sem posielať nedajú. Keď má účet viac firiem s fakturáciou, prehliadač sa po prihlásení vráti späť na stránku Dáta a integrácie vo volai (/propojeni) a až tam sa ukáže výber firmy - záznam v integrations vznikne až po tejto voľbe. ready pri fakturoid v GET /v1/integrations hlási len to, že má volai nastavené OAuth prihlasovacie údaje k Fakturoidu (FAKTUROID_CLIENT_ID a spol.) - NIE že je konkrétny účet už pripojený. Či je pripojenie hotové, agent pozná podľa toho, že sa objaví v poli integrations.

ABRA Flexi

Pripája sa prihlasovacími údajmi, rovnako ako Apple Calendar: POST /v1/integrations s {provider: "abra-flexi", baseUrl, company, username, password}. Adresa servera (baseUrl) musí sedieť na presnú adresu, ktorú prevádzkovateľ vopred povolil (ABRA_FLEXI_ALLOWED_HOSTS) - iná vráti chybu.

Čítanie faktúr

Dvojkrokový postup: najprv vyhľadanie, potom čerstvý detail tej jednej faktúry, ktorá Vás zaujíma.

• list_invoices({integrationId, search?}) - search (do 100 znakov) hľadá u poskytovateľa podľa čísla dokladu alebo názvu firmy; vráti prvých 40 riadkov pri Fakturoide alebo 50 pri ABRA, bez stránkovania. Keď je výsledkov veľa, spresnite search.
• get_invoice({integrationId, invoiceId}) - invoiceId je opakovaný externalId z list_invoices. Vracia najčerstvejší stav priamo od poskytovateľa, nie to, čo si pamätá volai.

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

status je paid, unpaid, overdue alebo unknown; amountDueMinor je celé číslo v najmenších jednotkách MENY DOKLADU (nie nutne CZK) a null znamená nezistený zostatok. Detail navyše nesie provider, fetchedAt a evidence: "provider_response".

Upomienka cez Úlohy

Hromadné upomienkové volanie o nezaplatených faktúrach ide cez Úlohy.

Úloha typu taskType: "invoice" sa založí so source: "integration" a každý príjemca (alebo celá úloha, keď je faktúra pre všetkých rovnaká) nesie externalRefs.invoice = {connectionId, externalId, provider?} - connectionId je id pripojenia z list_integrations, externalId id faktúry z list_invoices. Bez tejto referencie create_task/POST /v1/tasks zlyhá chybou validation so správou recipients.externalRefs a žiadnu úlohu neuloží. Ak by povinná referencia chýbala pri už existujúcom zázname, get_task/GET /v1/tasks/{id} ju uvedie v issues a start_task odmietne úlohu spustiť rovnakou validačnou chybou.

Každý príjemca navyše nesie pole paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - len na čítanie, systém ho odvodí z posledného čítania faktúry u poskytovateľa tesne pred vytáčaním. Bez referencie na faktúru je not_applicable, po založení alebo keď stav či sumu nejde overiť, je unknown, inak podľa odpovede Fakturoidu/ABRA - zaplatenú faktúru úloha položku preskočí (skipped) a nastaví paid. Hodnotu disputed dnes sám systém nenastavuje, len ju vie zobraziť portál - je súčasťou verejného výpočtu (TaskItem v /openapi.json) pre budúce ručné označenie sporných faktúr.

Chyby

• integration_not_found - Pripojenie s týmto integrationId neexistuje alebo nepatrí tomuto účtu.
• integration_unsupported - Pripojenie nie je fakturačné (napríklad kalendár), alebo ide o pokus pripojiť Fakturoid prihlasovacími údajmi namiesto OAuth.
• integration_unauthorized - Fakturoid alebo ABRA prístup odvolali - pripojenie je potrebné urobiť v portáli znova.
• integration_provider_error - Poskytovateľ momentálne neodpovedá alebo vrátil chybu - skúste to neskôr, stav faktúry medzitým berte ako neznámy.
• integration_invalid_query - ABRA odmietla search so spätnými lomkami alebo miešanými úvodzovkami - zjednodušte dopyt.

Úplnú tabuľku so všetkými kódmi nájdete v sekcii faktúry v REST API referencii a v chybách MCP.

Zabezpečenie

Prístupové tokeny ani heslá k Fakturoidu ani ABRA Flexi REST API ani MCP nikdy nevracajú a ukladáme ich šifrovane. Odpojenie integrácie ide len v portáli alebo cez REST (DELETE /v1/integrations/{id}) - MCP na to nemá nástroj zámerne, je to nevratné.