Hoe gebruik je de Peppol API: stapsgewijze handleiding

Of u nu een klein bedrijf, een grote onderneming of een softwareleverancier bent: de API van Qvalia biedt u één enkele, op standaarden gebaseerde manier om te integreren met het Peppol-netwerk, met optionele ondersteuning voor aanvullende EDI-stromen, intelligente documentverwerking en gegevensverrijking. Zie ‘Peppol API en ontwikkelaarstools’ voor een overzicht van alle Qvalia-API’s en de Peppol-documenten die ze verwerken.

Via de Invoicing API kunt u werken met Peppol-berichten die betrekking hebben op facturen, zoals de factuur ( BIS Billing ), de creditnota ( BIS Billing Credit Note), de BIS-zelffactuur (BIS Self-Billing Invoice), de BIS-zelfcreditnota (BIS Self-Billing Credit Note) en de BIS-zelfkredietnota ( BIS Invoice Response), en deze indien nodig aanvullen met een Message Level Response voor validatieresultaten op berichtniveau tijdens de MLR-overgangsperiode. Transportontvangstbewijzen, Message Level Status (MLS) tussen dienstverleners en reacties op bedrijfsniveau zijn afzonderlijke mechanismen.

De API kan:

In deze handleiding leer je hoe je:

De Peppol API biedt een uniforme interface voor elektronische zakelijke berichten via Peppol en EDI. De API is ontwikkeld ter ondersteuning van belangrijke scenario’s, zoals:

Voor alle eindpunten geldt hetzelfde ontwerpprincipe:

Voor u betekent dit dat u kunt denken in termen van zakelijke berichten in plaats van netwerken en protocollen. U stelt geldige, op UBL gebaseerde documenten op; Qvalia regelt de Peppol- en EDI-laag op de achtergrond.

Om aan de slag te gaan met de Peppol API van Qvalia heb je slechts een paar basiszaken nodig:

Qvalia-account
Uw organisatie is nu geregistreerd als klant bij Qvalia. U ontvangt een accountregistratienummer waarmee uw account bij alle transacties uniek kan worden geïdentificeerd.

API-sleutel
De authenticatie verloopt via een API-sleutel, waarbij er aparte sleutels zijn voor de test- en productieomgeving. Alle verzoeken worden via HTTPS met moderne TLS verzonden.

Accountregistratienummer in het URL-pad
Transactieaanroepen bevatten uw accountRegNo in het pad. Bijvoorbeeld:

Keuze van het formaat: JSON of XML
U kunt via standaard HTTP-headers (Content-Type en Accept) kiezen tussen JSON en XML. Als er geen expliciete keuze wordt gemaakt, is JSON de standaardinstelling.

Zodra deze elementen zijn geïmplementeerd, bent u klaar om het Peppol-verkeer met Qvalia te testen.

In dit hoofdstuk wordt een standaardprocedure voor de eerste integratie tussen uw systeem en de Transaction API van Qvalia beschreven, waarbij zowel het verzenden als het ontvangen van Peppol-facturen aan bod komt.

Begin met de integratie in de sandbox-omgeving:

Zo kunt u systemen bouwen en testen zonder dat dit gevolgen heeft voor echte klanten of financiële stromen.

Sla in je configuratie het volgende op:

Elk verzoek moet het volgende bevatten:

Peppol-eindpunten voor bedrijfsdocumenten maken gebruik van de op UBL 2.1 gebaseerde structuur die is gedefinieerd in de toepasselijke BIS- of PINT-specificatie. Andere Qvalia-API’s en -eindpunten kunnen andere payload-modellen gebruiken; raadpleeg de actuele API-documentatie voor het eindpunt dat u implementeert.

Je kunt het volgende doen:

Kopteksten bepalen de opmaak:

JSON (standaard)

XML

Dankzij deze flexibiliteit kunt u de Peppol API zowel in JSON-first- als in XML-first-omgevingen integreren.

Koppel vervolgens uw interne factuurmodel aan UBL-elementen. Zowel UBL JSON als UBL XML zijn beschikbaar.

Het doel is ervoor te zorgen dat:

Vervolgens zet je dit om in JSON of XML, afhankelijk van het formaat dat je hebt gekozen. Voor inkomende facturen gebruik je dezelfde UBL-structuur bij het inlezen, valideren en toewijzen van gegevens uit Qvalia aan je interne model.

Stap 5: Een uitgaande Peppol-factuur verzenden

Nu je uitgaande payload klaar is, voorbeeld van een eindpunt:

Vermeld:

Qvalia valideert de factuur, stuurt deze via het Peppol-netwerk ofVAN door en stuurt een reactie terug met identificatiegegevens en de status.

Om inkomende facturen via de API uit Qvalia op te halen, gaat u doorgaans als volgt te werk:

Roep het ontvangende eindpunt aan, bijvoorbeeld:

Je kunt eventueel:

De teruggestuurde UBL-JSON of -XML wordt vervolgens gekoppeld aan uw interne gegevensmodel voor boeking, goedkeuring of verdere verwerking.

De Transaction API maakt gebruik van voorspelbare HTTP-statuscodes die je kunt koppelen aan logbestanden, monitoring en gebruikersberichten. Typische patronen:

Dezelfde regels gelden, of je nu facturen verstuurt of ontvangt. OpenPeppol vervangt MLR door MLS in de eDelivery-laag: de MLS-activeringsperiode begint op 1 maart 2027, MLS wordt op 1 april 2027 verplicht voor dienstverleners en MLR wordt op 1 mei 2027 buiten gebruik gesteld.

Naast de API-reacties kun je ook altijd inloggen op Qvalia en de activiteiten in het transactielogboek bekijken. Zo krijg je via de gebruikersinterface een overzicht van wat er in je integratie gebeurt, zoals bijvoorbeeld:

Het transactielogboek is handig voor:

Samen geven de HTTP-statuscodes en het transactielogboek een volledig beeld: uw systeem kan programmatisch reageren op reacties, terwijl uw team indien nodig direct in Qvalia onderzoek kan doen en actie kan ondernemen.

Zodra u facturen in gebruik hebt, is het eenvoudig om uw integratie uit te breiden naar het volledige Peppol-berichtenaanbod.

Typische uitbreidingen zijn onder meer:
Orders. Gestructureerde bestellingen elektronisch ontvangen en verzenden
Orderreacties en wijzigingen. Bestellingen bevestigen, wijzigen of annuleren
Catalogi. Product- en prijsinformatie bijhouden in elektronische catalogi
Verzendberichten. Verzendinformatie doorgeven
Validatie en status op berichtniveau. MLR volgen tijdens de overgangsperiode, MLS tussen dienstverleners, en de relevante zakelijke reactie voor elk proces

De beschikbare eindpunten maken gebruik van een uniform account- en authenticatiemodel, maar de structuur van de payloads en de ondersteunde berichttypen zijn afhankelijk van het betreffende Peppol-profiel en de configuratie van uw Qvalia-service. Naarmate de behoeften van uw bedrijf of uw klanten veranderen, kunt u nieuwe gebruiksscenario’s inschakelen.

Hier wordt de belofte van „één Peppol-API voor elke behoefte“ werkelijkheid: dezelfde integratie is geschikt voor zowel kleine leveranciers als grote ondernemingen en complexe platformscenario’s.

Als u een softwareleverancier bent — die een facturatieplatform, ERP-systeem, boekhoudoplossing of integratieplatform beheert — zijn uw behoeften iets anders. Met de Partner API van Qvalia kunt u een multi-tenant-configuratie opzetten voor het uitwisselen van berichten voor eindgebruikers, inclusief het beheer van Peppol ID .

De Partner API voor Peppol is nodig als u:

Het partnergerichte model van Qvalia is speciaal voor dit doel ontworpen.

Uw applicatie genereert of verwerkt UBL-payloads (facturen, bestellingen, enz.) op dezelfde manier als bij de standaard Transaction API. Om transacties namens een specifieke klant te verzenden of te ontvangen, roept u de Transaction API aan via het URI-patroon met het partnervoorvoegsel:

Bijvoorbeeld:

Qvalia stuurt berichten door en ontvangt ze alsof ze rechtstreeks door de klant zijn verzonden of ontvangen, met volledige traceerbaarheid per account.

Naast transport en connectiviteit biedt Qvalia ook de Enrichment API aan, waarmee transacties kunnen worden verrijkt met classificatie op regelniveau, verwerking voor en na de transactie en nog veel meer, en waarmee PDF-documenten met minimale inspanning kunnen worden geëxtraheerd en omgezet in rijke, gestructureerde en gevalideerde gegevens.

De Enrichment API is ontworpen als een asynchrone service:

Dit resultaat kan het volgende omvatten:

Een typische integratie ziet er als volgt uit:

Dien een factuur in voor verrijking
Roep een eindpunt aan, voeg het factuurbestand en eventuele relevante metagegevens toe, en
Sla de geretourneerde pollingId op.

Poll voor voltooiing
Roep deze functie met regelmatige tussenpozen aan. Tijdens de verwerking bevestigt de API dat de taak nog steeds wordt uitgevoerd. Zodra de taak is voltooid, retourneert de API een status en links naar het verrijkingsresultaat.

Specifieke verrijkingstypen ophalen
Roep deze API aan om een bepaalde verrijkingsuitvoer op te halen, bijvoorbeeld gedetailleerde factuurgegevens of Peppol-validatieresultaten. Voer deze gegevens in uw boekhoudsysteem, analysestack of automatiseringslogica in.

In alle gevallen is de toegang tot deze technologie eenvoudig: hetzelfde account- en beveiligingsmodel als bij de Transaction API, en een klein aantal duidelijk omschreven eindpunten.

De API van Qvalia is ontwikkeld om u een eenvoudige, schaalbare toegang tot het Peppol-netwerk te bieden, ongeacht het type bedrijf dat u heeft:

De volgende stap is heel eenvoudig: maak verbinding met de sandbox, verstuur je eerste testfactuur en begin met het uitwerken van een plan om Peppol, EDI en data-enrichment een integraal onderdeel van je bedrijfsvoering of product te maken — in plaats van een apart, complex project.