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.

Via de service 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 leert u hoe u:

De Peppol API biedt een uniforme interface voor elektronische zakelijke berichten via Peppol en EDI. Deze is ontwikkeld ter ondersteuning van kernscenario's zoals:

Een algemeen ontwerpprincipe wordt toegepast op alle eindpunten:

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

Om aan de slag te gaan met de Peppol API van Qvalia zijn slechts enkele basisvereisten nodig:

Qvalia-account
Uw organisatie is aangemeld als klant van Qvalia. U ontvangt een accountregistratienummer dat uw account uniek identificeert in alle transacties.

API-sleutel
Authenticatie wordt afgehandeld via een API-sleutel, met aparte sleutels voor test- en productieomgevingen. Alle oproepen worden gedaan via HTTPS met moderne TLS.

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

Formaatkeuze: JSON of XML
U kunt JSON of XML kiezen via standaard HTTP-headers (Content-Type en Accept). JSON is de standaardinstelling als er geen expliciete keuze wordt gemaakt.

Zodra deze elementen aanwezig zijn, bent u klaar om Peppol-verkeer te testen met Qvalia.

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

Begin met integratie in de sandbox-omgeving:

Hierdoor kunt u bouwen en testen zonder dat dit invloed heeft op echte klanten of financiële stromen.

Sla in uw configuratie het volgende op:

Elk verzoek moet het volgende bevatten:

Alle transacties gebruiken UBL 2.1 als onderliggende standaard.

Je kunt:

Headers bepalen het formaat:

JSON (standaard)

XML

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

Breng vervolgens uw interne factuurmodel in kaart naar UBL-elementen. Zowel UBL JSON als UBL XML zijn beschikbaar.

Het doel is ervoor te zorgen dat:

Vervolgens serialiseert u dit als JSON of XML, afhankelijk van uw formaatkeuze. Voor inkomende facturen gebruikt u dezelfde UBL-structuur bij het lezen, valideren en toewijzen van gegevens uit Qvalia aan uw interne model.

Stap 5a: Een uitgaande Peppol-factuur verzenden

Met uw uitgaande payload gereed, eindpuntvoorbeeld:

Omvatten:

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

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

Bel het inkomende eindpunt, bijvoorbeeld:

Optioneel kunt u:

De geretourneerde UBL JSON of XML wordt vervolgens toegewezen aan uw interne gegevensmodel voor publicatie, goedkeuring of verdere verwerking.

De Transaction API maakt gebruik van voorspelbare HTTP-statuscodes die u kunt toewijzen aan logboeken, monitoring en gebruikersberichten. Typische patronen:

Dezelfde patronen zijn van toepassing, of u nu facturen verstuurt of ontvangt.

Naast de API-reacties kunt u altijd inloggen op Qvalia en de activiteiten in het transactielogboek bekijken. Zo krijgt u een UI-gebaseerd overzicht van wat er in uw integratie gebeurt, waaronder bijvoorbeeld:

Het transactielogboek is nuttig voor:

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

Zodra u facturen hebt opgesteld, kunt u uw integratie eenvoudig uitbreiden tot een volledig Peppol-berichtenportfolio.

Typische uitbreidingen zijn onder meer:
Orders. Ontvang en verstuur gestructureerde orders elektronisch
Orderbevestigingen en wijzigingen. Bevestig, wijzig of annuleer orders
Catalogi. Beheer product- en prijsinformatie in elektronische catalogi
Verzendadvies. Communiceer verzendinformatie
Reacties op berichtniveau. Volg technische en zakelijke bevestigingen

Omdat dit alles gebruikmaakt van hetzelfde API-ontwerp, authenticatiemodel en UBL 2.1-gegevensmodel, hebt u geen afzonderlijke projecten of gateways nodig voor elk documenttype. U kunt nieuwe use cases inschakelen naarmate uw bedrijf of de vereisten van uw klanten evolueren.

Hier wordt de belofte van "één Peppol API, ongeacht de behoefte" tastbaar: dezelfde integratie is geschikt voor kleine leveranciers, grote ondernemingen en complexe platformscenario's.

Als u een softwareleverancier bent — die een factureringsplatform, ERP, boekhoudoplossing of integratieplatform exploiteert — zijn uw vereisten iets anders. Met de Partner API van Qvalia kunt u een multi-tenantconfiguratie opzetten voor het uitwisselen van berichten voor eindgebruikers, inclusief het beheren 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 verbruikt 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 verstuurt en ontvangt berichten 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, die transacties kan verrijken met classificatie van regelitems, verwerking voor en na de transactie en meer, en die met minimale inspanning PDF-documenten kan extraheren en omzetten in rijke, gestructureerde en gevalideerde gegevens.

De Enrichment API is ontworpen als een asynchrone dienst:

Dit resultaat kan het volgende omvatten:

Een typische integratie ziet er als volgt uit:

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

Poll voor voltooiing
Bel met veilige tussenpozen. Tijdens de verwerking controleert de API of de taak nog steeds wordt uitgevoerd. Wanneer deze is voltooid, retourneert deze een status en links naar het verrijkingsresultaat.

Specifieke verrijkingssoorten ophalen
Roep deze functie aan om een bepaalde verrijkingsoutput te verkrijgen, 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 de Transaction API en een klein aantal duidelijk gedefinieerde eindpunten.

De API van Qvalia is ontwikkeld om u een vereenvoudigd, schaalbaar toegangspunt tot het Peppol-netwerk te bieden, ongeacht het type bedrijf dat u heeft:

De volgende stap is eenvoudig: maak verbinding met de sandbox, verstuur uw eerste testfactuur en begin met het plannen hoe Peppol, EDI en verrijking een geïntegreerd onderdeel van uw bedrijfsvoering of product kunnen worden, in plaats van een afzonderlijk, complex project.