Verkkolaskun vastaanottaminen
Tämä ohje käsittelee ostolaskujen automaattista vastaanottoa ja hallintaa Maventan REST API -rajapinnassa. Artikkelissa selvitetään vastaanoton aktivointi ja sulkeminen eri verkoissa sekä opastetaan saapuvien laskujen, laskukuvien ja liitteiden lataaminen Webhook-ilmoitusten ja GET-pyyntöjen avulla. Lisäksi ohje kattaa yleisimpien HTTP-virhetilanteiden käsittelyn.
- Laskujen vastaanoton aktivointi ja sulku
- Laskujen lataaminen Maventasta
- Virhetilanteet ja niiden käsittely
Laskujen vastaanoton aktivointi ja sulku
Tämä ohje käsittelee REST API -rajapinnan käyttöä, SOAP API -käyttäjille on oma SOAP invoice receiving API -ohjeensa.
Maventan REST API mahdollistaa ostolaskujen automatisoidun vastaanoton ja käsittelyn suoraan laskutusohjelmistoon. Rajapinta huolehtii laskujen turvallisesta reitityksestä, sähköisten osoitteistojen päivityksestä sekä automaattisista formaattimuunnoksista eri verkkolaskuverkkojen välillä.
📖 Maventa documentation: Invoice receiving
API-integraatio tekee laskujen vastaanotosta täysin automaattista ja huolehtii yrityksen saavutettavuudesta eri laskutuskanavissa. Laskujen vastaanotto kytketään päälle tai poistetaan käytöstä yrityskohtaisesti verkko-osoitteiden profiileilla rajapintakutsujen kautta.
Vastaanoton aktivointi
Vastaanoton aktivointi muodostaa yritykselle sähköisen laskutusosoitteen ja rekisteröi sen automaattisesti julkisiin hakemistoihin. Rajapinta yhdistää yrityksen maakohtaisiin pankki- ja operaattoriverkkoihin (Visma Network), kansainväliseen Peppol-verkkoon (Peppol Network) sekä skannauspalveluihin (Scan Network).
Yritys näkyy myös laskun vastaanottajana Maventan hakutyökalussa ja lookup metodilla.
Vastaanoton sulku
Tietyn verkon käytöstäpoisto poistaa yrityksen kyseisestä sähköisestä osoitehakemistosta, jolloin toimittajat eivät voi enää lähettää laskuja kyseisen verkon kautta.
Visma Network -rekisteröintiä ei voi poistaa niin kauan kuin mahdolliset Peppol- tai skannausrekisteröinnit ovat aktiivisia. Nämä on deaktivoitava ennen varsinaista vastaanoton sulkua.
ℹ️ Yksityiskohtaiset ja vaiheittaiset ohjeet laskujen vastaanoton kytkemisestä päälle tai sen poistamisesta käytöstä Maventan käyttöliittymässä löytyvät erillisestä tukiartikkelista: Laskujen vastaanotto.
Mikäli laskujen toimittajat yrittävät lähettää verkkolaskuja Maventa-tilille, jolla vastaanotto ei ole aktiivisena, toimittajat saavat tästä omalta verkkolaskuoperaattoriltaan virheilmoituksen.
Laskujen lataaminen Maventasta
Maventa tarjoaa reaaliaikaiset ilmoitukset sekä kyselyrajapinnat saapuvien laskujen noutamiseen:
Reaaliaikaiset ilmoitukset (Webhooks)
Suositeltu tapa seurata saapuvia laskuja on rekisteröidä DOCUMENTS.INVOICE.RECEIVED verkkokutsu. Kun lasku saapuu, Maventa lähettää ilmoituksen (HTTP POST) kohdejärjestelmään.
Lisätietoja on tarkasteltavissa dokumentaatiossa: Webhooks.
Laskujen nouto (GET /v1/invoices/{id})
Saapuneet laskut voidaan ladata järjestelmään ohjelmiston määrittämässä, Maventan tukemassa XML-muodossa. Ajantasaisen listauksen Maventan tukemista XML -formaateista löydät dokumentaatiosta: Supported XML - formats.
Saapuneen laskun tunnisteen (id) perusteella järjestelmästä voidaan ladata:
- Laskun XML-sisältö
- Visuaalinen laskukuva (PDF)
- Laskun mahdolliset liitetiedostot
💡 Suositus: Webhook-ilmoitusten lisäksi taustalla kannattaa ajaa säännöllistä kyselyrutiinia (polling) mahdollisten verkko-ohitusten tai virhetilanteiden varalta.
ℹ️ Yksityiskohtaiset ja vaiheittaiset ohjeet laskujen vastaanoton kytkemisestä päälle tai sen poistamisesta käytöstä Maventan käyttöliittymässä löytyvät erillisestä tukiartikkelista: Laskujen vienti Maventa-tililtä.
Automaattinen petostensuojaus (Detect)
Integroimalla Detect-palvelun saapuville laskuille voidaan suorittaa validointi ja petostentunnistus. Palvelun toimintaan voi tutustua dokumentaatiossa: Detect.
Virhetilanteet ja niiden käsittely
Maventa API ilmoittaa virhetilanteista standardeilla HTTP-tilakoodeilla (400–599). On suositeltavaa, että ohjelmisto käsittelee sekä rajapintavirheet että verkkoyhteyden katkokset.
Tarkempi kuvaus virhetilanteiden käsittelystä on tarkasteltavissa dokumentaatiossa: Error handling.
- Virhevastaukset: HTTP-virhekoodin lisäksi rajapinta palautta JSON-muotoisen virheselitteen (code, message ja details), joka yksilöi virheen syyn.
- Yleisimmät tilakoodit:
- 400 Bad Request: Pyynnön rakenne tai parametrit ovat virheellisiä.
- 401 Unauthorized: Tunnistautuminen epäonnistui tai käyttöoikeus puuttuu.
- 404 Not Found: Pyydettyä resurssia ei löydy.
- 5XX Server Error: Palvelinpään tilapäinen virhe.