Handleidingen

Facturen

De agent kan een uitgegeven factuur uit een gekoppeld Fakturoid- of ABRA Flexi-account lezen en als basis voor een herinneringsgesprek gebruiken - hij maakt nooit een factuur aan en markeert er ook nooit een als betaald.

Wat het wel en niet kan

• Zoekt uitgegeven facturen op factuurnummer of bedrijfsnaam (list_invoices).
• Haalt de actuele status van één factuur rechtstreeks bij de aanbieder op (get_invoice).
• Maakt een herinneringstaak aan (taskType: "invoice") die naar de factuur verwijst.

Kan niet

• Maakt geen facturen aan, wijzigt of verwijdert ze niet.
• Markeert een factuur niet als betaald - dat kunnen alleen Fakturoid of ABRA zelf.
• Koppelt Fakturoid niet met inloggegevens - alleen via OAuth in de browser.

Account koppelen

Beide factuurdiensten beheert u op dezelfde plek als de agenda's, in het portaal onder Gegevens en integraties (/propojeni). list_integrations en GET /v1/integrations zijn alleen-lezen: ze geven de koppelingsstatus en eventueel een connectUrl terug, maar koppelen zelf niets. De uitgebreide werkwijze voor de agent (list_integrations -> connectUrl -> een stap in de browser) staat op de pagina Koppelingen.

Fakturoid

Koppelen kan uitsluitend via OAuth-aanmelding in de browser - POST /v1/integrations met provider: "fakturoid" wijst REST af met de fout integration_unsupported; inloggegevens kunt u hier niet meesturen. Heeft het account meerdere bedrijven met facturering, dan keert de browser na het aanmelden terug naar de pagina Gegevens en integraties in volai (/propojeni) en verschijnt daar pas de bedrijfskeuze - het record in integrations ontstaat pas na die keuze. ready bij fakturoid in GET /v1/integrations meldt alleen dat volai OAuth-inloggegevens voor Fakturoid heeft ingesteld (FAKTUROID_CLIENT_ID en dergelijke) - NIET dat een bepaald account al gekoppeld is. Of de koppeling klaar is, ziet de agent doordat ze in het veld integrations verschijnt.

ABRA Flexi

Koppelen gaat met inloggegevens, net als bij Apple Calendar: POST /v1/integrations met {provider: "abra-flexi", baseUrl, company, username, password}. Het serveradres (baseUrl) moet overeenkomen met het exacte adres dat de beheerder vooraf heeft toegestaan (ABRA_FLEXI_ALLOWED_HOSTS) - een ander adres levert een fout op.

Facturen lezen

Een werkwijze in twee stappen: eerst zoeken, daarna de actuele details van die ene factuur die u nodig hebt.

• list_invoices({integrationId, search?}) - search (maximaal 100 tekens) zoekt bij de aanbieder op factuurnummer of bedrijfsnaam; het geeft de eerste 40 rijen bij Fakturoid of 50 bij ABRA terug, zonder paginering. Zijn er te veel resultaten, maak search dan nauwkeuriger.
• get_invoice({integrationId, invoiceId}) - invoiceId is de overgenomen externalId uit list_invoices. Geeft de meest actuele status rechtstreeks van de aanbieder terug, niet wat volai zelf heeft onthouden.

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

status is paid, unpaid, overdue of unknown; amountDueMinor is een geheel getal in de kleinste eenheden van de VALUTA VAN DE FACTUUR (niet per se CZK) en null betekent een onbekend openstaand saldo. Het detail bevat bovendien provider, fetchedAt en evidence: "provider_response".

Herinnering via taken

Herinneringsgesprekken in bulk over onbetaalde facturen lopen via Taken.

Een taak van het type taskType: "invoice" wordt aangemaakt met source: "integration" en elke ontvanger (of de hele taak, als de factuur voor iedereen dezelfde is) bevat externalRefs.invoice = {connectionId, externalId, provider?} - connectionId is de id van de koppeling uit list_integrations, externalId de id van de factuur uit list_invoices. Zonder die verwijzing mislukt create_task/POST /v1/tasks met de fout validation en het bericht recipients.externalRefs en wordt er geen taak opgeslagen. Ontbreekt de verplichte verwijzing bij een bestaand record, dan vermeldt get_task/GET /v1/tasks/{id} dat in issues en weigert start_task de taak te starten met dezelfde validatiefout.

Elke ontvanger heeft bovendien het veld paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - alleen-lezen; het systeem leidt het af uit de laatste factuurlezing bij de aanbieder, vlak voor het bellen. Zonder verwijzing naar een factuur is het not_applicable, na het aanmaken of wanneer status of bedrag niet te controleren is unknown, anders volgt het het antwoord van Fakturoid/ABRA - bij een betaalde factuur slaat de taak dat item over (skipped) en zet paid. De waarde disputed zet het systeem zelf momenteel niet, het portaal kan haar alleen tonen - ze maakt deel uit van de openbare opsomming (TaskItem in /openapi.json) voor een toekomstige handmatige markering van een betwiste factuur.

Fouten

• integration_not_found - Een koppeling met deze integrationId bestaat niet of hoort niet bij dit account.
• integration_unsupported - De koppeling is geen factuurkoppeling (bijvoorbeeld een agenda), of er wordt geprobeerd Fakturoid met inloggegevens in plaats van OAuth te koppelen.
• integration_unauthorized - Fakturoid of ABRA heeft de toegang ingetrokken - koppel opnieuw in het portaal.
• integration_provider_error - De aanbieder reageert momenteel niet of gaf een fout terug - probeer het later opnieuw en beschouw de status van de factuur intussen als onbekend.
• integration_invalid_query - ABRA heeft search met backslashes of gemengde aanhalingstekens geweigerd - vereenvoudig de zoekopdracht.

De volledige tabel met alle codes vindt u in het gedeelte facturen in de REST API-referentie en in de MCP-fouten.

Beveiliging

Toegangstokens en wachtwoorden voor Fakturoid of ABRA Flexi geven de REST API en MCP nooit terug en wij slaan ze versleuteld op. Een integratie loskoppelen kan alleen in het portaal of via REST (DELETE /v1/integrations/{id}) - MCP heeft hier bewust geen tool voor, omdat het onomkeerbaar is.