Juhendid

Arved

Agent oskab ühendatud Fakturoidist või ABRA Flexist väljastatud arve lugeda ja kasutada seda meeldetuletuskõne alusena - ta ei väljasta kunagi arvet ega märgi seda tasutuks.

Mida see oskab ja mida mitte

• Otsib väljastatud arveid numbri või ettevõtte nime järgi (list_invoices).
• Laadib ühe arve värske seisu otse teenusepakkujalt (get_invoice).
• Loob meeldetuletusülesande (taskType: "invoice"), mis viitab arvele.

Mida ei oska

• Ei väljasta, ei muuda ega kustuta ühtegi arvet.
• Ei märgi arvet tasutuks - seda oskavad ainult Fakturoid või ABRA ise.
• Ei ühenda Fakturoidi sisselogimisandmetega - see käib ainult brauseris OAuth kaudu.

Konto ühendamine

Mõlemat arveldusteenust haldate samas kohas kus kalendreid, portaali jaotises Andmed ja integratsioonid (/propojeni). list_integrations ja GET /v1/integrations on ainult lugemiseks: need tagastavad ühenduse oleku ja vajaduse korral connectUrl, ise midagi ei ühenda. Agendi üksikasjalik juhend (list_integrations -> connectUrl -> samm brauseris) on lehel Ühendused.

Fakturoid

Ühendatakse eranditult OAuth-sisselogimisega brauseris - POST /v1/integrations koos provider: "fakturoid" lükkab REST tagasi veaga integration_unsupported, sisselogimisandmeid siia saata ei saa. Kui kontol on mitu arveldust kasutavat ettevõtet, naaseb brauser pärast sisselogimist volai lehele Andmed ja integratsioonid (/propojeni) ning alles seal kuvatakse ettevõtte valik - kirje integrations tekib alles pärast seda valikut. Väli ready kirje fakturoid juures vastuses GET /v1/integrations annab teada ainult seda, et volai on seadistanud Fakturoidi OAuth-sisselogimisandmed (FAKTUROID_CLIENT_ID jt) - MITTE seda, et konkreetne konto on juba ühendatud. Kas ühendus on valmis, tunneb agent ära sellest, et see ilmub väljale integrations.

ABRA Flexi

Ühendatakse sisselogimisandmetega, nagu Apple Calendar: POST /v1/integrations koos {provider: "abra-flexi", baseUrl, company, username, password}. Serveri aadress (baseUrl) peab ühtima täpse aadressiga, mille haldaja on ette lubanud (ABRA_FLEXI_ALLOWED_HOSTS) - mis tahes muu tagastab vea.

Arvete lugemine

Kaheastmeline protseduur: kõigepealt otsing, seejärel selle ühe Teid huvitava arve värske detail.

• list_invoices({integrationId, search?}) - search (kuni 100 märki) otsib teenusepakkujal dokumendi numbri või ettevõtte nime järgi; tagastab Fakturoidis esimesed 40 rida või ABRA-s 50, lehitsemiseta. Kui tulemusi on liiga palju, täpsustage search.
• get_invoice({integrationId, invoiceId}) - invoiceId on list_invoices tagastatud externalId kordus. Tagastab kõige värskema seisu otse teenusepakkujalt, mitte seda, mida volai meeles peab.

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

status on paid, unpaid, overdue või unknown; amountDueMinor on täisarv ARVE VALUUTA väikseimates ühikutes (mitte tingimata CZK) ja null tähendab tuvastamata jääki. Detail kannab lisaks provider, fetchedAt ja evidence: "provider_response".

Meeldetuletus ülesannete kaudu

Maksmata arvete massiline meeldetuletuskõne käib läbi lehe Ülesanded.

Tüübi taskType: "invoice" ülesanne luuakse koos source: "integration" ja iga adressaat (või kogu ülesanne, kui arve on kõigile sama) kannab externalRefs.invoice = {connectionId, externalId, provider?} - connectionId on ühenduse id vastusest list_integrations, externalId arve id vastusest list_invoices. Ilma selle viiteta ebaõnnestub create_task/POST /v1/tasks veaga validation ja teatega recipients.externalRefs, ning ühtegi ülesannet ei salvestata. Kui kohustuslik viide peaks olemagi juba olemasoleva kirje juures puudu, toob get_task/GET /v1/tasks/{id} selle välja väljal issues ja start_task keeldub ülesannet käivitamast sama valideerimisveaga.

Iga adressaat kannab lisaks välja paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - ainult lugemiseks, süsteem tuletab selle teenusepakkuja viimasest arve lugemisest vahetult enne valimist. Ilma arveviiteta on see not_applicable, loomisel või kui seisu või summat ei saa kontrollida, on see unknown, muidu Fakturoidi/ABRA vastuse järgi - tasutud arve puhul jätab ülesanne kirje vahele (skipped) ja seab paid. Väärtust disputed süsteem ise praegu ei sea, seda oskab ainult portaal kuvada - see kuulub avalikku loendisse (TaskItem failis /openapi.json) vaidlustatud arve tulevaseks käsitsi märkimiseks.

Vead

• integration_not_found - Selle integrationId-ga ühendust ei ole või see ei kuulu sellele kontole.
• integration_unsupported - Ühendus ei ole arveldusühendus (näiteks kalender) või üritatakse Fakturoidi ühendada sisselogimisandmetega OAuth asemel.
• integration_unauthorized - Fakturoid või ABRA tühistasid juurdepääsu - ühendus tuleb portaalis uuesti teha.
• integration_provider_error - Teenusepakkuja ei vasta praegu või tagastas vea - proovige hiljem, arve seisu pidage vahepeal tundmatuks.
• integration_invalid_query - ABRA lükkas search tagasi kaldkriipsudega tagurpidi või segatud jutumärkidega - lihtsustage päringut.

Täieliku tabeli kõigi koodidega leiate jaotisest arved REST API viites ja jaotisest MCP vead.

Turvalisus

Juurdepääsutokeneid ega Fakturoidi ja ABRA Flexi paroole ei tagasta REST API ega MCP kunagi ning me salvestame need krüpteeritult. Integratsiooni lahtiühendamine käib ainult portaalis või REST kaudu (DELETE /v1/integrations/{id}) - MCP-l selleks tööriista tahtlikult ei ole, sest see on pöördumatu.