Of u nu een klein bedrijf, een grote onderneming of een softwareleverancier bent: de API van Qvalia biedt u één gestandaardiseerde manier om te integreren met het Peppol-netwerk, met optionele ondersteuning voor aanvullende EDI-stromen, intelligente documentverwerking en gegevensverrijking.

Via de Invoicing API kunt u werken met factuurgerelateerde Peppol-berichten, zoals BIS Billing factuur), BIS Billing Note (creditnota), BIS Self-Billing Invoice, BIS Self-Billing Credit Note en BIS Invoice Response, en deze indien nodig aanvullen met Message Level Response voor technische bevestigingen met betrekking tot facturen en andere Peppol-berichten.

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:

Voor alle transacties wordt UBL 2.1 als basisstandaard gebruikt.

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 5a: 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:

Deze werkwijze geldt zowel voor het versturen als voor het ontvangen van facturen.

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
Reacties op berichtniveau. Bevestigingen op technisch en zakelijk niveau bijhouden

Omdat dit alles gebruikmaakt van hetzelfde API-ontwerp, hetzelfde authenticatiemodel en hetzelfde UBL 2.1-gegevensmodel, hebt u niet voor elk documenttype aparte projecten of gateways nodig. U kunt nieuwe toepassingen mogelijk maken naarmate uw bedrijf of de behoeften van uw klanten veranderen.

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.