Siirry sisältöön

Oppaat

Laskut

Agentti voi lukea annetun laskun yhdistetystä Fakturoid- tai ABRA Flexi -tilistä ja käyttää sitä muistutuspuhelun pohjana - se ei koskaan anna laskua eikä merkitse mitään laskua maksetuksi.

Mitä se osaa ja mitä ei

  • Hakee annettuja laskuja numeron tai yrityksen nimen perusteella (list_invoices).
  • Lukee yksittäisen laskun tuoreimman tilan suoraan palveluntarjoajalta (get_invoice).
  • Luo laskuun viittaavan muistutustehtävän (taskType: "invoice").

Ei voi

  • Ei anna, muokkaa eikä poista laskuja.
  • Ei merkitse laskua maksetuksi - sen voivat tehdä vain Fakturoid tai ABRA itse.
  • Ei yhdistä Fakturoidia tunnuksilla - yhdistäminen onnistuu vain OAuth-kirjautumisella selaimessa.

Tilin yhdistäminen

Molempia laskutuspalveluja hallitaan samassa paikassa kuin kalentereita, portaalin osiossa Yhteydet ja API (/propojeni). list_integrations ja GET /v1/integrations ovat vain luku -kutsuja: ne palauttavat yhteyden tilan ja mahdollisen connectUrl-osoitteen, mutta eivät yhdistä mitään itse. Agentin yksityiskohtainen toimintatapa (list_integrations -> connectUrl -> yksi vaihe selaimessa) on sivulla Yhteydet.

Fakturoid

Yhdistetään yksinomaan OAuth-kirjautumisella selaimessa - POST /v1/integrations arvolla provider: "fakturoid" hylätään REST-rajapinnassa virheellä integration_unsupported, tunnuksia ei voi lähettää tätä kautta. Jos tilillä on useita laskutukseen kelpaavia yrityksiä, selain palaa kirjautumisen jälkeen volain Yhteydet ja API -sivulle (/propojeni, tarvittaessa /en/connections) ja yrityksen valinta näytetään vasta siellä - integrations-merkintä luodaan vasta tämän valinnan jälkeen. ready arvolle fakturoid kohdassa GET /v1/integrations kertoo vain, että volaille on asetettu Fakturoidin OAuth-tunnukset (FAKTUROID_CLIENT_ID ja muut) - EI sitä, että jokin tietty tili olisi jo yhdistetty. Agentti näkee yhteyden valmistuneen siitä, että se ilmestyy integrations-kenttään.

ABRA Flexi

Yhdistetään tunnuksilla, aivan kuten Apple Calendar: POST /v1/integrations sisällöllä {provider: "abra-flexi", baseUrl, company, username, password}. Palvelimen osoitteen (baseUrl) on vastattava täsmälleen sitä osoitetta, jonka ylläpitäjä on etukäteen sallinut (ABRA_FLEXI_ALLOWED_HOSTS) - muu osoite aiheuttaa virheen.

Salasana luovutetaan vain, kun käyttäjällä on se jo tallennettuna turvallisesti (ympäristömuuttuja, käyttäjän itse nimeämä tiedosto) - sitä ei koskaan kysytä keskustelussa eikä toisteta takaisin.

Laskujen lukeminen

Kaksivaiheinen toimintatapa: ensin haku, sitten tuore yksityiskohtainen luku siitä yhdestä laskusta, jota tarvitaan.

  • list_invoices({integrationId, search?}) - search (enintään 100 merkkiä) hakee palveluntarjoajalta asiakirjan numeron tai yrityksen nimen perusteella; palauttaa Fakturoidilta ensimmäiset 40 ja ABRAlta 50 riviä ilman sivutusta. Jos osumia on liikaa, search on tarkennettava.
  • get_invoice({integrationId, invoiceId}) - invoiceId on list_invoices-kutsusta kopioitu externalId. Palauttaa tuoreimman tilan suoraan palveluntarjoajalta, ei sitä, mitä volai muistaa.

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

status on paid, unpaid, overdue tai unknown; amountDueMinor on kokonaisluku LASKUN OMAN VALUUTAN pienimmässä yksikössä (ei välttämättä CZK) ja null tarkoittaa tuntematonta jäljellä olevaa summaa. Yksityiskohtanäkymässä on lisäksi provider, fetchedAt ja evidence: "provider_response".

status: "unknown" tai puuttuva summa EI KOSKAAN tarkoita maksettua - eikä soittajan oma väite ole maksutodiste. Todisteeksi agentti hyväksyy vain tuoreen get_invoice-vastauksen.

Muistutus Tehtävien kautta

Maksamattomista laskuista muistuttavat massapuhelut hoidetaan osiossa Tehtävät.

Tehtävä, jonka tyyppi on taskType: "invoice", luodaan arvolla source: "integration", ja jokaisella vastaanottajalla (tai koko tehtävällä, kun lasku on kaikille sama) on externalRefs.invoice = {connectionId, externalId, provider?} - connectionId on yhteyden tunniste list_integrations-kutsusta ja externalId laskun tunniste list_invoices-kutsusta. Ilman tätä viitettä create_task/POST /v1/tasks epäonnistuu virheellä validation ja viestillä recipients.externalRefs, eikä tehtävää tallenneta. Jos pakollinen viite puuttuisi jo olemassa olevasta tietueesta, get_task/GET /v1/tasks/{id} ilmoittaa sen kentässä issues, ja start_task kieltäytyy käynnistämästä tehtävää samalla validointivirheellä.

Jokaisella vastaanottajalla on lisäksi kenttä paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - vain luku, järjestelmä johtaa sen viimeisimmästä laskun luvusta palveluntarjoajalta juuri ennen soittoa. Ilman laskuviitettä arvo on not_applicable, luomisen jälkeen tai kun tilaa tai summaa ei voi vahvistaa unknown, muuten Fakturoidin/ABRAn vastauksen mukainen - maksettu lasku saa tehtävän ohittamaan rivin (skipped) ja asettamaan arvon paid. Arvoa disputed järjestelmä ei nykyisin aseta itse, portaali voi vain näyttää sen - se kuuluu julkiseen arvojoukkoon (TaskItem tiedostossa /openapi.json) riitautetun laskun tulevaa manuaalista merkintää varten.

Virheet

  • integration_not_found - Yhteyttä tällä integrationId-arvolla ei ole olemassa tai se ei kuulu tälle tilille.
  • integration_unsupported - Yhteys ei ole laskutusyhteys (esimerkiksi kalenteri), tai Fakturoidia yritetään yhdistää tunnuksilla OAuthin sijaan.
  • integration_unauthorized - Fakturoid tai ABRA on peruuttanut käyttöoikeuden - yhteys on tehtävä uudelleen portaalissa.
  • integration_provider_error - Palveluntarjoaja ei tällä hetkellä vastaa tai palautti virheen - yritä myöhemmin uudelleen ja käsittele laskun tilaa sillä välin tuntemattomana.
  • integration_invalid_query - ABRA hylkäsi search-arvon kenoviivojen tai sekaisin olevien lainausmerkkien vuoksi - yksinkertaista hakua.

Täydellinen taulukko kaikista koodeista on osiossa laskut REST API -viitteessä ja osiossa MCP-virheet.

Turvallisuus

REST API ja MCP eivät koskaan palauta Fakturoidin tai ABRA Flexin käyttöoikeustunnisteita eivätkä salasanoja, ja ne tallennetaan salattuina. Integraation voi irrottaa vain portaalissa tai REST-rajapinnan kautta (DELETE /v1/integrations/{id}) - MCP:ssä siihen ei tarkoituksella ole työkalua, koska toimenpide on peruuttamaton.