Ghiduri

Facturi

Agentul poate citi o factură emisă dintr-un cont Fakturoid sau ABRA Flexi conectat și o poate folosi ca bază pentru un apel de reamintire - nu emite niciodată o factură și nu o marchează ca plătită.

Ce poate și ce nu poate face

• Caută facturi emise după număr sau după numele firmei (list_invoices).
• Citește starea cea mai recentă a unei facturi direct de la furnizor (get_invoice).
• Creează o Sarcină de reamintire (taskType: "invoice") care face trimitere la factură.

Nu poate

• Nu emite, nu modifică și nu șterge nicio factură.
• Nu marchează o factură ca plătită - doar Fakturoid sau ABRA o pot face.
• Nu conectează Fakturoid cu date de autentificare - doar prin OAuth în browser.

Conectarea unui cont

Ambele servicii de facturare se administrează în același loc ca și calendarele, în portal, la secțiunea Date și integrări (/propojeni). list_integrations și GET /v1/integrations sunt doar pentru citire: returnează starea conexiunii și, eventual, un connectUrl, dar nu conectează nimic. Procedura completă pentru agent (list_integrations -> connectUrl -> un pas în browser) se găsește pe pagina Conexiuni.

Fakturoid

Se conectează exclusiv prin autentificare OAuth în browser - POST /v1/integrations cu provider: "fakturoid" este respins de REST cu eroarea integration_unsupported, iar datele de autentificare nu pot fi trimise în acest mod. Dacă în cont există mai multe firme cu facturare, după autentificare browserul revine la pagina Date și integrări din volai (/propojeni) și abia acolo apare selectarea firmei - înregistrarea din integrations se creează numai după această alegere. Valoarea ready pentru fakturoid în GET /v1/integrations arată doar că volai are configurate datele de autentificare OAuth pentru Fakturoid (FAKTUROID_CLIENT_ID și cele asemenea) - NU că un anumit cont este deja conectat. Dacă o conexiune este finalizată, agentul își dă seama după faptul că apare în câmpul integrations.

ABRA Flexi

Se conectează cu date de autentificare, la fel ca Apple Calendar: POST /v1/integrations cu {provider: "abra-flexi", baseUrl, company, username, password}. Adresa serverului (baseUrl) trebuie să corespundă exact adresei pe care operatorul a permis-o în prealabil (ABRA_FLEXI_ALLOWED_HOSTS) - orice altă adresă returnează o eroare.

Citirea facturilor

O procedură în doi pași: mai întâi căutarea, apoi o citire proaspătă a facturii care vă interesează.

• list_invoices({integrationId, search?}) - search (maximum 100 de caractere) caută la furnizor după numărul documentului sau după numele firmei; returnează primele 40 de rânduri la Fakturoid sau 50 la ABRA, fără paginare. Când sunt prea multe rezultate, restrângeți search.
• get_invoice({integrationId, invoiceId}) - invoiceId este externalId repetat din list_invoices. Returnează starea cea mai recentă direct de la furnizor, nu ceea ce își amintește volai.

Echivalente REST: GET /v1/integrations/{id}/invoices?search=... și GET /v1/integrations/{id}/invoices/{invoiceId}.

status este paid, unpaid, overdue sau unknown; amountDueMinor este un număr întreg în cele mai mici unități ale MONEDEI FACTURII (nu neapărat CZK), iar null înseamnă un sold neverificat. Detaliul conține suplimentar provider, fetchedAt și evidence: "provider_response".

Reamintire prin Sarcini

Apelurile în masă de reamintire pentru facturi neplătite se fac prin Sarcini.

O Sarcină de tip taskType: "invoice" se creează cu source: "integration", iar fiecare destinatar (sau întreaga sarcină, când factura este aceeași pentru toți) poartă externalRefs.invoice = {connectionId, externalId, provider?} - connectionId este id-ul conexiunii din list_integrations, iar externalId este id-ul facturii din list_invoices. Fără această referință, create_task/POST /v1/tasks eșuează cu eroarea validation cu mesajul recipients.externalRefs, iar nicio sarcină nu se salvează. Dacă referința obligatorie lipsește la o înregistrare deja existentă, get_task/GET /v1/tasks/{id} o menționează în issues, iar start_task refuză să pornească sarcina cu aceeași eroare de validare.

Fiecare destinatar poartă în plus câmpul paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - doar pentru citire, sistemul îl deduce din ultima citire a facturii la furnizor, chiar înainte de apelare. Fără referință la factură este not_applicable, după creare sau când starea ori suma nu pot fi verificate este unknown, altfel urmează răspunsul Fakturoid/ABRA - la o factură plătită sarcina omite elementul (skipped) și setează paid. Valoarea disputed nu este setată astăzi de sistem, ci doar poate fi afișată de portal - face parte din enumerarea publică (TaskItem în /openapi.json) pentru o viitoare marcare manuală a unei facturi contestate.

Erori

• integration_not_found - Nu există nicio conexiune cu acest integrationId sau nu aparține acestui cont.
• integration_unsupported - Conexiunea nu este una de facturare (de exemplu un calendar) sau este o încercare de a conecta Fakturoid cu date de autentificare în loc de OAuth.
• integration_unauthorized - Fakturoid sau ABRA au revocat accesul - conexiunea trebuie refăcută în portal.
• integration_provider_error - Furnizorul nu răspunde momentan sau a returnat o eroare - încercați mai târziu, iar între timp considerați starea facturii ca necunoscută.
• integration_invalid_query - ABRA a respins search cu bară oblică inversă sau ghilimele amestecate - simplificați interogarea.

Tabelul complet cu toate codurile îl găsiți în secțiunea facturi din referința REST API și în erorile MCP.

Securitate

REST API și MCP nu returnează niciodată token-urile de acces sau parolele pentru Fakturoid ori ABRA Flexi, iar noi le stocăm criptat. Deconectarea unei integrări se poate face doar în portal sau prin REST (DELETE /v1/integrations/{id}) - MCP nu are un instrument pentru aceasta în mod intenționat, deoarece este ireversibilă.