Finvoice 3.0

Finvoice on Finanssiala ry:n ylläpitämä suomalainen verkkolaskustandardi. Kirjapro tukee versiota 3.0.

Operaattori

Kirjapro välittää verkkolaskut Maventan (Visma) kautta. Maventa tukee Finvoice 3.0 -sanomia sekä Peppol-verkostoa kansainväliseen laskutukseen.

Maventan ominaisuudet

• Automaattinen reititys — Vastaanottajan verkkolaskuosoite haetaan automaattisesti Y-tunnuksen perusteella (Tieke-rekisteri)
• Vastaanottajahaku — Voit tarkistaa vastaanottajan verkkolaskuosoitteen ennen lähetystä
• Peppol-tuki — Kansainväliset verkkolaskut ilman erillistä sopimusta
• OAuth2-tunnistautuminen — Turvallinen yhteys standardiprotokollalla
• Webhook-ilmoitukset — Reaaliaikainen tieto laskun tilasta (lähetetty, toimitettu, vastaanotettu, virhe)
• Dead-letter-jono — Epäonnistuneet toiminnot käsitellään automaattisesti uudelleen

Huomio

Kirjapro tuki aiemmin APIX-operaattoria (Finago). APIX-tuki on edelleen saatavilla olemassa oleville käyttäjille, mutta uudet yritykset käyttävät Maventaa. Suosittelemme siirtymistä Maventaan parempien ominaisuuksien ja luotettavuuden vuoksi.

Käyttöönotto

1. Siirry Asetukset → Verkkolasku
2. Valitse operaattoriksi Maventa
3. Syötä Maventa-tunnuksesi (company_uuid ja user_api_key)
4. Vahvista yritystiedot (KYC-prosessi)
5. Valmis — voit lähettää ja vastaanottaa verkkolaskuja

Yleiskatsaus

Finvoice-rakenne

<?xml version="1.0" encoding="UTF-8"?>
<Finvoice Version="3.0"
  xmlns="http://www.finvoice.info/finvoice/3.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SellerPartyDetails>...</SellerPartyDetails>
  <BuyerPartyDetails>...</BuyerPartyDetails>
  <InvoiceDetails>...</InvoiceDetails>
  <PaymentInfo>...</PaymentInfo>
  <InvoiceRows>...</InvoiceRows>
</Finvoice>

Pakolliset elementit

SellerPartyDetails (Myyjän tiedot)

<SellerPartyDetails>
  <SellerPartyIdentifier>1234567-8</SellerPartyIdentifier>
  <SellerOrganisationName>Yritys Oy</SellerOrganisationName>
  <SellerPostalAddressDetails>
    <SellerStreetName>Kauppakatu 1</SellerStreetName>
    <SellerTownName>Helsinki</SellerTownName>
    <SellerPostCodeIdentifier>00100</SellerPostCodeIdentifier>
    <CountryCode>FI</CountryCode>
  </SellerPostalAddressDetails>
  <SellerAccountDetails>
    <SellerAccountID IdentificationSchemeName="IBAN">
      FI1234567890123456
    </SellerAccountID>
    <SellerBic IdentificationSchemeName="BIC">NDEAFIHH</SellerBic>
  </SellerAccountDetails>
</SellerPartyDetails>

BuyerPartyDetails (Ostajan tiedot)

<BuyerPartyDetails>
  <BuyerPartyIdentifier>9876543-2</BuyerPartyIdentifier>
  <BuyerOrganisationName>Asiakas Oy</BuyerOrganisationName>
  <BuyerPostalAddressDetails>
    <BuyerStreetName>Asiakaskatu 5</BuyerStreetName>
    <BuyerTownName>Espoo</BuyerTownName>
    <BuyerPostCodeIdentifier>02100</BuyerPostCodeIdentifier>
    <CountryCode>FI</CountryCode>
  </BuyerPostalAddressDetails>
</BuyerPartyDetails>

InvoiceDetails (Laskun tiedot)

<InvoiceDetails>
  <InvoiceTypeCode>INV01</InvoiceTypeCode>
  <InvoiceTypeText>LASKU</InvoiceTypeText>
  <OriginCode>Original</OriginCode>
  <InvoiceNumber>2024001</InvoiceNumber>
  <InvoiceDate>
    <Date Format="CCYYMMDD">20240115</Date>
  </InvoiceDate>
  <InvoiceTotalVatExcludedAmount AmountCurrencyIdentifier="EUR">
    1000.00
  </InvoiceTotalVatExcludedAmount>
  <InvoiceTotalVatAmount AmountCurrencyIdentifier="EUR">
    255.00
  </InvoiceTotalVatAmount>
  <InvoiceTotalVatIncludedAmount AmountCurrencyIdentifier="EUR">
    1255.00
  </InvoiceTotalVatIncludedAmount>
</InvoiceDetails>

Verkkolaskuosoitteet

OVT-tunnus

OVT (Organisaatioiden välinen tiedonsiirto) -tunnus:

0037 + Y-tunnus (ilman väliviivaa)

Esimerkki: 003712345678

Operaattoritunnus

Kirjapro käyttää oletuksena Maventaa (003721291126).

Operaattori	Tunnus	Huomio
Maventa	003721291126	Kirjapron oletusoperaattori
APIX	003723327487	Legacy — ei uusille käyttäjille
CGI	003714377140
Basware	BAWCFI22

ALV-käsittely

VatSpecificationDetails

<VatSpecificationDetails>
  <VatBaseAmount AmountCurrencyIdentifier="EUR">1000.00</VatBaseAmount>
  <VatRatePercent>25.5</VatRatePercent>
  <VatRateAmount AmountCurrencyIdentifier="EUR">255.00</VatRateAmount>
</VatSpecificationDetails>

Verokannat

Koodi	Kanta	Käyttö
S	25,5%	Yleinen
AA	13,5%	Elintarvikkeet
H	10%	Kirjat, lääkkeet
Z	0%	Veroton

Validointi

Kirjapro validoi Finvoice-sanoman ennen lähetystä:

1. XML Schema - Rakenteen oikeellisuus
2. Y-tunnus - Mod 11 -tarkistus
3. IBAN - Mod 97 -tarkistus
4. Viitenumero - Painotettu summa
5. Summat - Verot + veroton = kokonaissumma

Varoitus

Virheellinen sanoma hylätään Maventan toimesta. Kirjapro validoi sanoman automaattisesti ennen lähetystä, mutta tarkista laskun tiedot huolellisesti.

Laskun tilasiirtymät

Maventa raportoi laskun tilan reaaliaikaisesti:

Tila	Kuvaus
Käsittelyssä	Lasku on lähetetty Maventaan
Lähetetty	Maventa on välittänyt laskun vastaanottajan operaattorille
Toimitettu	Vastaanottajan operaattori on vahvistanut vastaanoton
Virhe	Lähetys epäonnistui — tarkista laskun tiedot

Vinkki

Jos lähetys epäonnistuu, Kirjapron dead-letter-jono yrittää toimintoa automaattisesti uudelleen. Tarkista laskun tiedot, jos virhetila jatkuu.

Lisätietoja

• Finanssiala ry - Finvoice
• Maventa API -dokumentaatio
• API Reference