Vodniki

Računi

Agent lahko prebere izdan račun iz povezanega Fakturoida ali ABRA Flexi in ga uporabi kot podlago za opominjevalni klic - računa nikoli ne izda in ga ne označi kot plačanega.

Kaj zmore in česa ne

• Poišče izdane račune po številki ali imenu podjetja (list_invoices).
• Prebere sveže stanje enega računa neposredno pri ponudniku (get_invoice).
• Ustvari opominjevalno nalogo (taskType: "invoice"), ki se sklicuje na račun.

Česa ne zmore

• Ne izda, ne ureja in ne izbriše nobenega računa.
• Ne označi računa kot plačanega - to zmoreta le Fakturoid ali ABRA sama.
• Ne poveže Fakturoida s prijavnimi podatki - povezava poteka samo prek OAuth v brskalniku.

Povezava računa

Obe storitvi za izdajanje računov upravljate na istem mestu kot koledarje, v portalu v razdelku Podatki in integracije (/propojeni). list_integrations in GET /v1/integrations sta samo za branje: vrneta stanje povezave in morebitni connectUrl, sama pa ničesar ne povežeta. Podroben postopek za agenta (list_integrations -> connectUrl -> korak v brskalniku) je na strani Povezave.

Fakturoid

Povezuje se izključno s prijavo OAuth v brskalniku - POST /v1/integrations s provider: "fakturoid" REST zavrne z napako integration_unsupported, prijavnih podatkov sem ni mogoče pošiljati. Če ima račun več podjetij z izdajanjem računov, se brskalnik po prijavi vrne na stran Podatki in integracije v volai (/propojeni) in šele tam se prikaže izbira podjetja - zapis v integrations nastane šele po tej izbiri. ready pri fakturoid v GET /v1/integrations sporoča samo, da ima volai nastavljene prijavne podatke OAuth za Fakturoid (FAKTUROID_CLIENT_ID in drugi) - NE, da je konkreten račun že povezan. Ali je povezava končana, agent ugotovi po tem, da se pojavi v polju integrations.

ABRA Flexi

Povezuje se s prijavnimi podatki, enako kot Apple Calendar: POST /v1/integrations z {provider: "abra-flexi", baseUrl, company, username, password}. Naslov strežnika (baseUrl) se mora ujemati z natančnim naslovom, ki ga je upravljavec vnaprej dovolil (ABRA_FLEXI_ALLOWED_HOSTS) - drug naslov vrne napako.

Branje računov

Postopek v dveh korakih: najprej iskanje, nato svež podatek o tistem računu, ki vas zanima.

• list_invoices({integrationId, search?}) - search (do 100 znakov) išče pri ponudniku po številki dokumenta ali imenu podjetja; vrne prvih 40 vrstic pri Fakturoidu ali 50 pri ABRA, brez strani. Če je zadetkov preveč, zožite search.
• get_invoice({integrationId, invoiceId}) - invoiceId je ponovljeni externalId iz list_invoices. Vrne najsvežejše stanje neposredno od ponudnika, ne tistega, kar si zapomni volai.

Ustrezniki REST: GET /v1/integrations/{id}/invoices?search=... in GET /v1/integrations/{id}/invoices/{invoiceId}.

status je paid, unpaid, overdue ali unknown; amountDueMinor je celo število v najmanjših enotah VALUTE RAČUNA (ne nujno CZK), null pa pomeni, da neporavnani znesek ni znan. Podrobnost poleg tega vsebuje provider, fetchedAt in evidence: "provider_response".

Opomin prek nalog

Množično opominjevalno klicanje zaradi neplačanih računov poteka prek Naloge.

Naloga tipa taskType: "invoice" se ustvari s source: "integration" in vsak prejemnik (ali celotna naloga, če je račun za vse enak) nosi externalRefs.invoice = {connectionId, externalId, provider?} - connectionId je id povezave iz list_integrations, externalId pa id računa iz list_invoices. Brez te reference create_task/POST /v1/tasks ne uspe z napako validation s sporočilom recipients.externalRefs in nobena naloga se ne shrani. Če obvezna referenca manjka pri že obstoječem zapisu, jo get_task/GET /v1/tasks/{id} navede v issues, start_task pa zavrne zagon naloge z isto validacijsko napako.

Vsak prejemnik poleg tega nosi polje paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - samo za branje, sistem ga izpelje iz zadnjega branja računa pri ponudniku tik pred klicanjem. Brez reference na račun je not_applicable, po ustvarjanju ali kadar stanja ali zneska ni mogoče preveriti, je unknown, sicer glede na odgovor Fakturoida/ABRA - pri plačanem računu naloga postavko preskoči (skipped) in nastavi paid. Vrednosti disputed sistem danes sam ne nastavlja, portal jo zgolj zna prikazati - je del javnega seznama (TaskItem v /openapi.json) za prihodnje ročno označevanje spornega računa.

Napake

• integration_not_found - Povezava s tem integrationId ne obstaja ali ne pripada temu računu.
• integration_unsupported - Povezava ni povezava za račune (na primer koledar) ali pa gre za poskus povezave Fakturoida s prijavnimi podatki namesto OAuth.
• integration_unauthorized - Fakturoid ali ABRA sta dostop preklicala - povezavo je treba v portalu vzpostaviti znova.
• integration_provider_error - Ponudnik trenutno ne odgovarja ali je vrnil napako - poskusite pozneje, stanje računa medtem obravnavajte kot neznano.
• integration_invalid_query - ABRA je zavrnila search z levimi poševnicami ali pomešanimi narekovaji - poenostavite poizvedbo.

Celotno tabelo vseh kod najdete v razdelku računi v referenci REST API in v napakah MCP.

Varnost

Dostopnih žetonov in gesel za Fakturoid ali ABRA Flexi REST API in MCP nikoli ne vrneta, mi pa jih shranjujemo šifrirano. Integracijo je mogoče odklopiti samo v portalu ali prek REST (DELETE /v1/integrations/{id}) - MCP za to namenoma nima orodja, ker je dejanje nepovratno.