Asiakirjat
Laskut ja hyvityslaskut
Plus itse laskutus ja laskujen vastaukset
Muodot
JSON tai UBL XML
UBL 2.1 -pohjainen, yksi asiakirja kutakin pyyntöä kohti
Tapahtumat
Allekirjoitetut webhookit
Vastaanotettu, toimitettu, viivästynyt ja epäonnistunut
Saatavuus
99,8 % kuukaudessa
Sopimusperusteinen, palvelupisteillä
Lähetä lasku yhdessä pyynnössä
Lähetä lasku JSON- tai UBL XML -muodossa tilisi lähtevän liikenteen päätepisteeseen. Qvalia tarkistaa sen, etsii vastaanottajan Peppol-järjestelmästä ja toimittaa laskun. Hyvityslaskut, itselaskutusasiakirjat ja laskuvastaukset käsitellään samalla tavalla.
- Testausympäristö osoitteessa api-test.qvalia.com, tuotantoympäristö osoitteessa api.qvalia.com
- API-avain Authorization-otsikossa tai lyhytaikainen tunnus (JWT)
- Idempotency-Key-otsikko tekee uudelleenkokeiluista turvallisia
● ● ●
Sandbox-pyyntö: lähetä lasku
curl -X POST \
"https://api-test.qvalia.com/transaction/$ACCOUNT_REG_NO/invoices/outgoing" \
-H "Authorization: $QVALIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d @invoice.jsonMiten lasku etenee API:n kautta
Järjestelmänne toimii yhden sovellusrajapinnan (API) avulla. Qvalia ylläpitää sen taustalla toimivaa Peppol-yhteyspistettä.
1. Lähetä
Lähetä yksi asiakirja kutakin pyyntöä kohti. Jos tiedot ovat virheellisiä tai vastaanottajaa ei ole rekisteröity kyseiselle asiakirjatyypille eikä muita toimituskanavia ole määritetty, API palauttaa vakiovirhekoodin 422 ennen kuin mitään lähetetään.
2. Tarkista ja toimita
Qvalia tarkistaa asiakirjan sovellettavien Peppol-sääntöjen mukaisesti, etsii vastaanottajan liityntäpisteen ja toimittaa asiakirjan AS4-protokollan kautta.
3. Seuraa tilannetta
Webhookit ilmoittavat toimitusten tilasta, käynnissä olevista uudelleenkokeiluista ja epäonnistumisista. Tila-päätetapa palauttaa kunkin asiakirjan viimeisimmän tilan ilman asiakirjan sisältöä.
4. Vastaanota
Saapuvat laskut ja vastaukset odottavat saapuvien päänkohtien päässä. Lukupäänkohta palauttaa lukemattomat asiakirjat ja merkitsee ne luetuiksi, joten seuraava kutsu palauttaa vain uudet asiakirjat.
Laskudokumentit ja päätepisteet
Jokainen polku alkaa /transaction/{accountRegNo}, tilisi rekisteröintinumero. Jokaisella asiakirjatyypillä on lähtevät ja saapuvat päätepisteet, lukematonta asiakirjaa varten tarkoitettu lukupäätepiste sekä tilapäätepiste.
| Asiakirja | Päätepiste | Peppol-määrittely |
| Lasku | /invoices | Peppol BIS Billing 3.0 |
| Luottoilmoitus | /creditnotes | Peppol BIS Billing 3.0 |
| Itse laskutettava lasku | /selfbillinginvoices | Peppol BIS -itse laskutus |
| Itse laskutettava hyvityslasku | /selfbillingcreditnotes | Peppol BIS -itse laskutus |
| Laskun vastaus | /invoiceresponses | Peppol BIS Invoice Response |
| Vastaus viestitasolla | /messagelevelresponses | Peppol BIS Message Level Response |
Se, mitä asiakirjatyyppejä tilisi käyttää, riippuu palvelusta ja tilauksesta. Pyyntö- ja vastausmallit löytyvät Lasku-API:n ja Hyvityslasku-API:n ohjeista. Kaikki Qvalian API:t löytyvät kohdasta Peppol-API:t ja kehittäjätyökalut.
Tarkista vastaanottaja ennen lähettämistä
Tarkista osallistujan tunniste ( Peppol ID ) ennen laskun lähettämistä. Vastauksesta käy ilmi, onko osallistuja rekisteröitynyt Peppol-verkostoon ja minkä tyyppisiä asiakirjoja se voi vastaanottaa, jolloin järjestelmäsi voi ilmoittaa puuttuvasta tai virheellisestä tunnisteesta ennen kuin verkosto hylkää laskun.
- Rajoita tarkistus yhteen asiakirjatyyppiin käyttämällä
docTypeRoot, esimerkiksiInvoicetaiCreditNote - Peppol ID on järjestelmä ja tunniste, esimerkiksi
0007:1234567890 - Samat perus-URL-osoitteet ja tunnistautumistapa kuin Transaction API:ssa
● ● ●
Sandbox-pyyntö: vastaanottajan haku
curl \
"https://api-test.qvalia.com/account/$ACCOUNT_REG_NO/action/lookup/peppol/0007:1234567890?docTypeRoot=Invoice" \
-H "Authorization: $QVALIA_API_KEY"Suunniteltu tuotantointegraatioihin
Ne yksityiskohdat, jotka ratkaisevat, toimiiko integraatio myös suurilla volyymeillä, on kaikki dokumentoitu API-ohjeistossa.
- Turvalliset uudelleenkokeilut
Lähetä idempotenssiavain, jolloin toistettu pyyntö palauttaa alkuperäisen vastauksen sen sijaan, että luotaisiin toinen lasku. - Allekirjoitetut webhookit
Jokaisella tapahtumalla on tapahtumatunnus, ja kun olet määrittänyt allekirjoitussalaisuuden, myös allekirjoitus, jonka voit tarkistaa. - Tapahtuman uusinta 30 päivän ajan
Voit hakea minkä tahansa toimitetun tapahtuman uudelleen sen tunnuksen perusteella, esimerkiksi jos järjestelmässäsi on ollut käyttökatkos. - Tila ilman sisältöä
Täsmää suuria tietomääriä kevyillä tilatiedoilla, jotka on suodatettu päivämäärän, asiakirjan tunnuksen tai päivitysajan mukaan. - Käyttörajojen tyhjentäminen
Rajoitukset lasketaan tilikohtaisesti, ja 429-vastaus kertoo, kuinka kauan sinun on odotettava. - Liitteet
Lisää PDF-tiedostoja ja kuvia viestin sisään. Koko pyyntö, liitteet mukaan lukien ja Base64-koodattuna, ei saa ylittää Peppolin 100 Mt:n rajaa.
Yksi lasku, jokaiselle vastaanottajalle sopiva muoto
Lähetä lasku kerran. Qvalia tarkistaa sen, etsii vastaanottajan ja toimittaa sen Peppol-verkossa Peppol- BIS Billing -3.0- tai Peppol-PINT-muodossa. Jos vastaanottaja ei kuulu Peppol-verkkoon, Qvalia voi toimittaa laskun EDI:n kautta, PDF-tiedostona sähköpostitse, tulostettuna tai valituilla markkinoilla B2C-verkkopankkien kautta. Nämä ovat lisätoimituskanavia, eivät Peppol-määrityksiä. Katso, mitä yritysviestimuotoja Qvalia tukee.
Jos järjestelmäsi ei pysty tuottamaan Peppol BIS -muotoista laskua, lataa lasku siinä muodossa, jossa se jo on: Svefaktura 1.0, EDIFACT INVOIC, cXML, Finvoice 3.0, XRechnung, CII tai ZUGFeRD- ja Factur-X-muotoinen XML. Qvalia muuntaa sen Peppol- BIS Billing 3.0 -muotoon, tarkistaa sen oikeellisuuden ja lähettää sen. Katso ohjeet laskujen lähettämisestä nykyisessä muodossasi.
Valitse lähtöpisteesi
Ohjelmistoalustat
Sisäänrakennettu Peppol
Tarjoa sähköistä laskutusta omille asiakkaillesi. Partner API luo heidän tilinsä ja Peppol-tunnuksensa, ja Invoicing API välittää heidän asiakirjansa.
ERP- ja taloushallinnon tiimit
Peppol-yhteyspiste
Yhdistä ERP- tai taloushallintojärjestelmäsi Peppoliin sovellusrajapinnan (API), SFTP:n tai valmiin liitännän avulla.
Kehittäjät
Pikaopas
Siirry API-avaimesta ensimmäiseen sandbox-laskuusi askel askeleelta pyyntöesimerkkien avulla.
Laskutus-API:n usein kysytyt kysymykset
Mikä on sähköisen laskutuksen sovellusrajapinta (API)?
Sähköisen laskutuksen sovellusrajapinnan (API) avulla ohjelmistosi voi lähettää ja vastaanottaa jäsenneltyjä sähköisiä laskuja ilman, että sen tarvitsee itse luoda verkkoyhteyttä. Qvalian laskutus-API:n avulla järjestelmäsi lähettää laskut JSON- tai UBL XML -muodossa, ja Qvalia tarkistaa niiden oikeellisuuden ja toimittaa ne Peppol-verkon kautta.
Mitä laskuasiakirjoja voin lähettää ja vastaanottaa?
Laskut, hyvityslaskut, itse laskutetut laskut ja hyvityslaskut sekä laskuvastaukset, joista jokaisella on lähetys- ja vastaanottopisteet. Se, mitä asiakirjatyyppejä tilisi käyttää, riippuu palvelusta ja tilauspaketista.
Pitääkö minun tuntea Peppol BIS, jotta voin käyttää sovellusrajapintaa?
Asiakirjasi noudattavat Peppol-standardia BIS Billing 3.0, ja ne ovat UBL 2.1 -pohjaisia JSON- tai XML-muodossa. Esimerkkitiedot osoitteessa api.qvalia.io esittävät täydellisen laskun, ja validointivirheet osoittavat korjattavan säännön. Katso kohta ”Kuinka Peppol-validointi toimii”.
Onko siellä hiekkalaatikkoa?
Kyllä. Api-test.qvalia.com-sivuston testausympäristö käyttää omaa API-avaintaan, joten voit testata omia järjestelmiäsi vaikuttamatta todellisiin asiakkaisiin. API- ja testausympäristön käyttöoikeudet sisältyvät Connect- Medium -pakettiin.
Miten voin välttää saman laskun lähettämisen kahdesti?
Lähetä jokaisen lähetyksen mukana Idempotency-Key-otsikko. Jos toistat pyynnön, esimerkiksi aikakatkaisun jälkeen, API palauttaa alkuperäisen vastauksen sen sijaan, että luo toisen dokumentin. Uusi lähetys, jossa on sama dokumenttitunnus ja vastaanottaja, palauttaa virhekoodin 409 Conflict, ellet valitse korvaamista.
Mistä tiedän, että lasku on toimitettu?
Tilaa toimitus- ja virhetapahtumia koskevat webhookit tai tarkista tilapäätepisteen tila. Webhookia, jota päätepisteesi ei hyväksy, ei lähetetä uudelleen, joten varmista turvallisuuden vuoksi tilan säännöllinen tarkistaminen. Kaikki toimitetut tapahtumat ovat haettavissa uudelleen 30 päivän ajan.
Miten vastaanotan saapuvat laskut?
Tilaa uuden asiakirjan webhook ja hae sitten lasku saapuvien viestien päätepisteestä. Lukupäätepiste palauttaa lukemattomat laskut ja merkitsee ne luetuiksi.
Mitä laskutus-API maksaa?
API-käyttöoikeus sisältyy Connect- Medium -pakettiin. Kumppani- ja yrityshinnat riippuvat volyymista ja toimitusmallista. Katso Paketit ja hinnat.
