Vejledninger

Fakturaer

Agenten kan læse en udstedt faktura fra en tilsluttet Fakturoid- eller ABRA Flexi-konto og bruge den som grundlag for et påmindelsesopkald - den udsteder aldrig en faktura og markerer aldrig en som betalt.

Hvad den kan og ikke kan

• Søge i udstedte fakturaer efter nummer eller firmanavn (list_invoices).
• Læse den ene fakturas friskeste status direkte hos udbyderen (get_invoice).
• Oprette en påmindelsesopgave (taskType: "invoice"), der henviser til fakturaen.

Kan ikke

• Den udsteder, redigerer eller sletter ingen fakturaer.
• Den markerer ikke en faktura som betalt - det kan kun Fakturoid eller ABRA selv.
• Den tilslutter ikke Fakturoid med adgangsoplysninger - kun via OAuth i browseren.

Tilslutning af en konto

Begge fakturatjenester administreres samme sted som kalendere, i portalens afsnit Data og integrationer (/en/connections). list_integrations og GET /v1/integrations er skrivebeskyttede: de returnerer forbindelsens tilstand og eventuelt en connectUrl, men tilslutter ikke noget selv. Det fulde agentforløb (list_integrations -> connectUrl -> et trin i browseren) står på siden Forbindelser.

Fakturoid

Tilsluttes kun via OAuth i browseren - POST /v1/integrations med provider: "fakturoid" afvises af REST med integration_unsupported; adgangsoplysninger kan slet ikke sendes på den måde. Har kontoen mere end ét firma med fakturering aktiveret, sendes browseren efter login tilbage til volais egen side Data og integrationer (/en/connections, eller /propojeni på tjekkisk), og der vises valget af firma - posten i integrations oprettes først efter dette valg. ready for fakturoid i GET /v1/integrations oplyser kun, at volai har konfigureret OAuth-oplysninger til Fakturoid (FAKTUROID_CLIENT_ID og de øvrige) - IKKE at en bestemt konto faktisk er tilsluttet. Om forbindelsen er oprettet, ses som en post i arrayet integrations.

ABRA Flexi

Tilsluttes med adgangsoplysninger, på samme måde som Apple Calendar: POST /v1/integrations med {provider: "abra-flexi", baseUrl, company, username, password}. Serveradressen (baseUrl) skal svare til en vært, som operatøren på forhånd har sat på tilladelseslisten (ABRA_FLEXI_ALLOWED_HOSTS) - alt andet afvises.

Læsning af fakturaer

Et forløb i to trin: først søgning, derefter en frisk læsning af den ene faktura, der er brug for.

• list_invoices({integrationId, search?}) - search (op til 100 tegn) er en søgning hos udbyderen efter fakturanummer eller firmanavn; den returnerer de første 40 rækker fra Fakturoid eller 50 fra ABRA, uden sideinddeling. Afgræns search yderligere, hvis der er for mange resultater.
• get_invoice({integrationId, invoiceId}) - invoiceId er den externalId, der er kopieret fra list_invoices. Returnerer den friskeste status direkte fra udbyderen, ikke det, volai husker.

REST-ækvivalenter: GET /v1/integrations/{id}/invoices?search=... og GET /v1/integrations/{id}/invoices/{invoiceId}.

status er paid, unpaid, overdue eller unknown; amountDueMinor er et heltal i FAKTURAENS EGEN VALUTAS mindste enhed (ikke nødvendigvis CZK), og null betyder, at restbeløbet ikke er bekræftet. Detaljen indeholder også provider, fetchedAt og evidence: "provider_response".

Påmindelser via opgaver

Massepåmindelser om ubetalte fakturaer foregår via Opgaver.

En opgave med taskType: "invoice" oprettes med source: "integration", og hver modtager (eller hele opgaven, når alle modtagere deler samme faktura) bærer externalRefs.invoice = {connectionId, externalId, provider?} - connectionId er forbindelses-id'et fra list_integrations, externalId er faktura-id'et fra list_invoices. Uden den reference fejler create_task/POST /v1/tasks med en validation-fejl, hvis besked nævner recipients.externalRefs, og ingen opgave gemmes. Hvis en eksisterende post manglede den påkrævede reference, ville get_task/GET /v1/tasks/{id} angive den i issues, og start_task ville afvise opgaven med samme valideringsfejl.

Hver modtager har desuden feltet paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - styret af systemet og skrivebeskyttet, afledt af den friskeste fakturalæsning hos udbyderen lige før opkaldet. Den er not_applicable uden fakturareference, unknown lige efter oprettelsen eller når status eller beløb ikke kan bekræftes, og følger ellers svaret fra Fakturoid/ABRA - en betalt faktura får opgaven til at springe posten over (skipped) og sætte paid. Systemet sætter aldrig selv disputed i dag - kun portalen kan vise den - den er en del af den offentlige enum (TaskItem i /openapi.json) til et fremtidigt manuelt flag for bestridelse.

Fejl

• integration_not_found - Der findes ingen forbindelse med dette integrationId, eller den tilhører ikke denne konto.
• integration_unsupported - Forbindelsen er ikke en faktureringsforbindelse (for eksempel en kalender), eller der blev forsøgt at tilslutte Fakturoid med adgangsoplysninger i stedet for OAuth.
• integration_unauthorized - Fakturoid eller ABRA har tilbagekaldt adgangen - tilslut igen i portalen.
• integration_provider_error - Udbyderen svarer ikke lige nu eller returnerede en fejl - prøv igen senere, og behandl fakturaens tilstand som ukendt i mellemtiden.
• integration_invalid_query - ABRA afviste search på grund af omvendte skråstreger eller blandede anførselstegn - forenkl forespørgslen.

Den fulde tabel med alle koder findes i afsnittet om fakturaer i REST API-referencen og i MCP-fejl.

Sikkerhed

REST API og MCP returnerer aldrig adgangstokens eller adgangskoder til Fakturoid eller ABRA Flexi, og vi gemmer dem krypteret. En integration kan kun frakobles i portalen eller via REST (DELETE /v1/integrations/{id}) - MCP har bevidst intet værktøj til det, da det ikke kan fortrydes.