Pamācības

Rēķini

Aģents spēj nolasīt izrakstītu rēķinu no pieslēgta Fakturoid vai ABRA Flexi konta un izmantot to kā pamatu atgādinājuma zvanam - rēķinu nekad neizraksta un neatzīmē kā apmaksātu.

Ko tas spēj un ko ne

• Meklē izrakstītos rēķinus pēc numura vai uzņēmuma nosaukuma (list_invoices).
• Nolasa viena rēķina svaigāko statusu tieši no pakalpojuma sniedzēja (get_invoice).
• Izveido atgādinājuma Uzdevumu (taskType: "invoice"), kas atsaucas uz rēķinu.

Nespēj

• Neizraksta, nelabo un neizdzēš nevienu rēķinu.
• Neatzīmē rēķinu kā apmaksātu - to var tikai pats Fakturoid vai ABRA.
• Nepieslēdz Fakturoid ar pieteikšanās datiem - tikai ar OAuth pārlūkprogrammā.

Konta pieslēgšana

Abus rēķinu pakalpojumus pārvaldāt tajā pašā vietā, kur kalendārus - portālā sadaļā Dati un integrācijas (/propojeni). list_integrations un GET /v1/integrations ir tikai lasīšanai: tie atgriež pieslēguma stāvokli un iespējamo connectUrl, paši neko nepieslēdz. Detalizēta aģenta procedūra (list_integrations -> connectUrl -> solis pārlūkprogrammā) ir lapā Pieslēgumi.

Fakturoid

Pieslēdzas tikai ar OAuth pieteikšanos pārlūkprogrammā - POST /v1/integrations ar provider: "fakturoid" REST noraida ar kļūdu integration_unsupported, pieteikšanās datus šeit sūtīt nevar. Ja kontam ir vairāki uzņēmumi ar rēķinu izrakstīšanu, pēc pieteikšanās pārlūkprogramma atgriežas volai lapā Dati un integrācijas (/propojeni), un tikai tur parādās uzņēmuma izvēle - ieraksts integrations rodas tikai pēc šīs izvēles. ready pie fakturoid atbildē GET /v1/integrations norāda tikai to, ka volai ir iestatīti OAuth pieteikšanās dati Fakturoid (FAKTUROID_CLIENT_ID un citi) - NE to, ka konkrētais konts jau ir pieslēgts. Vai pieslēgums ir gatavs, aģents redz pēc tā, ka tas parādās laukā integrations.

ABRA Flexi

Pieslēdzas ar pieteikšanās datiem, tāpat kā Apple Calendar: POST /v1/integrations ar {provider: "abra-flexi", baseUrl, company, username, password}. Servera adresei (baseUrl) jāatbilst precīzai adresei, ko operators iepriekš atļāvis (ABRA_FLEXI_ALLOWED_HOSTS) - cita adrese atgriež kļūdu.

Rēķinu nolasīšana

Divu soļu procedūra: vispirms meklēšana, pēc tam svaigs tā viena rēķina detalizētais skats, kas jūs interesē.

• list_invoices({integrationId, search?}) - search (līdz 100 rakstzīmēm) meklē pie pakalpojuma sniedzēja pēc dokumenta numura vai uzņēmuma nosaukuma; atgriež pirmās 40 rindas Fakturoid vai 50 ABRA gadījumā, bez lappusēm. Ja rezultātu ir pārāk daudz, precizējiet search.
• get_invoice({integrationId, invoiceId}) - invoiceId ir no list_invoices pārrakstītais externalId. Atgriež svaigāko stāvokli tieši no pakalpojuma sniedzēja, nevis to, ko atceras volai.

REST ekvivalenti: GET /v1/integrations/{id}/invoices?search=... un GET /v1/integrations/{id}/invoices/{invoiceId}.

status ir paid, unpaid, overdue vai unknown; amountDueMinor ir vesels skaitlis DOKUMENTA VALŪTAS mazākajās vienībās (ne obligāti CZK), un null nozīmē neizdibinātu atlikumu. Detalizētais skats papildus satur provider, fetchedAt un evidence: "provider_response".

Atgādinājums ar Uzdevumiem

Masveida atgādinājuma zvani par neapmaksātiem rēķiniem notiek ar Uzdevumi.

Uzdevums ar taskType: "invoice" tiek izveidots ar source: "integration", un katrs saņēmējs (vai viss uzdevums, ja rēķins visiem ir vienāds) satur externalRefs.invoice = {connectionId, externalId, provider?} - connectionId ir pieslēguma id no list_integrations, externalId ir rēķina id no list_invoices. Bez šīs atsauces create_task/POST /v1/tasks beidzas ar kļūdu validation un ziņu recipients.externalRefs, un neviens uzdevums netiek saglabāts. Ja obligātā atsauce trūktu jau esošam ierakstam, get_task/GET /v1/tasks/{id} to norāda laukā issues, un start_task atsakās palaist uzdevumu ar to pašu validācijas kļūdu.

Katrs saņēmējs papildus satur lauku paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - tikai lasīšanai, sistēma to atvasina no pēdējā rēķina nolasījuma pie pakalpojuma sniedzēja tieši pirms zvanīšanas. Bez atsauces uz rēķinu tas ir not_applicable, pēc izveides vai ja statusu vai summu nevar pārbaudīt - unknown, pretējā gadījumā atbilstoši Fakturoid/ABRA atbildei - apmaksāta rēķina gadījumā uzdevums šo vienumu izlaiž (skipped) un iestata paid. Vērtību disputed sistēma šobrīd pati neiestata, to tikai spēj attēlot portāls - tā ir publiskā uzskaitījuma daļa (TaskItem failā /openapi.json) nākotnes manuālai strīdīga rēķina atzīmēšanai.

Kļūdas

• integration_not_found - Pieslēgums ar šo integrationId neeksistē vai nepieder šim kontam.
• integration_unsupported - Pieslēgums nav rēķinu pieslēgums (piemēram, kalendārs), vai arī tiek mēģināts pieslēgt Fakturoid ar pieteikšanās datiem OAuth vietā.
• integration_unauthorized - Fakturoid vai ABRA piekļuvi atsauca - pieslēgums portālā jāveic no jauna.
• integration_provider_error - Pakalpojuma sniedzējs pašlaik neatbild vai atgrieza kļūdu - mēģiniet vēlāk, rēķina stāvokli līdz tam uzskatiet par nezināmu.
• integration_invalid_query - ABRA noraidīja search ar atpakaļvērstajām slīpsvītrām vai jauktām pēdiņām - vienkāršojiet vaicājumu.

Pilnu tabulu ar visiem kodiem atradīsiet sadaļā rēķini REST API atsaucē un MCP kļūdās.

Drošība

REST API un MCP nekad neatgriež piekļuves token vai paroles Fakturoid vai ABRA Flexi, un mēs tos glabājam šifrētus. Integrāciju atvienot var tikai portālā vai ar REST (DELETE /v1/integrations/{id}) - MCP šim nolūkam rīka tīši nav, jo tas ir neatgriezeniski.