Documenten
Facturen en creditnota’s
Plus zelffacturering en reacties op facturen
Formaten
JSON of UBL XML
Gebaseerd op UBL 2.1, één document per verzoek
Evenementen
Ondertekende webhooks
Ontvangen, afgeleverd, vertraagd en mislukt
Beschikbaarheid
99,8% per maand
Contractueel, met servicecredits
Stuur één factuur per aanvraag
Verzend de factuur als JSON of UBL XML naar het uitgaande eindpunt van uw account. Qvalia controleert de factuur, zoekt de ontvanger op in Peppol en bezorgt de factuur. Creditnota’s, zelfdeclaraties en reacties op facturen volgen hetzelfde patroon.
- Sandbox op api-test.qvalia.com, productie op api.qvalia.com
- API-sleutel in de Authorization-header, of een tijdelijk token (JWT)
- Een ‘Idempotency-Key’-header zorgt ervoor dat herhalingspogingen veilig zijn
● ● ●
Sandbox-verzoek: een factuur versturen
curl -X POST \
"https://api-test.qvalia.com/transaction/$ACCOUNT_REG_NO/invoices/outgoing" \
-H "Authorization: $QVALIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d @invoice.jsonHoe een factuur via de API wordt verwerkt
Uw systeem werkt met één API. Qvalia beheert het Peppol-toegangspunt dat hierachter zit.
1. Verzenden
Plaats één document per verzoek. Als de gegevens ongeldig zijn of de ontvanger niet bij Peppol is geregistreerd, geeft de API een 422-foutcode terug (een stabiele foutcode), voordat er iets wordt verzonden.
2. Controleren en opleveren
Qvalia controleert het document aan de hand van de geldende Peppol-regels, zoekt het toegangspunt van de ontvanger op en verzendt het document via AS4.
3. Volg de status
Webhooks melden de bezorging, lopende herpogingen en mislukkingen. Het status-eindpunt geeft de meest recente status van elk document weer, zonder de inhoud van het document.
4. Ontvangen
Binnenkomende facturen en reacties worden op de ontvangsteindpunten in de wacht gezet. Het eindpunt voor het lezen geeft ongelezen documenten weer en markeert deze als gelezen, zodat bij de volgende aanroep alleen nieuwe documenten worden weergegeven.
Factuurdocumenten en eindpunten
Elk pad begint met /transaction/{accountRegNo}, het registratienummer van uw account. Elk documenttype heeft eindpunten voor uitgaande en inkomende gegevens, een eindpunt voor het opvragen van ongelezen documenten en een eindpunt voor de status.
| Document | Eindpunt | Peppol-specificatie |
| Factuur | /invoices | Peppol BIS Billing .0 |
| Creditnota | /creditnotes | Peppol BIS Billing .0 |
| Factuur op basis van zelfdeclaratie | /selfbillinginvoices | Peppol BIS-zelffacturering |
| Kredietnota op basis van zelfdeclaratie | /selfbillingcreditnotes | Peppol BIS-zelffacturering |
| Reactie op factuur | /invoiceresponses | BIS Invoice Response |
| Reactie op berichtniveau | /messagelevelresponses | BIS Message Level Response Peppol BIS Message Level Response |
Welke documenttypes uw account gebruikt, hangt af van de dienst en het abonnement. De schema’s voor verzoeken en antwoorden zijn te vinden in de documentatie van de Factuur-API en de Creditnota-API. Zie voor alle API’s van Qvalia: Peppol-API’s en ontwikkelaarstools.
Controleer de ontvanger voordat je het bericht verstuurt
Controleer de ‘ Peppol ID ’ voordat u de factuur indient. Uit het antwoord blijkt of de deelnemer bij Peppol is geregistreerd en welke documenttypes hij kan ontvangen, zodat uw systeem een ontbrekend of onjuist ID kan signaleren voordat het netwerk de factuur afwijst.
- Beperk de controle tot één documenttype met
docTypeRoot, bijvoorbeeldInvoiceofCreditNote - De ' Peppol ID ' is de regeling en de identificatiecode, bijvoorbeeld
0007:1234567890 - Dezelfde basis-URL’s en authenticatie als bij de Transaction API
● ● ●
Sandbox-verzoek: een ontvanger opzoeken
curl \
"https://api-test.qvalia.com/account/$ACCOUNT_REG_NO/action/lookup/peppol/0007:1234567890?docTypeRoot=Invoice" \
-H "Authorization: $QVALIA_API_KEY"Ontworpen voor productie-integraties
De details die bepalen of een integratie op grote schaal goed functioneert, staan allemaal beschreven in de API-referentie.
- Veilige herhalingspogingen
Verzend een idempotentiesleutel, en bij een herhaald verzoek wordt het oorspronkelijke antwoord geretourneerd in plaats van dat er een tweede factuur wordt aangemaakt. - Ondertekende webhooks
Elke gebeurtenis heeft een gebeurtenis-ID en, zodra u een ondertekeningsgeheim hebt ingesteld, een handtekening die u kunt verifiëren. - Herhaling van gebeurtenissen gedurende 30 dagen
Haal elk geleverd evenement opnieuw op aan de hand van de ID, bijvoorbeeld na een storing aan uw kant. - Status zonder de inhoud
Voer volumevergelijkingen uit met compacte statusrecords, gefilterd op datum, document-ID of wijzigingstijdstip. - Limieten opverwerken
Limieten worden per account geteld, en een 429-antwoord geeft aan hoe lang u moet wachten. - Bijlagen
Voeg PDF-bestanden en afbeeldingen toe aan het bericht. Het volledige verzoek, inclusief bijlagen en Base64-gecodeerd, moet binnen de limiet van 100 MB van Peppol blijven.
Eén factuur, in het formaat dat elke ontvanger nodig heeft
Stuur de factuur één keer. Qvalia controleert deze, zoekt de ontvanger op en verzendt de factuur via het Peppol-netwerk als Peppol- BIS Billing -3.0 of Peppol-PINT. Als de ontvanger niet op Peppol is aangesloten, kan Qvalia de factuur in bepaalde markten ook via EDI, als PDF per e-mail, in gedrukte vorm of via B2C-internetbanken verzenden. Dit zijn aanvullende verzendkanalen, geen Peppol-specificaties. Bekijk welke zakelijke berichtformaten Qvalia ondersteunt.
Als uw systeem geen Peppol BIS kan genereren, upload de factuur dan in het formaat waarin deze al wordt aangemaakt: Svefaktura 1.0, EDIFACT INVOIC, cXML, Finvoice 3.0, XRechnung, CII of de XML in ZUGFeRD en Factur-X. Qvalia zet deze om naar Peppol- BIS Billing e 3.0, controleert deze op geldigheid en verstuurt deze. Zie ‘Facturen versturen in uw bestaande formaat’.
Kies je startpunt
Softwareplatforms
Geïntegreerde Peppol
Bied e-facturering aan uw eigen klanten aan. De Partner API maakt hun accounts en Peppol-ID’s aan, en de Invoicing API verzorgt de verzending van hun documenten.
ERP- en financiële teams
Peppol-toegangspunt
Koppel uw ERP- of financiële systeem aan Peppol via de API, SFTP of een kant-en-klare connector.
Ontwikkelaars
Snelstartgids
Ga stap voor stap van de API-sleutel naar je eerste sandbox-factuur, met voorbeelden van verzoeken.
Veelgestelde vragen over de facturatie-API
Wat is een API voor elektronische facturering?
Met een API voor elektronische facturering kan uw software gestructureerde elektronische facturen verzenden en ontvangen zonder zelf een netwerkverbinding tot stand te brengen. Met de facturering-API van Qvalia verstuurt uw systeem facturen in JSON- of UBL XML-formaat, waarna Qvalia deze valideert en via het Peppol-netwerk verzendt.
Welke factuurdocumenten kan ik verzenden en ontvangen?
Facturen, creditnota’s, zelfgefactureerde facturen en creditnota’s, en reacties op facturen, elk met uitgaande en inkomende eindpunten. Welke documenttypes uw account gebruikt, hangt af van de dienst en het abonnement.
Moet ik kennis hebben van Peppol BIS om de API te kunnen gebruiken?
Uw documenten voldoen aan de Peppol- BIS Billing ie 3.0, in JSON of XML op basis van UBL 2.1. De voorbeeldgegevens op api.qvalia.io tonen een volledige factuur, en validatiefouten verwijzen naar de regel die moet worden gecorrigeerd. Zie Hoe Peppol-validatie werkt.
Is er een sandbox?
Ja. De sandbox op api-test.qvalia.com maakt gebruik van een eigen API-sleutel, zodat je je eigen systemen kunt testen zonder dat dit gevolgen heeft voor echte klanten. Toegang tot de API en de sandbox is inbegrepen bij het Connect- Medium -abonnement.
Hoe voorkom ik dat ik dezelfde factuur twee keer verstuur?
Voeg bij elke verzending een Idempotency-Key-header toe. Als je het verzoek herhaalt, bijvoorbeeld na een time-out, geeft de API het oorspronkelijke antwoord terug in plaats van een tweede document aan te maken. Een nieuwe verzending met hetzelfde document-ID en dezelfde ontvanger levert een 409 Conflict-fout op, tenzij je ervoor kiest om het document te overschrijven.
Hoe weet ik of een factuur is bezorgd?
Abonneer je op webhooks voor afleverings- en foutmeldingen, of raadpleeg het status-eindpunt. Een webhook die je eindpunt niet kan verwerken, wordt niet opnieuw verzonden; voer daarom regelmatig een statuscontrole uit als extra veiligheidsmaatregel. Elke afgeleverde gebeurtenis kan gedurende 30 dagen opnieuw worden opgevraagd.
Hoe ontvang ik inkomende facturen?
Abonneer je op de webhook voor nieuwe documenten en haal vervolgens de factuur op via het endpoint voor inkomende gegevens. Het lees-endpoint geeft ongelezen facturen weer en markeert deze als gelezen.
Wat kost de Facturatie-API?
Toegang tot de API is inbegrepen bij het Connect- Medium -abonnement. De prijzen voor partners en ondernemingen zijn afhankelijk van het volume en het leveringsmodel. Zie ‘Abonnementen en prijzen’.
