Guider

Fakturor

Agenten kan läsa en utfärdad faktura från en ansluten Fakturoid eller ABRA Flexi och använda den som underlag för ett påminnelsesamtal - den utfärdar aldrig en faktura och markerar ingen som betald.

Vad den kan och inte kan

• Söker utfärdade fakturor på nummer eller företagsnamn (list_invoices).
• Hämtar aktuell status för en enskild faktura direkt från leverantören (get_invoice).
• Skapar en påminnelseuppgift (taskType: "invoice") som hänvisar till fakturan.

Kan inte

• Utfärdar, redigerar eller raderar inga fakturor.
• Markerar inte en faktura som betald - det kan bara Fakturoid eller ABRA själva göra.
• Ansluter inte Fakturoid med inloggningsuppgifter - det går bara via OAuth i webbläsaren.

Ansluta kontot

Båda faktureringstjänsterna hanteras på samma ställe som kalendrarna, i portalen under Data och integrationer (/propojeni). list_integrations och GET /v1/integrations är skrivskyddade: de returnerar anslutningsstatus och eventuell connectUrl, men ansluter inget själva. Den detaljerade proceduren för agenten (list_integrations -> connectUrl -> ett steg i webbläsaren) finns på sidan Anslutningar.

Fakturoid

Ansluts uteslutande med OAuth-inloggning i webbläsaren - POST /v1/integrations med provider: "fakturoid" avvisas av REST med felet integration_unsupported, inloggningsuppgifter kan inte skickas hit. Om kontot har flera företag med fakturering återvänder webbläsaren efter inloggningen till sidan Data och integrationer i volai (/propojeni, eventuellt /en/connections) och först där visas valet av företag - posten i integrations skapas först efter det valet. ready för fakturoid i GET /v1/integrations anger bara att volai har OAuth-uppgifterna till Fakturoid inställda (FAKTUROID_CLIENT_ID med flera) - INTE att ett visst konto redan är anslutet. Om anslutningen är klar ser agenten på att den dyker upp i fältet integrations.

ABRA Flexi

Ansluts med inloggningsuppgifter, precis som Apple Calendar: POST /v1/integrations med {provider: "abra-flexi", baseUrl, company, username, password}. Serveradressen (baseUrl) måste överensstämma med exakt den adress som operatören i förväg har tillåtit (ABRA_FLEXI_ALLOWED_HOSTS) - en annan adress ger ett fel.

Läsa fakturor

Ett förfarande i två steg: först en sökning, sedan en aktuell detaljvy av den enda faktura som är av intresse.

• list_invoices({integrationId, search?}) - search (upp till 100 tecken) söker hos leverantören på dokumentnummer eller företagsnamn; returnerar de första 40 raderna hos Fakturoid eller 50 hos ABRA, utan sidindelning. Om träffarna är för många, precisera search.
• get_invoice({integrationId, invoiceId}) - invoiceId är det upprepade externalId från list_invoices. Returnerar den allra färskaste statusen direkt från leverantören, inte det som volai minns.

REST-motsvarigheter: GET /v1/integrations/{id}/invoices?search=... och GET /v1/integrations/{id}/invoices/{invoiceId}.

status är paid, unpaid, overdue eller unknown; amountDueMinor är ett heltal i den minsta enheten för FAKTURANS VALUTA (inte nödvändigtvis CZK) och null betyder ett okänt återstående belopp. Detaljvyn har dessutom provider, fetchedAt och evidence: "provider_response".

Påminnelse via Uppgifter

Massutskick av påminnelsesamtal om obetalda fakturor går via Uppgifter.

En uppgift av typen taskType: "invoice" skapas med source: "integration" och varje mottagare (eller hela uppgiften, när fakturan är densamma för alla) har externalRefs.invoice = {connectionId, externalId, provider?} - connectionId är anslutningens id från list_integrations, externalId är fakturans id från list_invoices. Utan den här referensen misslyckas create_task/POST /v1/tasks med felet validation och meddelandet recipients.externalRefs, och ingen uppgift sparas. Om den obligatoriska referensen skulle saknas i en redan befintlig post redovisar get_task/GET /v1/tasks/{id} den i issues, och start_task vägrar starta uppgiften med samma valideringsfel.

Varje mottagare har dessutom fältet paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - endast läsbart, systemet härleder det från den senaste läsningen av fakturan hos leverantören strax före uppringningen. Utan fakturareferens är det not_applicable, efter skapandet eller när status eller belopp inte går att verifiera är det unknown, annars enligt svaret från Fakturoid/ABRA - en betald faktura gör att uppgiften hoppar över posten (skipped) och sätter paid. Värdet disputed sätts i dag inte av systemet självt, portalen kan bara visa det - det ingår i den publika uppsättningen (TaskItem i /openapi.json) för en framtida manuell markering av en omtvistad faktura.

Fel

• integration_not_found - Anslutningen med detta integrationId finns inte eller tillhör inte det här kontot.
• integration_unsupported - Anslutningen är inte en faktureringsanslutning (till exempel en kalender), eller så görs ett försök att ansluta Fakturoid med inloggningsuppgifter i stället för OAuth.
• integration_unauthorized - Fakturoid eller ABRA har återkallat åtkomsten - anslutningen måste göras om i portalen.
• integration_provider_error - Leverantören svarar för tillfället inte eller returnerade ett fel - försök senare och behandla fakturans status som okänd under tiden.
• integration_invalid_query - ABRA avvisade search med omvända snedstreck eller blandade citattecken - förenkla frågan.

Den fullständiga tabellen med alla koder finns i avsnittet fakturor i REST API-referensen och i MCP-fel.

Säkerhet

Åtkomsttoken och lösenord till Fakturoid eller ABRA Flexi returneras aldrig av REST API eller MCP, och vi lagrar dem krypterade. En integration kan bara kopplas bort i portalen eller via REST (DELETE /v1/integrations/{id}) - MCP har medvetet inget verktyg för det, eftersom det är oåterkalleligt.