Laskujen lähettäminen ja vastaanottaminen Peppol-verkon kautta

Peppol on eurooppalainen verkko jäsenneltyjen verkkolaskujen vaihtamiseen yritysten ja julkishallinnon organisaatioiden välillä. Jokainen lasku kulkee lähettäjän tukipisteestä vastaanottajan tukipisteeseen. Nordlet muodostaa Peppol BIS Billing 3.0 -muotoiset laskut ja hyvityslaskut sekä lähettää ja vastaanottaa niitä yrityksen oman tukipistetilinsä kautta.

Peppol asettaa säännökset sille, miten tukipisteet vaihtavat asiakirjoja keskenään, mutta ei sille, miten ohjelmistosi viestii oman tukipisteesi kanssa, sillä jokaisella palveluntarjoajalla on oma ohjelmistorajapintansa (API). Nordlet toimii seuraavien palveluntarjoajien kanssa:

Palveluntarjoaja	Lähetys	Toimituksen tila	Vastaanotto
Recommand	kyllä	verkkohukilla (webhook) ja pyynnöstä	kyllä
Storecove	kyllä	vain verkkohukilla (webhook)	kyllä
e-invoice.be	kyllä	verkkohukilla (webhook) ja pyynnöstä	kyllä

Ilman tukipistettä Nordlet muodostaa silti jokaisesta laaditusta laskusta ja hyvityslaskusta Peppol-tiedoston, jonka voit ladata ja toimittaa eteenpäin muulla tavoin; se ei kuitenkaan lähetä tai vastaanota mitään automaattisesti.

Mitä tarvitset

• Tilin joltakin yllä mainitulta palveluntarjoajalta siten, että yrityksesi on rekisteröity Peppol-verkkoon kyseisen palvelun kautta. Jokainen palveluntarjoaja veloittaa palvelustaan hinnastonsa mukaisesti.
• Nordletissa yrityksen Y-tunnuksen tai arvonlisäverotunnisteen taikka Peppol-tunnuksen (Tili → Yritykset → Peppol-tunnus). Myös jokaisella asiakkaalla, jolle lähetät laskuja, on oltava jokin näistä kumppanikortillaan.

Tukipisteen yhdistttäminen

Avaa Tili → Vaatimustenmukaisuus → EU → Peppol-tukipiste, valitse palveluntarjoajasi kentässä Palveluntarjoaja, täytä kyseisen palveluntarjoajan kentät alla annettujen ohjeiden mukaisesti ja tallenna tiedot. Jätä kenttä Rajapinnan perusosoite (API base URL) tyhjäksi, ellei palveluntarjoajasi ole antanut sinulle muuta osoitetta. Tallennuksen jälkeen sivulla näkyy yrityksesi verkkohukin osoite (Webhook URL) muodossa https://api.nordlet.com/v1/peppol/webhooks/{provider}/{companyId}, jossa {provider} on recommand, storecove tai e-invoice-be ja {companyId} on yrityksesi tunniste. Jokaisella Nordlet-yrityksellä on oma verkkohukin osoitteensa.

Nordlet hyväksy verkkohuksuutsun vain, jos se todistaa tuntevasi verkkohukin salasanan (webhook secret), joten kutsut, jotka eivät tule tukipistetililtäsi, hylätään. Nordlet ottaa yhteyttä julkisiin internetosoitteisiin vain kutsuessaan tukipistettäsi.

Recommand

1. Avaa Recommandissa yrityksesi tiedot ja kopioi sen yritystunnus (company ID) kenttään Tukipisteen tilitunnus (Account ID at the access point).
2. Luo Recommandissa rajapinta-avain (API key) ja kopioi avain sekä sen salasana kenttiin Rajapinta-avain (API key) ja Rajapinta-avainten salasana (API secret).
3. Keksi pitkä satunnainen merkkijono, jonka vain sinä ja Recommand tiedätte, ja syötä se kenttään Verkkohukin salasana (Webhook secret). Tallenna.
4. Luo Recommandissa yrityksellesi verkkohuk (webhook) käyttäen Nordletin näyttämää verkkohukin osoitetta ja samaa verkkohukin salasanaa.

Recommand allekirjoittaa jokaisen verkkohuksuutsun kyseisellä salasanalla.

Storecove

1. Luo Storecovessa yrityksellesi oikeudellinen yksikkö (legal entity), joka on asetettu lähettämään ja vastaanottamaan asiakirjoja, ja kopioi sen tunniste kenttään Tukipisteen tilitunnus (Account ID at the access point).
2. Luo Storecovessa kohdassa API Keys rajapinta-avain ja kopioi se kenttään Rajapinta-avain (API key). Jätä kenttä Rajapinta-avainten salasana (API secret) tyhjäksi.
3. Keksi pitkä satunnainen merkkijono ja syötä se kenttään Verkkohukin salasana (Webhook secret). Tallenna.
4. Määritä Storecovessa push-verkkohuk Nordletin näyttämään osoitteeseen, joka on suojattu HTTP Basic -todennuksella: mikä tahansa käyttäjänimi ja verkkohukin salasana salasanana.

Storecovella ei ole erillistä kutsua lähetetyn asiakirjan tilaa varten, joten Storecoven kanssa toimituksen tila tulee ainoastaan sen verkkohukin kautta eikä laskusivulla ole painiketta Tarkista Peppol-tila. Storecoven testiympäristötili (sandbox) lähettää laskut Peppol-testiverkkoon, ja tuotantokäyttöön tarkoitetut rajapinta-avaimet saa Storecoven tuesta.

e-invoice.be

1. Kopioi e-invoice.be-sovelluksen kohdassa API Settings yrityksesi rajapinta-avain kenttään Rajapinta-avain (API key). Jätä kentät Tukipisteen tilitunnus (Account ID at the access point) ja Rajapinta-avainten salasana (API secret) tyhjiksi. Tallenna.
2. Luo verkkohuk e-invoice.be-rajapinnan kautta (POST https://api.e-invoice.be/api/webhooks/) käyttäen Nordletin näyttämää verkkohukin osoitetta sekä tapahtumia document.received, document.sent ja document.sent.failed.
3. Kopioi rajapinnan uudelle verkkohukille palauttama secret-arvo Nordletin kenttään Verkkohukin salasana (Webhook secret) ja tallenna uudelleen.

e-invoice.be allekirjoittaa jokaisen verkkohuksuutsun kyseisellä salasanalla. e-invoice.be-testiyritys lähettää lähetettäväksi tarkoitetut asiakirjat sähköpostitse sen sijaan, että se lähettäisi ne Peppol-verkon kautta.

Laskun lähettäminen

1. Laadi lasku tai hyvityslasky.
2. Tarkista, että asiakkaan kumppanikortilla on Peppol-tunnus, arvonlisäverotunniste tai Y-tunnus.
3. Napsauta laskusivun Toimitus-osiossa painiketta Lähetä Peppol-verkon kautta ja vahvista toiminto. Toimitusosio näkyy laadituilla laskuilla, joita ei ole vielä maksettu, ja painike näkyy vain silloin, kun tukipiste on yhdistetty.

Nordlet muodostaa Peppol-tiedoston ja toimittaa sen tukipisteellesi. Tämän jälkeen laskusivulla näkyy Peppol-toimitus-osio:

Tila	Merkitys
pending	Toimitettu tukipisteelle; asiakkaan tukipiste ei ole vielä vahvistanut vastaanottoa
delivered	Asiakkaan tukipiste on vahvistanut laskun vastaanoton
rejected	Asiakas on hylännyt laskun; syy näkyy tilan alapuolella
failed	Laskua ei voitu toimittaa; syy näkyy tilan alapuolella, jos tukipiste on ilmoittanut sen

Tila päivittyy automaattisesti, kun tukipiste ilmoittaa muutoksesta verkkohukkinsa kautta. Painike Tarkista Peppol-tila pyytää senhetkisen tilan välittömästi Recommandilta tai e-invoice.be-palvelusta. e-invoice.be-palvelun osalta se lukee myös asiakkaan laskuvastauksen, ja hylkäys (vastauskoodi RE) näkyy tilana hylätty (rejected). Hylätyn tai epäonnistuneen laskun voi lähettää uudelleen, kun olet korpannut virheen syyn. Jos tukipiste hylkää laskun suoraan esimerkiksi siksi, että asiakas ei ole rekisteröitynyt Peppol-verkkoon, Nordlet näyttää syyn ja lasku jää lähettämättä.

Laskusivun yläreunassa oleva painike Peppol XML lataa saman Peppol-tiedoston ilman sen lähettämistä.

EU:n sisäisessä myynnissä laskun päivämäärä toimii toimituspäivänä ja asiakkaan maa toimitusmaana Peppol-sääntöjen edellyttämällä tavalla.

Laskujen vastaanottaminen

Kun tukipiste ilmoittaa vastaanotetusta asiakirjasta verkkohukinsa kautta, Nordlet lataa Peppol-tiedoston tukipisteestä. Yrityksesi vastaanottamat laskut ja hyvityslaskut näkyvät kohdassa Ostot → Asiakirjojen käsittely, ja ne on merkitty vastaanotetuiksi Peppol-verkon kautta lähettäjän Peppol-tunnukselta. Nordlet lukee Peppol-tiedoston itse, joten vastaanottaminen ei kuluta asiakirjojen tunnistuskrediittejä.

1. Avaa vastaanotettu asiakirja.
2. Tarkista toimittaja, päivämäärät ja rivit; valitse toimittaja kumppaneistasi tai luo uusi.
3. Napsauta Tallenna luonnokseksi. Nordlet luo ostolaskuluonnoksen tai vastaanotetun hyvityslaskun tapauksessa ostohyvityslaskuluonnoksen, johon alkuperäinen Peppol-tiedosto on liitetty. Käsittele se kirjanpidossa kuten mikä tahansa muu ostolasku.

Nordletin ostolaskun rivit eivät voi olla negatiivisia. Koko asiakirjaa koskevat alennukset, lisämaksut ja negatiiviset rivit kohdistetaan niille riveille, joilla on sama arvonlisäverokanta. Summa, jota mikään saman arvonlisäverokannan rivi ei voi kattaa, kuten palautettu tuote arvonlisäverokannalla, jolle laskussa ei ole muita rivejä, näytetään toisessa taulukossa: vastaanotetun laskun kohdalla Hyvityslaskun rivit tai vastaanotetun hyvityslaskun kohdalla Laskun rivit. Kyseiset rivit tallennetaan samalle toimittajalle toisena asiakirjana: uutta laskua vastaavana ostohyvityslaskuna, jonka numerona on „-CR“, tai ostolaskuna, jonka numerona on „-INV“. Nämä kaksi asiakirjaa muodostavat yhdessä vastaanotetun asiakirjan loppusummat.

Sen tarkistaminen, onko asiakas Peppol-verkossa

Kutsu POST /v1/peppol/participants/lookup parametrilla partnerId tai participantId (muodossa „<järjestelmä>:“) kysyy Peppol-verkolta, onko vastaanottaja rekisteröitynyt ja mitä asiakirjoja se hyväksyy. Tämä toimii ilman tukipistettäkin.

Toimintojen suorittaminen rajapinnan kautta

Tehtävä	Kutsu
Tukipisteen yhdistttäminen	POST /v1/declarations/configs/update, jossa system: "peppol" ja config-kentässä provider (recommand, storecove tai e-invoice-be), accountId, apiKey, apiSecret, webhookSecret sekä valinnainen apiBaseUrl
Tukipisteen verkkohukin vastaanottaminen	POST /v1/peppol/webhooks/{provider}/{companyId}, jota tukipiste kutsuu
Peppol-tiedoston lataaminen	POST /v1/sales/invoices/peppol-xml
Lähettäminen	POST /v1/sales/invoices/peppol-send (palauttaa virheen 422 ilman tukipistettä)
Toimituksen tilan lukeminen	POST /v1/sales/invoices/peppol-status (palauttaa virheen 422 Storecoven kanssa); laskut sisältävät kentät peppolMessageId, peppolStatus, peppolDetail, peppolSentAt, peppolCheckedAt
Vastaanotettujen asiakirjojen hakeminen	POST /v1/capture/documents/list; vastaanotetuilla asiakirjoilla on provider: "peppol" ja senderId
Asiakirjan muuntaminen ostolaskuksi	POST /v1/capture/documents/confirm parametrilla oppositeLines toista asiakirjaa varten

Verkkohuktitapahtumat: sale_invoice.peppol_sent, sale_invoice.peppol_delivered, sale_invoice.peppol_rejected, sale_invoice.peppol_failed ja document_capture.peppol_received. Katso virheenkäsittelyä, idempotenssia ja verkkohukkeja koskevat ohjeet kohdasta Rajapinnan käytännöt.