Verkkolaskujen lähettäminen

• Verkkolaskujen lähetys Maventassa
  • Miten verkkolaskujen lähetys toimii?
  • Automaattinen reititys ja toimitustavat
  • Lähetyksen vaiheet ja integraatioprosessi
    • Aineiston testaus ja validointi
    • Laskun lähetys rajapintaan (POST /v1/invoices)
    • Toimitustilan seuranta
  • Saman laskunumeron käytön estäminen
• Operaattorit, verkkoyhteydet ja maakohtaiset toimituskanavat
  • Yleinen reititysjärjestys ja toimituskanavat
  • Maakohtaiset erityispiirteet ja lakisääteiset muodot
• Liitetiedostot verkkolaskuissa
  • Liitteiden toimittaminen eri formaateissa
  • Tekniset rajoitukset ja säännöt
  • Toimitus eri jakelukanavissa
• Laskun kuva ja personointi
• Verkkolaskun lähettäminen ulkomaille ja eri verkoissa
  • Peppol-verkosto
  • Paikalliset ja maakohtaiset verkostot
  • Maventan sisäinen verkko
    • Kansainvälisten verkkolaskujen lähettäminen Maventa-verkossa
• XML-laskuaineiston manuaalinen lähetys ja testaaminen Maventan käyttöliittymässä

---

Maventan myyntilaskujen lähetysrajapinta ja verkkolaskupalvelu mahdollistavat myyntilaskujen automatisoidun toimittamisen suoraan laskutusohjelmistosta.

Verkkolaskujen lähetys Maventassa

On tärkeää huomioida, että Maventa toimii ainoastaan laskuvälityspalveluna, eikä palvelussa itsessään luoda laskuja. Maventan käyttöönotto edellyttää, että käytössä on laskutusohjelmisto, joka kykenee muodostamaan XML-laskuaineistoa jossain Maventan hyväksymistä laskuformaateista. Maventa toimii tällöin automaattisena jakeluverkostona, joka reitittää laskut oikeaan jakelukanavaan ja huolehtii maakohtaisista sekä verkostokohtaisista muotovaatimuksista.

Laskujen lähetys tulee ensisijaisesti tehdä suoraan Maventaan integroidusta laskutusohjelmistosta, jolloin järjestelmä muodostaa ja lähettää laskuaineiston automaattisesti taustalla.

⚠️ Huomio: Maventaan lähetettyä laskua ei voi peruuttaa tai pysäyttää. Tarvittaessa lähettäjän tulee olla suoraan yhteydessä vastaanottajaan, luoda hyvitys- tai peruutuslasku sekä lähettää vastaanottajalle uusi, korjattu lasku.

Miten verkkolaskujen lähetys toimii?

Tämä ohje käsittelee REST API -rajapinnan käyttöä, SOAP API -käyttäjille on oma SOAP invoice sending API -ohjeensa.

Maventan REST API mahdollistaa laskujen automatisoidun käsittelyn ja huolehtii laskujen turvallisesta reitityksestä, sähköisten osoitteistojen päivityksestä sekä automaattisista formaattimuunnoksista eri verkkolaskuverkkojen välillä.

📖 Maventa documentation: Invoice sending

Maventa API tarjoaa yhtenäisen tavan toimittaa myyntilaskuja, hyvityslaskuja ja niiden liitteitä vastaanottajille jakelukanavasta tai maasta riippumatta:

Monikanavainen reititys: Laskut voidaan toimittaa verkkolaskuna maakohtaisissa operaattori- ja pankkiverkoissa, kansainvälisessä Peppol-verkossa, sähköpostitse tai tulostuspalvelun kautta.

Automaattinen reititysjärjestys: Jos verkkolaskuosoite puuttuu tai se on annettu puutteellisesti, Maventa hyödyntää automaattista reititystä toimitustavan varmistamiseksi. Järjestelmä etsii vaihtoehtoista osoitetta Y-tunnuksella ja täsmäyttää tiedot vastaanottajan nimen perusteella. Jos verkkolaskuosoitetta ei löydy, lasku ohjataan sähköpostitse ja toissijaisesti tulostuspalveluun osoitetietojen perusteella.

Automaattiset formaattimuunnokset ja validointi: Laskutusohjelmistosta voidaan lähettää laskuaineisto jossain Maventan tukemista XML-formaateista. Maventa validoi aineiston ja muuntaa sen vastaanottavan operaattorin tukemaan muotoon. Ajantasaisen listauksen Maventan tukemista XML -formaateista löydät dokumentaatiosta: Supported XML - formats.

Liitetiedostot verkkolaskuissa: Liitteitä (esim. PDF, XLSX, JPG) tuetaan 10 MB yksittäiskokoon ja 150 MB kokonaisrajaan asti. Jos vastaanottava verkko tai operaattori (esim. pankkiverkko) ei tue liitteitä, Maventa muuntaa aineiston ja lisää siihen linkin esilläpitopalveluun, josta liitteet ovat ladattavissa.

Virhetilanteet ja suojaus: Mikäli lasku jää virhetilaan (esim. virheellisten osoitetietojen tai yhteensopimattomuuden vuoksi), lähettäjälle muodostetaan virheilmoitus korjaavia toimenpiteitä varten. Järjestelmässä voidaan myös aktivoida suoja-asetus, joka estää samalla laskunumerolla lähettämisen määritetyn suoja-ajan (7vrk) puitteissa.

Automaattinen reititys ja toimitustavat

Lasku toimitetaan ensisijaisesti verkkolaskuna laskun mukana tulevien osoite- ja operaattoritietojen perusteella. Jos tiedot puuttuvat tai ne ovat puutteelliset, Maventa hyödyntää automaattista reititystä toimitustavan varmistamiseksi seuraavassa järjestyksessä:

1. Haku Y-tunnuksella: Vaihtoehtoista verkkolaskuosoitetta etsitään vastaanottajan Y-tunnuksen perusteella.
2. Tietojen täsmäytys: Jos hakutuloksia on useita, sekä Y-tunnuksen että yrityksen nimen on täsmättävä tarkalleen.
3. Sähköpositse toimittaminen: Jos verkkolaskuosoitetta ei löydy, lasku lähetetään sähköpostitse, mikäli sähköpostilaskujen lähetys on sallittu yritystilin asetuksissa, sähköpostireitti on sallittu ja osoite on määritelty laskulle.
4. Postitse toimittaminen: Jos verkko- tai sähköpostiosoitetta ei ole, lasku ohjataan tulostuspalveluun. Tämä edellyttää aktivoitua tulostuspalvelua ja täydellisiä osoitetietoja (katuosoite, postinumero, postitoimipaikka ja maa).

Jos mikään toimitustapa ei ole käytettävissä, lasku siirtyy virhetilaan ja lähettäjä saa automaattisen ilmoituksen lähetysvirheestä. Ilmoitus sisältää ohjeet tilanteen korjaamiseksi, kuten puuttuvien osoitetietojen täydentämisen.

Lähetyksen vaiheet ja integraatioprosessi

Integraatiotasolla myyntilaskujen lähetys ja seuranta pohjautuvat selkeisiin päätepisteisiin (endpoints):

1. Aineiston testaus ja validointi (valinnainen)

Laskuaineiston tarkistaminen ennen lähetystä on valinnaista, sillä Maventa validoi kaikki laskut automaattisesti lähetysprosessin aikana. Validoinnin kutsuminen rajapinnan kautta (POST /v1/validate) auttaa kuitenkin havaitsemaan mahdolliset virheet mahdollisimman varhaisessa vaiheessa ennen varsinaista laskun lähetystä.

Lisätietoja on tarkasteltavissa dokumentaatiossa: Validate before sending. 

2. Laskun lähetys rajapintaan (POST /v1/invoices)

Kaikilla yritystileillä myyntilaskujen lähetys on oletuksena aktiivisena, kunhan yrityksen valtuutus on valmis (company_state on aktiivinen).

Lasku toimitetaan kutsulla POST /v1/invoices, jossa XML-tiedosto (tai liitteet sisältävä ZIP-paketti) lähetetään Base64-enkoodattuna file-parametrissa. Pyynnön mukana annettavat API-parametrit korvaavat aina XML-tiedostossa olevat vastaavat arvot.

Lähetyksen yhteydessä saatava laskutunniste (invoice_id / uuid) tulee aina tallentaa omaan järjestelmään toimitustilan seurantaa varten.

Keskeisiä lähetysmäärityksiä ja parametreja:

• Vastaanottaja ja reititys: Vastaanottajan verkkolaskuosoite (recipient_eia) ja operaattoritunnus (recipient_operator). Tietyn operaattorin määrittäminen verkkolaskuosoitteen oheen pakottaa toimituksen kyseisen verkon kautta.
  Toimitusreittejä voidaan myös estää disabled_routes-parametrilla.
• Toissijaiset toimitustavat: Toissijaiseksi jakelukanavaksi voidaan määrittää sähköposti (recipient_email, sender_comment, email_settings) tai tulostuspalvelu.
• Laskukohtaiset asetukset: Tulostuspalvelun määrityksiä, kieliasetuksia (lang) sekä maakohtaisia laskutuskenttiä (esim. B2C-laskutuksen vaatimat kentät) voidaan ohjata laskukohtaisesti.
• Tuplalaskujen estäminen: Kaksoislähetykset voidaan estää joko käyttämällä omaa laskukohtaista UUID-tunnistetta (uuid) tai aktivoimalla yritystason asetus (stop_duplicate_numbers), joka hylkää saman laskunumeron 7 päivän sisällä.
• Erityistoiminnot: Asetuksella prevent_routing lasku voidaan merkitä tilaan SENT ilman sen toimittamista vastaanottajalle (käytetään mm. muistutus- ja perintätoimeksiannoissa).

3. Toimitustilan seuranta

Laskun tilamuutoksista (kuten toimitettu, virheessä tai hylätty) saadaan reaaliaikainen tieto rekisteröimällä DOCUMENTS.INVOICE.SENT tai DOCUMENTS.INVOICE.ERROR verkkokutsu.

Lisätietoja on tarkasteltavissa dokumentaatiossa: Follow up and handle errors.

Saman laskunumeron käytön estäminen

Maventa käyttää laskun numeroa laskun yksilöimiseen. Moninkertaisen lähetyksen ja sekaannusten välttämiseksi järjestelmässä voidaan estää saman laskunumeron käyttö uudestaan seitsemän (7) päivän sisällä aiemmasta lähetyksestä. Suoja-ajan kuluttua samaa numeroa voi tarvittaessa käyttää uudelleen esimerkiksi muistutuslaskussa.

Määritykset ja ohjeet toiminnon aktivointiin löytyvät dokumentaatiosta täältä (API): Preventing duplicate invoices ja tukiartikkelista täältä (käyttöliittymä): Yleiset asetukset laskujen lähetykselle.

Operaattorit, verkkoyhteydet ja maakohtaiset toimituskanavat

Maventa huolehtii laskujen reitityksestä ja formaattimuunnoksista maakohtaisten sekä operaattorikohtaisten vaatimusten mukaisesti. Laskujen välitys onnistuu useimmille kotimaisille ja kansainvälisille verkko- sekä pankkioperaattoreille.

Yleinen reititysjärjestys ja toimituskanavat

B2B- ja B2G-laskutuksessa Maventa pyrkii toimittamaan laskun aina parasta mahdollista sähköistä väylää pitkin. Reitityksen yleinen prioriteetti muodostuu seuraavista kanavista:

1. Maventan sisäinen verkko: Välitön toimitus Maventan asiakkaiden välillä riippumatta yritysten maantieteellisestä sijainnista.
2. Maakohtaiset operaattori- ja viranomaisverkot: Alueelliset ja kansalliset verkkolaskuverkostot (esim. Verkkolaskufoorumi Suomessa, InExchange ja Ruotsin operaattoriverkko, Nemhandel/Sproom Tanskassa).
3. Pankkiverkko (vain Suomessa): Kotimainen laskujen välitys Finvoice-muodossa pankkiverkoston kautta.
4. Kansainvälinen Peppol-verkosto: Rajat ylittävä ja kansainvälinen verkkolaskutus Peppol-rekisteröidyille vastaanottajille.
5. Toissijaiset lähetyskanavat (sähköposti ja tulostuspalvelu): Jos sähköistä verkkolaskuosoitetta ei tavoiteta, lasku voidaan reitittää sähköpostitse tai ohjata tulostuspalveluun fyysistä postitusta varten.

Maakohtaiset erityispiirteet ja lakisääteiset muodot

• Kuluttajalaskutus (B2C): Suomessa, Ruotsissa ja Norjassa hyödynnetään verkkopankkeja ja sähköisiä postilaatikoita (esim. Kivra, Vipps), kun taas muissa maissa B2C-laskut toimitetaan pääosin sähköpostitse tai postitse.
• Tanska (Nemhandel & Peppol): Kotimaisessa liikenteessä käytetään Nemhandel-verkkoa ja ulkomaan liikenteessä Peppol-verkkoa (edellyttää täydellistä Endpoint ID -tunnusta ja Peppol BIS 3.0 -tukea).
• Puola (KSeF): Laskut raportoidaan KSeF-järjestelmään FA(3)-formaatissa. Kotimaassa KSeF vastaa jakelusta; ulkomaankaupassa lasku välitetään KSeF-raportoinnin jälkeen Peppol-verkossa.
• Italia (SDI): Laskut raportoidaan SDI-järjestelmään FatturaPA-formaatissa (vaatii Maventan koodin 61M0PS7). SDI hoitaa kotimaan jakelun; ulkomaan liikenne jatkaa Peppol- tai sisäiseen verkkoon SDI-hyväksynnän jälkeen.

Liitetiedostot verkkolaskuissa

Liitetiedostoja (kuten laskun kuvia ja tausta-asiakirjoja) voidaan toimittaa verkko-, sähköposti- ja tulostuspalvelulaskujen mukana. Maventa mukauttaa liitteiden toimitustavan automaattisesti vastaanottavan verkon ja jakelukanavan vaatimusten mukaisesti.

Mukaan liitettävä PDF-laskukuva on valinnainen – XML-laskun on aina oltava sellaisenaan täydellinen. Jos toimitustapa edellyttää laskun kuvaa (kuten tulostuspalvelu) eikä sitä ole liitetty mukaan, Maventa muodostaa visuaalisen laskukuvan automaattisesti XML-aineiston pohjalta.

Liitteiden toimittaminen eri formaateissa

Liitteiden sisällyttämistapa riippuu käytettävästä laskuformaatista:

• UBL-pohjaiset formaattit (esim. Peppol BIS 3.0): Liitteet upotetaan suoraan XML-tiedoston sisään. Varsinainen laskun kuva tunnistetaan kuvauksesta <cbc:DocumentDescription>CommercialInvoice</cbc:DocumentDescription>
• Muut formaatit (esim. Finvoice 3.0): Liitteet pakataan samaan ZIP-tiedostoon XML-laskun kanssa. Laskun kuva tunnistetaan siitä, että sillä on täsmälleen sama tiedostonimi kuin XML-laskulla (esim. 12345.xml ja 12345.pdf)

Tekniset rajoitukset ja säännöt

• Kokorajat: Yksittäisen liitteen enimmäiskoko on 10 MB ja koko lähetyspaketin enimmäiskoko 100 MB (jotkin vastaanottavat operaattorit saattavat rajoittaa liitteet 5 MB:iin).
• Tiedostomuodot: Tuettuja muotoja ovat mm. pdf, tif, jpg, png, txt, xlsx, doc ja csv. PDF-tiedostojen tulee olla suojaamattomia ilman salasanasuojausta.
• Tiedostonimen muotoilu: Nimessä sallitaan vain kirjaimet (A–Z), numerot (0–9), piste (.) ja alaviiva (_). Erikoismerkit ja skandinaaviset merkit (å, ä, ö) ovat kiellettyjä, ja nimen enimmäispituus on 50 merkkiä.

Toimitus eri jakelukanavissa

• Tulostuspalvelu: Tukee liitteitä ja käyttää toimitettua suojattamatonta PDF-kuvaa tai automaattisesti generoitiua laskupohjaa.
• Pankkiverkko ja operaattorit ilman liitetukea: Jos vastaanottava verkko ei tue liitteitä, Maventa korvaa ne linkillä esilläpitopalveluun, josta vastaanottaja voi ladata liitteet.

Laskun kuva ja personointi

Laskutuksessa käytetään ensisijaisesti lähettävän laskutusohjelmiston tuottamaa PDF-laskukuvaa. Tarvittaessa tulostuspalvelussa voidaan hyödyntää omaa PDF-kuvaa tai Maventan luomaa laskupohjaa voidaan personoida yrityksen logolla.

Yksityiskohtaiset ohjeet oman laskukuvan ja logon käyttöönottoon löytyvät dokumentaatiosta täältä (API): Configure account settings ja erillisestä tukiartikkelista täältä (käyttöliittymä): Laskun kuvan asetukset.

Verkkolaskun lähettäminen ulkomaille ja eri verkoissa

Maventa tukee useita kansainvälisiä ja alueellisia jakeluverkkoja sekä huolehtii formaattimuunnoksista automaattisesti.

Peppol-verkosto

Euroopassa ja kansainvälisesti verkkolaskujen välityksessä hyödynnetään laajasti Peppol-verkostoa. Kaikki Peppolin kautta kulkevat laskut toimitetaan PeppolBIS-formaatissa. Kun lasku lähetetään Maventasta Peppol-verkostoon, se muunnetaan automaattisesti PeppolBIS-muotoon alkuperäisestä laskuformaatista riippumatta.

Paikalliset ja maakohtaiset verkostot 

Maventa tukee alueellisia operaattori- ja pankkiverkkoja sekä maakohtaisia laskuformaatteja (kuten Finvoice, TEAPPS, Svefaktura ja OIOUBL). Maventa muuntaa lähtevät laskut aina vastaanottavan operaattorin edellyttämään muotoon – voit esimerkiksi lähettää Finvoice-aineistoa ruotsalaiselle vastaanottajalle, ja Maventa huolehtii sen muuntamisesta vastaanottajan operaattorin tukemaan formaattiin.

Maventan sisäinen verkko

Verkkolaskujen lähettäminen ulkomaisille yrityksille on erityisen helppoa ja nopeaa silloin, kun sekä lähettäjä että vastaanottaja ovat Maventan asiakkaita. Tällöin lasku liikkuu Maventan sisäisessä verkossa maantieteellisestä sijainnista riippumatta.

Kansainvälisten verkkolaskujen lähettäminen Maventa-verkossa

Kun sekä lähettäjä että vastaanottaja käyttävät Maventaa laskuoperaattorinaan, laskun reitittämiseen käytetään aina Maventan sisäisen verkon määrityksiä.

Reititysohje ja tekniset tiedot:

1. Varmista vastaanottajan Maventa-asiakkuus: Tarkista, että vastaanottaja on Maventan asiakas.
2. Käytä oikeaa operaattoritunnusta: Käytä aina Maventan operaattoritunnusta yritysten maantieteellisestä sijainnista riippumatta.
3. Syötä tiedot laskutusohjelmistoon: Syötä seuraavat reititystiedot laskutusohjelmistosi asiakaskortille tai laskun reititystietoihin:

Kenttä	Arvo
Operaattori	Maventa
Operaattori-/välittäjätunnus	003721291126
Verkkolaskuosoite	Vastaanottajan yksilöllinen osoite (löytyy osoitehausta)

XML-laskuaineiston manuaalinen lähetys ja testaaminen Maventan käyttöliittymässä

Mikäli XML-muotoinen laskuaineisto halutaan lähettää tai testata suoraan Maventan käyttöliittymästä, käyttäjällä tulee olla ADMIN-tason käyttöoikeudet.

• Laskun lähetys: Valmiiksi luodun XML-laskuaineiston voi ladata ja lähettää käyttöliittymästä. Toiminto ei tue liitetiedostoja (esim. PDF). Lähetetyn laskun tilaa voi seurata Lähetetyt laskut -välilehdeltä.
• Aineiston testaus: XML-tiedoston teknisen ja sisällöllisen yhteensopivuuden voi testata ennakkoon ilman laskun lähettämistä tai tallentamista järjestelmään. Testaus on maksutonta, ja se antaa välittömän palautteen mahdollisista rakenteellisista virheistä.

Tarkat vaiheittaiset ohjeet laskujen manuaaliseen lähetykseen ja testaamiseen löytyvät erillisestä tukiartikkelista: Laskutyökalut.