Olitpa sitten pienyritys, suuryritys tai ohjelmistotoimittaja, Qvalian sovellusrajapinta tarjoaa sinulle yhden standardeihin perustuvan tavan integroitua Peppol-verkkoon, ja se tukee valinnaisesti muita EDI-virtoja, älykästä asiakirjojen käsittelyä ja tietojen rikastamista.
Palvelun Invoicing API kautta voit käsitellä laskuihin liittyviä Peppol-sanomia, kuten BIS Billing (lasku), BIS Billing Credit Note (hyvityslasku), BIS Self-Billing Invoice (lasku), BIS Self-Billing Credit Note (hyvityslasku) ja BIS Invoice Response), ja tarvittaessa täydentää niitä Message Level Response -vastauksilla, jotka koskevat laskuihin liittyviä teknisiä kuittauksia ja muita Peppol-sanomia.
API voi:
- Auta pientä yritystä aloittamaan Peppol-laskujen lähettäminen nopeasti.
- Tukea suurta yritystä, jossa on strukturoituja, suuria sanomavirtoja.
- Teholaskutusohjelmistot ja toiminnanohjausjärjestelmät, jotka tarvitsevat usean asiakkaan yhteyksiä useille asiakkaille
Tässä oppaassa opit, miten:
- Määritä Qvalian Transaction API Peppol- ja EDI-keskuksesi.
- Vaihda ensimmäinen Peppol-laskusi API:n kautta
- Laajenna laskujen lisäksi myös tilauksiin, luetteloihin ja muuhun.
- Mahdollistaa skaalautuvat, usean vuokralaisen mallit ohjelmistojen myyjille.
- Lisää kehittyneitä tekoälypohjaisia dataominaisuuksia tietojen rikastamiseen ja PDF-tiedostojen poimimiseen.
Yleiskatsaus: API Peppolia ja EDI:tä varten
Peppol API tarjoaa yhtenäisen käyttöliittymän sähköisille liikesanomille Peppolin ja EDI:n välityksellä. Se on rakennettu tukemaan seuraavia keskeisiä skenaarioita:
- Laskut ja hyvityslaskut
- Ostotilaukset ja tilausvastaukset
- Tilausmuutokset ja peruutukset
- Luettelot ja kohteiden päivitykset
- Lähetysohjeet
- Viestitason vastaukset ja tilapäivitykset
Kaikissa päätepisteissä käytetään yhteistä suunnitteluperiaatetta:
- REST-pohjaiset HTTP-päätepisteet
- Tuki sekä JSONille että XML:lle
- UBL 2.1 taustalla olevana tietomallina
- Virheenkäsittely vakiomuotoisten HTTP-tilakoodien avulla
Sinulle tämä tarkoittaa, että voit ajatella liiketoimintaviestejä verkkojen ja protokollien sijaan. Sinä luot kelvollisia UBL-pohjaisia asiakirjoja; Qvalia hoitaa Peppol- ja EDI-kerroksen taustalla.
Aloittaminen: ennakkoedellytykset ja asennus
Qvalian Peppol API:n käyttöönotto vaatii vain muutamia perusasioita:
Qvalia-tili
Organisaatiosi on otettu Qvalia-asiakkaaksi. Saat tilin rekisteröintinumeron, joka yksilöi tilisi yksiselitteisesti kaikissa tapahtumakutsuissa.
API-avain
Tunnistautuminen tapahtuu API-avaimen avulla, ja testi- ja tuotantoympäristöille on omat avaimet. Kaikki kutsut tehdään HTTPS:n kautta nykyaikaisella TLS:llä.
Tilin rekisteröintinumero URL-polussa
Tapahtumakutsut sisältävät accountRegNo -numeron polussa. Esimerkiksi:
POST /transaction/{accountRegNo}/invoices/outgoingFormaattivalinta:
Voit valita JSON- tai XML-muodon tavallisten HTTP-otsakkeiden (Content-Type ja Accept) avulla. JSON on oletusarvo, jos mitään nimenomaista valintaa ei ole tehty.
Kun nämä elementit ovat valmiina, voit aloittaa Peppolin liikenteen testaamisen Qvalian avulla.
Vaihe vaiheelta: ensimmäisen Peppol-laskutuksen integrointi (lähetä ja vastaanota)
Tässä osiossa käydään läpi tyypillinen ensimmäinen integraatio järjestelmäsi ja Qvalian Transaction API:n välillä, joka kattaa sekä Peppol-laskujen lähettämisen että vastaanottamisen.
Vaihe 1: Aloita hiekkalaatikosta
Aloita integrointi hiekkalaatikkoympäristöä vastaan:
- Perus-URL (esimerkki): https://api-qa.qvalia.com
- Sama todentamismalli, päätepisteet ja rakenne kuin tuotannossa.
Näin voit rakentaa ja testata ilman, että se vaikuttaa todellisiin asiakkaisiin tai rahavirtoihin.
Vaihe 2: Käytä API-avainta ja accountRegNo-tunnusta
Tallenna kokoonpanoosi:
- API-avaimesi (hiekkalaatikkoa varten)
- TilisiRegNro
Kunkin pyynnön on sisällettävä:
- Authorization-otsake, jossa on API-avain
- accountRegNo päätepisteen polussa, esimerkiksi:
Lähtevät laskut:/transaction/{accountRegNo}/invoices/outgoing
Saapuvat laskut (pull):/transaction/{accountRegNo}/invoices/incoming
Vaihe 3: Valitse JSON tai XML (UBL-pohjainen)
Kaikissa tapahtumissa käytetään UBL 2.1 -standardia.
Voit joko:
- Luo UBL 2.1 XML, tai
- Käytä UBL:n JSON-edustusta, joka kuvaa saman rakenteen JSON-kenttiin.
Otsikot ohjaavat muotoa:
JSON (oletus)
Content-Type: application/jsonAccept: application/jsonXML
Content-Type: application/xmlAccept: application/xmlTämä joustavuus mahdollistaa Peppol API:n integroinnin sekä JSON- että XML-pohjaisiin ympäristöihin.
Vaihe 4: Liitä laskusi UBL:ään
Kartoita seuraavaksi sisäinen laskutusmallisi UBL-elementteihin. Käytettävissä ovat sekä UBL JSON että UBL XML.
- Otsikkotiedot (lasku, IssueDate, InvoiceTypeCode).
- Osapuolet (AccountingSupplierParty, AccountingCustomerParty)
- Summat (TaxTotal, LegalMonetaryTotal)
- Rivit (Laskurivi, Nimike, Hinta, Veroluokka)
Tavoitteena on varmistaa, että:
- Kaikki pakolliset kentät ovat läsnä
- Arvot ovat asianomaisen Peppol-profiilin mukaisia (esim, BIS Billing)
- Omat liiketoimintavaatimuksesi (viitteet, kustannuspaikat, projektikoodit) täyttyvät.
Tämän jälkeen sarjallistat tämän joko JSON- tai XML-muodossa, riippuen valitsemastasi formaatista. Saapuvien laskujen osalta käytät samaa UBL-rakennetta lukiessasi, validoidessasi ja kartoittaessasi tietoja Qvaliasta sisäiseen malliisi.
Vaihe 5a: Lähtevän Peppol-laskun lähettäminen
Vaihe 5.1: Lähtevän Peppol-laskun lähettäminen
Kun lähtevä hyötykuorma on valmis, päätepisteen esimerkki:
POST https://api-qa.qvalia.com/transaction/{accountRegNo}/invoices/outgoingSisältää:
- Authorization-otsake, jossa on API-avaimesi
- Oikea Content-Type-otsake (JSON tai XML)
- UBL-pohjaisen laskun hyötykuorma pyynnön rungossa.
Qvalia validoi laskun, reitittää sen Peppol-verkon tai VAN kautta ja palauttaa vastauksen, jossa on tunnisteet ja tila.
Vaihe 5.2: Vastaanota saapuvat Peppol-laskut.
Kun haluat hakea saapuvat laskut Qvaliasta API:n kautta, sinun on tyypillisesti:
Soita esimerkiksi saapuvaan päätepisteeseen:
GET https://api-qa.qvalia.com/transaction/{accountRegNo}/invoices/incomingVaihtoehtoisesti voit:
- Suodatin tai sivun tulokset (asetuksista riippuen)
- Käytä "read"-päätepisteitä uusien ja jo käsiteltyjen laskujen erottamiseksi toisistaan.
Palautettu UBL JSON tai XML yhdistetään sitten sisäiseen tietomalliisi lähettämistä, hyväksyntää tai jatkokäsittelyä varten.
Vaihe 6: Seurannan, vastausten ja virheiden käsittely.
Tapahtuma-API käyttää ennakoitavia HTTP-tilakoodeja, jotka voit liittää loki-, seuranta- ja käyttäjäviesteihin. Tyypillisiä malleja:
- 200 OK - Pyyntö onnistui, ja tiedot palautetaan.
- 204 No Content - Pyyntö onnistui, mutta runkoa ei ole saatavilla.
- 400 / 422 - Virheelliset tiedot tai skeema; säädä hyötykuormaa tai jäsentelyä.
- 401 / 403 - Tunnistus- tai käyttöoikeusongelmat
- 404 - Resurssia ei löydy (usein polku- tai tunnisteongelma).
- 409 - Ristiriidat, kuten päällekkäisyydet
- 429 - Nopeusraja saavutettu; hidasta pyyntöjäsi.
- 500 - Sisäinen virhe; yritä uudelleen tai ilmoita asiakaspalveluun, jos virhe on jatkuva.
Samat mallit pätevät riippumatta siitä, lähetätkö vai vastaanotatko laskuja.
Tapahtumalokin käyttäminen operatiiviseen seurantaan
API-vastausten lisäksi voit aina kirjautua Qvaliaan ja tarkastella toimintaa tapahtumalokissa. Näin saat käyttöliittymäpohjaisen näkymän siitä, mitä integraatiossasi tapahtuu, mukaan lukien esim:
- Lähetetyt ja vastaanotetut laskut
- Yksittäisten tapahtumien tila
- Virhetiedot ja validointipalaute
- Tekniset ja liiketoimintatason aikaleimat
Tapahtumaloki on hyödyllinen:
- Ensilinjan tuki ja operatiiviset tiimit, jotka eivät työskentele suoraan API:n kanssa.
- Asiakkaiden tai sisäisten käyttäjien raportoimien erityisten ongelmien vianmääritys.
- Sen tarkistaminen, että integraation muutokset käyttäytyvät odotetulla tavalla tuotannossa.
Yhdessä HTTP-tilakoodit ja tapahtumaloki antavat täydellisen kuvan: järjestelmäsi voi reagoida vastauksiin ohjelmallisesti, kun taas tiimisi voi tarvittaessa tutkia ja seurata tilannetta suoraan Qvaliassa.
Laskujen lisäksi: laajenna Peppol API:n käyttötapausta
Kun laskut on otettu käyttöön, on helppoa laajentaa integraatiota koko Peppol-viestisalkkuun.
Tyypillisiä laajennuksia ovat:
Tilaukset. Vastaanottaa ja lähettää strukturoituja tilauksia sähköisesti
Tilausten vastaukset ja muutokset. Tilausten vahvistaminen, muuttaminen tai peruuttaminen
Luettelot. Tuote- ja hintatietojen ylläpito sähköisissä luetteloissa
Lähetysilmoitukset. Lähetystietojen välittäminen
Viestitasoiset vastaukset. Seuraa teknisiä ja liiketoimintatason kuittauksia.
Koska kaikki tämä käyttää samaa API-suunnittelua, todennusmallia ja UBL 2.1 -tietomallia, et tarvitse erillisiä projekteja tai yhdyskäytäviä kutakin asiakirjatyyppiä varten. Voit ottaa käyttöön uusia käyttötapauksia, kun liiketoimintasi tai asiakkaidesi vaatimukset kehittyvät.
Tässä kohtaa "yksi Peppol API tarpeesta riippumatta" -lupaus tulee konkreettiseksi: sama integraatio palvelee pieniä toimittajia, suuria yrityksiä ja monimutkaisia alustaskenaarioita.
Kumppanin API laskutusohjelmistoja ja toiminnanohjausjärjestelmiä varten
Jos olet ohjelmistotoimittaja - joka käyttää laskutusalustaa, toiminnanohjausjärjestelmää, kirjanpitoratkaisua tai integraatioalustaa - vaatimuksesi ovat hieman erilaiset. Qvalian kumppani-API:n avulla voit luoda monitilaaja-kokoonpanon loppukäyttäjien viestien vaihtoa varten, mukaan lukien Peppol ID -rekisteröintien hallinta.
Peppolin kumppani-API:tä tarvitaan tarvittaessa:
- Palvele monia loppuasiakkaita yhdeltä alustalta
- Pidä kunkin asiakkaan tiedot ja tapahtumat selkeästi erillään toisistaan.
- Vältä oman Peppol-yhteyspisteen tai EDI-yhdyskäytävän käyttöä.
Qvalian kumppanuuslähtöinen malli on suunniteltu nimenomaan tähän tarkoitukseen.
Miten kumppaniasetukset toimivat
- Yrityksesi hyväksytään kumppaniksi ja se saa kumppanitunnuksen.
- Voit valita kahdesta tavasta käsitellä loppukäyttäjien viestejä: 1) yhdistetty jaettu käyttäjätili tai 2) jokaiselle loppukäyttäjälle oma Qvalia-tili, jolla on oma tilinumero (accountRegNo).
- API-kutsut sisältävät sekä yhteistyökumppanin kontekstin että tietyn asiakastilin, jolloin voit lähettää ja vastaanottaa viestejä heidän puolestaan.
Esimerkki: Kumppanin toteuttaminen
Käyttöönotto
- Organisaatiosi saa yhteistyökumppanin tunnukset ja määritykset, mukaan lukien partnerRegNo ja API-avain.
- Perustat yhden integraation Qvalian API:n suuntaan käyttämällä komentoa
/partner/{partnerRegNo}etuliite kaikille kumppaneille suunnatuille puheluille.
Asiakkaan käyttöönotto tuotteessasi
- Kun asiakas aktivoi Peppolin/e-laskutuksen käyttöliittymässäsi, kyseiselle asiakkaalle luodaan tai linkitetään Qvalia-tili.
- Tallennat asiakkaan tiliRegNo-tunnuksen oman asiakastunnuksesi rinnalle, jotta voit käsitellä tapahtumia asiakaskohtaisesti.
Tapahtumien lähettäminen ja vastaanottaminen asiakaskohtaisesti
Sovelluksesi luo tai käyttää UBL-hyötykuormia (laskuja, tilauksia jne.) samalla tavalla kuin tavallisella Transaction API:lla. Jos haluat lähettää tai vastaanottaa tapahtumia tietyn asiakkaan puolesta, kutsut Transaction API:ta partner-prefixed URI patternin kautta:
/partner/{partnerRegNo}/transaction/{accountRegNo}/{message-type}/{direction}Esimerkiksi:
- Lähtevän laskun lähettäminen:
/partner/{partnerRegNo}/transaction/{accountRegNo}/invoices/outgoing(POST) - Saapuvien laskujen hakeminen:
/partner/{partnerRegNo}/transaction/{accountRegNo}/invoices/incoming(GET) - Käyttämällä
readmuunnokset tarvittaessa lisäämälläreadpolulla.
Qvalia reitittää ja vastaanottaa viestejä ikään kuin ne olisivat suoraan asiakkaan lähettämiä tai vastaanottamia, ja ne ovat täysin jäljitettävissä tilikohtaisesti.
Edut ohjelmistotoimittajille
- Yksi tekninen integraatio, monta asiakasta, yhdenmukaisen kumppani- ja asiakkuusmallin avulla.
- Sinun ei tarvitse käyttää ja ylläpitää omaa Peppolia tai EDI-verkkoa.
- Helppo skaalautuminen uusille markkinoille, toimeksiantoihin ja viestityyppeihin käyttämällä samaa kumppanien integrointimallia uudelleen.
Lisätoiminnot: AI-agenttien rikastaminen
Kuljetuksen ja liitettävyyden lisäksi Qvalia tarjoaa myös Enrichment API -rajapinnan, joka voi rikastuttaa tapahtumia muun muassa rivikohtaisella luokittelulla, tapahtumaa edeltävällä ja sen jälkeisellä käsittelyllä ja muulla tavoin, sekä poimia ja muuntaa PDF-dokumentit rikkaiksi, jäsennellyiksi ja validoiduiksi tiedoiksi pienellä vaivalla.
Rikastusliittymä on suunniteltu asynkroniseksi palveluksi:
- Lähetät laskutiedoston (esim. PDF tai XML) API:n kautta.
- Saat vastauksessa pollingId-tunnuksen.
- Kyselet tilaa, kunnes rikastus on valmis.
- Haet jäsennellyn JSON-tuloksen, jossa on rikastettuja tietoja.
Tähän tulokseen voi sisältyä:
- Alkuperäisestä tiedostosta poimittu, jäsennelty laskun sisältö.
- Validointi Peppolia tai muita liiketoimintasääntöjä vasten
- Normalisoidut kentät, jotka soveltuvat analytiikkaan, automaatioon ja tekoälyn työnkulkuihin.
Toteutusmalli
Tyypillinen integrointi näyttää seuraavalta:
Lähetä lasku rikastettavaksi
Kutsu päätepistettä, liitä laskutiedosto ja kaikki asiaankuuluvat metatiedot ja
Tallenna palautettu pollingId.
POST /enrichment/{accountRegNo}/invoiceKysely loppuun
Soita turvallisin väliajoin. Käsittelyn aikana API varmistaa, että työ on edelleen käynnissä. Kun se on valmis, se palauttaa tilan ja linkit rikastustulokseen.
GET /enrichment/{accountRegNo}/{pollingId}Hae tiettyjä rikastetyyppejä
Soita saadaksesi tietyn rikastustuloksen - esimerkiksi yksityiskohtaiset laskutiedot tai Peppol-validointitulokset. Syötä tämä kirjanpitomoottoriin, analytiikkapinoon tai automaatiologiikkaan.
GET /enrichment/{accountRegNo}/{pollingId}/{enrichmentType}Käyttötapaukset
- Pienyritykset
Voi hyötyä yritystason älykkäästä asiakirjojen käsittelystä; puhtaat, jäsennellyt tiedot ilman investointeja monimutkaisiin OCR- tai validointityökaluihin. - Large
Voidaan standardoida lasku- ja asiakirjatiedot eri yksiköissä, järjestelmissä ja maantieteellisillä alueilla ja mahdollistaa parempi tiedonhallinta, analytiikka ja kirjanpidon automatisointi. - Ohjelmistotoimittajat ja yhteistyökumppanit
voivat sisällyttää kehittyneet rikastustoiminnot suoraan tuotteisiinsa rakentamatta omia jäsennys- ja sääntömoottoreita.
Kaikissa tapauksissa pääsy tähän teknologiaan on suoraviivaista: sama tili- ja suojausmalli kuin transaktioiden sovellusliittymässä ja pieni joukko hyvin määriteltyjä päätepisteitä.
Peppol API-yhteys kaikille yrityksille
Qvalian sovellusliittymä on rakennettu antamaan sinulle yksinkertaistettu ja skaalautuva yhteys Peppol-verkkoon yritystyypistäsi riippumatta:
- Pienyritys, jonka on vaihdettava vaatimustenmukaisia verkkolaskuja.
- Suuri yritys, joka hallinnoi suuria määriä ja useiden yksiköiden virtoja.
- Ohjelmistotoimittaja, joka tarjoaa laskutus-, ERP- tai rahoitusratkaisuja monille asiakkaille.
Seuraava askel on suoraviivainen: muodosta yhteys hiekkalaatikkoon, lähetä ensimmäinen testilasku ja aloita suunnittelemaan, miten Peppolista, EDI:stä ja rikastamisesta voi tulla sisäänrakennettu osa toimintojasi tai tuotteitasi - eikä erillinen, monimutkainen projekti.
