Vodiči

Računi

Agent može pročitati izdani račun iz povezanog Fakturoida ili ABRA Flexija i upotrijebiti ga kao podlogu za opomenu telefonom - nikada ne izdaje račun niti ga označava kao plaćenog.

Što može, a što ne može

• Pretražuje izdane račune prema broju ili nazivu tvrtke (list_invoices).
• Dohvaća svježe stanje jednog računa izravno od pružatelja (get_invoice).
• Izrađuje Zadatak opomene (taskType: "invoice") koji upućuje na račun.

Ne može

• Ne izdaje, ne uređuje i ne briše nijedan račun.
• Ne označava račun kao plaćen - to mogu samo Fakturoid ili ABRA.
• Ne povezuje Fakturoid pristupnim podacima - moguće je samo putem OAuth-a u pregledniku.

Povezivanje računa

Obje usluge izdavanja računa upravljate na istom mjestu kao i kalendare, u portalu u odjeljku Podaci i integracije (/propojeni). list_integrations i GET /v1/integrations služe samo za čitanje: vraćaju stanje veze i eventualni connectUrl, a sami ništa ne povezuju. Detaljan postupak za agenta (list_integrations -> connectUrl -> korak u pregledniku) nalazi se na stranici Veze.

Fakturoid

Povezuje se isključivo OAuth prijavom u pregledniku - POST /v1/integrations s provider: "fakturoid" REST odbija pogreškom integration_unsupported, pristupni se podaci ovamo ne mogu slati. Ako račun ima više tvrtki s izdavanjem računa, preglednik se nakon prijave vraća na stranicu Podaci i integracije u volai (/propojeni) i tek se tamo prikazuje odabir tvrtke - zapis u integrations nastaje tek nakon tog odabira. ready kod fakturoid u GET /v1/integrations javlja samo da volai ima postavljene OAuth pristupne podatke za Fakturoid (FAKTUROID_CLIENT_ID i dr.) - NE da je konkretan račun već povezan. Je li veza gotova, agent prepoznaje po tome što se pojavi u polju integrations.

ABRA Flexi

Povezuje se pristupnim podacima, kao i Apple Calendar: POST /v1/integrations s {provider: "abra-flexi", baseUrl, company, username, password}. Adresa poslužitelja (baseUrl) mora odgovarati točnoj adresi koju je operator unaprijed odobrio (ABRA_FLEXI_ALLOWED_HOSTS) - svaka druga vraća pogrešku.

Čitanje računa

Postupak u dva koraka: najprije pretraga, zatim svježi detalj onog jednog računa koji vas zanima.

• list_invoices({integrationId, search?}) - search (do 100 znakova) traži kod pružatelja prema broju računa ili nazivu tvrtke; vraća prvih 40 redaka kod Fakturoida ili 50 kod ABRA-e, bez straničenja. Ako je rezultata previše, precizirajte search.
• get_invoice({integrationId, invoiceId}) - invoiceId je ponovljeni externalId iz list_invoices. Vraća najsvježije stanje izravno od pružatelja, a ne ono što pamti volai.

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

status je paid, unpaid, overdue ili unknown; amountDueMinor je cijeli broj u najmanjim jedinicama VALUTE RAČUNA (ne nužno CZK), a null znači nepoznat preostali iznos. Detalj dodatno sadrži provider, fetchedAt i evidence: "provider_response".

Opomena putem Zadataka

Skupno pozivanje radi opomene za neplaćene račune ide putem Zadaci.

Zadatak tipa taskType: "invoice" izrađuje se sa source: "integration", a svaki primatelj (ili cijeli zadatak ako je račun za sve isti) nosi externalRefs.invoice = {connectionId, externalId, provider?} - connectionId je id veze iz list_integrations, externalId id računa iz list_invoices. Bez te reference create_task/POST /v1/tasks ne uspijeva pogreškom validation s porukom recipients.externalRefs i nijedan zadatak ne sprema. Ako obvezna referenca nedostaje kod već postojećeg zapisa, get_task/GET /v1/tasks/{id} navodi je u issues, a start_task odbija pokrenuti zadatak istom pogreškom validacije.

Svaki primatelj dodatno nosi polje paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - samo za čitanje, sustav ga izvodi iz posljednjeg čitanja računa kod pružatelja neposredno prije biranja. Bez reference na račun je not_applicable, nakon izrade ili kada se stanje ili iznos ne može provjeriti je unknown, inače prema odgovoru Fakturoida/ABRA-e - plaćeni račun zadatak preskače (skipped) i postavlja paid. Vrijednost disputed sustav danas sam ne postavlja, samo je portal može prikazati - dio je javnog popisa vrijednosti (TaskItem u /openapi.json) za buduće ručno označavanje spornog računa.

Pogreške

• integration_not_found - Veza s ovim integrationId ne postoji ili ne pripada ovom računu.
• integration_unsupported - Veza nije za izdavanje računa (na primjer kalendar) ili je riječ o pokušaju povezivanja Fakturoida pristupnim podacima umjesto OAuth-om.
• integration_unauthorized - Fakturoid ili ABRA opozvali su pristup - vezu je potrebno ponovno uspostaviti u portalu.
• integration_provider_error - Pružatelj trenutno ne odgovara ili je vratio pogrešku - pokušajte kasnije, a stanje računa u međuvremenu smatrajte nepoznatim.
• integration_invalid_query - ABRA je odbila search s obrnutim kosim crtama ili pomiješanim navodnicima - pojednostavnite upit.

Cjelovitu tablicu sa svim kodovima nalazite u odjeljku računi u REST API referenci i u pogreškama MCP-a.

Sigurnost

Pristupne tokene i lozinke za Fakturoid i ABRA Flexi REST API i MCP nikada ne vraćaju, a mi ih pohranjujemo šifrirano. Prekid integracije moguć je samo u portalu ili putem REST-a (DELETE /v1/integrations/{id}) - MCP za to namjerno nema alat jer je radnja nepovratna.