Slik bruker du Peppol API: trinnvis veiledning

Enten du er en liten bedrift, en stor Bedrift , eller en programvareleverandør, gir Qvalias API deg en enkelt, standardbasert måte å integrere med Peppol-nettverket på, med valgfri støtte for ytterligere EDI-flyter, intelligent dokumentbehandling og databerikelse. For en oversikt over alle Qvalia API-er og Peppol-dokumentene de inneholder, se Peppol API og utviklerverktøy .

Gjennom tjenesten Fakturering API kan du jobbe med fakturarelaterte Peppol-meldinger som BIS Billing (faktura), BIS Billing Kreditnota (kreditnota), BIS-selvfaktura, BIS-selvfaktureringskreditnota og BIS Invoice Response , og, når det er nødvendig, komplementere dem med meldingsnivårespons for valideringsresultater på meldingsnivå i overgangsperioden for MLR. Transportkvitteringer, meldingsnivåstatus (MLS) mellom tjenesteleverandører og svar på forretningsnivå er separate mekanismer.

API-et kan:

I denne veiledningen lærer du hvordan du:

Peppol API tilbyr et enhetlig grensesnitt for elektroniske forretningsmeldinger over Peppol og EDI. Det er bygget for å støtte kjernescenarier som:

Et felles designprinsipp brukes på tvers av alle endepunkter:

For deg betyr dette at du kan tenke i forretningsmeldinger i stedet for nettverk og protokoller. Du oppretter gyldige UBL-baserte dokumenter; Qvalia håndterer Peppol- og EDI-laget i bakgrunnen.

For å komme i gang med Qvalias Peppol API kreves det bare noen få grunnleggende prinsipper:

Qvalia-konto
Organisasjonen din er registrert som Qvalia-kunde. Du mottar et kontoregistreringsnummer som unikt identifiserer kontoen din i alle transaksjonsanrop.

API-nøkkel
Autentisering håndteres via en API-nøkkel, med separate nøkler for test- og produksjonsmiljøer. Alle anrop gjøres over HTTPS med moderne TLS.

Kontoregistreringsnummer i URL-banen
Transaksjonskall inkluderer kontoregistreringsnummeret ditt i banen. For eksempel:

Formatvalg: JSON eller XML
Du kan velge JSON eller XML via standard HTTP-overskrifter (Content-Type og Accept). JSON er standard hvis det ikke gjøres noe eksplisitt valg.

Når disse elementene er på plass, er du klar til å begynne å teste Peppol-trafikk med Qvalia.

Denne delen går gjennom en typisk første integrasjon mellom systemet ditt og Qvalias transaksjons-API, som dekker både sending og mottak av Peppol-fakturaer.

Begynn med å integrere mot sandkassemiljøet:

Dette lar deg bygge og teste uten å påvirke reelle kunder eller økonomiske strømmer.

I konfigurasjonen din, lagre:

Hver forespørsel bør inneholde:

Peppols forretningsdokument-endepunkter bruker den UBL 2.1-baserte strukturen som er definert av gjeldende BIS- eller PINT-spesifikasjon. Andre Qvalia API-er og -endepunkter kan bruke andre nyttelastmodeller. Bekreft gjeldende API-dokumentasjon for endepunktet du implementerer.

Du kan enten:

Overskrifter styrer formatet:

JSON (standard)

XML

Denne fleksibiliteten lar deg integrere Peppol API i både JSON-first- og XML-first-miljøer.

Deretter tilordner du den interne fakturamodellen din til UBL-elementer. Både UBL JSON og UBL XML er tilgjengelige.

Målet er å sikre at:

Deretter serialiserer du dette enten som JSON eller XML, avhengig av formatvalget. For innkommende fakturaer bruker du den samme UBL-strukturen når du leser, validerer og tilordner data fra Qvalia til den interne modellen din.

Trinn 5: Send en utgående Peppol-faktura

Med den utgående nyttelasten klar, eksempel på endepunkt:

Inkludere:

Qvalia validerer fakturaen og ruter den via Peppol-nettverket eller EDI/ VAN , og returnerer et svar med identifikatorer og status.

For å hente innkommende fakturaer fra Qvalia via API, gjør du vanligvis følgende:

Kall det innkommende endepunktet, for eksempel:

Valgfritt kan du:

Den returnerte UBL JSON- eller XML-filen blir deretter tilordnet den interne datamodellen din for publisering, godkjenning eller videre behandling.

Transaksjons-API-et bruker forutsigbare HTTP-statuskoder som du kan tilordne til logger, overvåking og brukermeldinger. Typiske mønstre:

De samme mønstrene gjelder enten du sender eller mottar fakturaer. OpenPeppol erstatter MLR med MLS i eDelivery-laget: MLS-aktiveringsvinduet starter 1. mars 2027, MLS blir obligatorisk for tjenesteleverandører 1. april 2027, og MLR pensjoneres 1. mai 2027.

I tillegg til API-svarene kan du alltid logge inn på Qvalia og se gjennom aktiviteten i transaksjonsloggen. Dette gir deg en brukergrensesnittbasert oversikt over hva som skjer i integrasjonen din, inkludert for eksempel:

Transaksjonsloggen er nyttig for:

Sammen gir HTTP-statuskodene og transaksjonsloggen et komplett bilde: systemet ditt kan reagere programmatisk på svar, mens teamet ditt kan undersøke og følge opp direkte i Qvalia ved behov.

Når du har fakturaer på plass, er det enkelt å utvide integrasjonen til en komplett Peppol-meldingsportefølje.

Typiske utvidelser inkluderer:
Bestillinger . Motta og send strukturerte bestillinger elektronisk
Ordresvar og endringer. Bekreft, endre eller avbryt bestillinger
Kataloger . Vedlikehold produkt- og prisinformasjon i elektroniske kataloger
Forsendelsesråd . Kommuniser forsendelsesinformasjon
Validering og status på meldingsnivå . Spor MLR i overgangsperioden, MLS mellom tjenesteleverandører og relevant forretningsrespons for hver prosess.

De tilgjengelige endepunktene bruker en konsistent konto- og autentiseringsmodell, men nyttelaststrukturer og aktiverte meldingstyper avhenger av den relevante Peppol-profilen og Qvalia-tjenestekonfigurasjonen din. Du aktiverer nye brukstilfeller etter hvert som bedriften din eller kundenes krav utvikler seg.

Det er her løftet om «ett Peppol API uansett behov» blir konkret: den samme integrasjonen betjener små leverandører, store bedrifter og komplekse plattformscenarioer.

Hvis du er en programvareleverandør – som driver en faktureringsplattform, ERP, regnskapsløsning eller integrasjonsplattform – er kravene dine litt annerledes. Med Qvalias Partner API kan du sette opp en flerleietakerkonfigurasjon for utveksling av meldinger for sluttbrukere, inkludert administrasjon av Peppol ID registreringer.

Partner-API-et for Peppol er nødvendig hvis du trenger å:

Qvalias partnerorienterte modell er spesielt utviklet for dette formålet.

Applikasjonen din genererer eller bruker UBL-nyttelaster (fakturaer, bestillinger osv.) på samme måte som med standard Transaction API. For å sende eller motta transaksjoner på vegne av en bestemt kunde, kaller du Transaction API gjennom det partnerprefikserte URI-mønsteret:

For eksempel:

Qvalia ruter og mottar meldinger som om de ble sendt eller mottatt direkte av kunden, med full sporbarhet per konto.

I tillegg til transport og tilkobling tilbyr Qvalia også Enrichment API , som kan berike transaksjoner med linjeelementklassifisering, behandling før og etter transaksjoner og mer, og kan trekke ut og transformere PDF-dokumenter til rike, strukturerte og validerte data med minimal innsats.

Berikelses-API-et er utformet som en asynkron tjeneste:

Dette resultatet kan inkludere:

En typisk integrasjon ser slik ut:

Send inn en faktura for berikelse
Ring et endepunkt, legg ved fakturafilen og eventuelle relevante metadata, og
Lagre den returnerte pollingId-en.

Avstemning for fullføring
Kall med trygge intervaller. Under behandlingen bekrefter API-et at jobben fortsatt kjører. Når den er ferdig, returnerer den en status og lenker til berikelsesresultatet.

Hent spesifikke berikelsestyper
Ring for å få et bestemt berikelsesresultat – for eksempel detaljerte fakturadata eller Peppol-valideringsresultater. Mat dette inn i regnskapsmotoren, analysestakken eller automatiseringslogikken din.

I alle tilfeller er tilgangen til denne teknologien enkel: samme konto- og sikkerhetsmodell som Transaction API, og et lite sett med veldefinerte endepunkter.

Qvalias API er bygget for å gi deg en forenklet, skalerbar aksesspunkt til Peppol-nettverket , uavhengig av bedriftstype:

Neste steg er enkelt: koble til sandkassen, send din første testfaktura, og begynn å planlegge hvordan Peppol, EDI og berikelse kan bli en innebygd del av driften eller produktet ditt – i stedet for et separat, komplekst prosjekt.