Valinvo

Snelstart

Status: bèta. Valinvo zet een JSON-factuur om in Peppol BIS Billing 3.0.21 (België en het Peppol-netwerk), XRechnung 3.0.2 (Duitsland, UBL of CII), ZUGFeRD 2.5.2 / Factur-X 1.09.2 (pdf met ingebedde XML) of Factur-X, CII of UBL met de Franse regels (Frankrijk). Elke gemaakte factuur wordt gecontroleerd volgens de officiële regels van haar formaat voordat we ze terugsturen.

Voorwaarden: de API is alleen voor ondernemingen en valt onder de gebruiksvoorwaarden en de verwerkersovereenkomst (de Engelse versie is bindend). Zonder API-sleutel aanvaardt u ze door bij elk verzoek de header X-Accept-Terms: 1.0 (de geldende versie) mee te sturen; verzoeken zonder deze header worden geweigerd met 428 terms_not_accepted. Houders van een API-sleutel aanvaarden schriftelijk bij de uitgifte. Elk API-antwoord verwijst naar de voorwaarden in de header Link: <…/terms>; rel="terms-of-service". De proefversie zonder API-sleutel is alleen bedoeld om te testen en te evalueren: gebruik voorbeeldgegevens, geen echte facturen met persoonsgegevens van anderen.

Ondersteuning: stuur nooit echte facturen per e-mail. Stuur het validatieresultaat (regel-ID's en veldposities) of een geanonimiseerde kopie met voorbeeldwaarden naar hello@bmk-hub.com, of gebruik het contactformulier.

Formaten opvragen

curl https://valinvo.bmk-hub.com/v1/formats
Formaat-IDFormaatGebruik
xrechnung-ublXRechnung 3.0.2, UBL 2.1Duitse overheid; B2B in Duitsland
xrechnung-ciiXRechnung 3.0.2, UN/CEFACT CIIHetzelfde, voor ontvangers die CII willen
peppol-bis-ublPeppol BIS Billing 3.0.21, UBL 2.1B2B in België; elke ontvanger op het Peppol-netwerk
zugferd-en16931ZUGFeRD 2.5.2 / Factur-X 1.09.2, profiel EN 16931 (PDF/A-3 + CII-XML)B2B in Duitsland als pdf die mensen kunnen lezen en software kan verwerken (bèta; de extra velden van de Franse hervorming worden nog niet ondersteund)
factur-x-frFactur-X 1.09.2, EN 16931 + BR-FR (PDF/A-3 + CII)B2B in Frankrijk: het Factur-X-bestand voor uw plateforme agréée (bèta; verzending via een PA is niet inbegrepen)
cii-frCII D22B, EN 16931 + BR-FRDezelfde Franse factuur als losse CII-XML (bèta)
ubl-frUBL 2.1, EN 16931 + BR-FRDezelfde Franse factuur als UBL-XML (bèta)

Een factuur maken

Stuur het formaat en de factuur in één JSON-body. Twee volledige voorbeelden: XRechnung (Duitsland) en Peppol (België).

curl -X POST https://valinvo.bmk-hub.com/v1/invoices \
  -H 'X-Accept-Terms: 1.0' \
  -H 'Content-Type: application/json' \
  -d @invoice.peppol-be.example.json \
  -o factuur.xml -D -

Het antwoord is het XML-bestand. De headers tonen het resultaat van de officiële controle:

X-Validation-Status: valid
X-Validation-Warnings: 0
X-Rule-Set: peppol-bis-3.0.21-ubl-invoice

Voeg -H 'Accept: application/json' toe om de XML en het volledige controlerapport in één JSON-antwoord te krijgen.

Met "format": "zugferd-en16931" is het antwoord een pdf (opslaan met -o factuur.pdf); de officiële regels controleren de XML die erin zit. In JSON-modus komt de pdf base64-gecodeerd. Een factuur zonder leverdatum krijgt één waarschuwing (PEPPOL-EN16931-R008, leeg leverelement): het ZUGFeRD-schema schrijft dat element voor, dus deze waarschuwing is te verwachten.

Gratis proefversie en API-sleutels

Zonder sleutel kunt u 2 facturen per dag (per IP-adres) maken om de API te proberen; de headers X-Trial-Limit en X-Trial-Remaining tonen hoeveel er nog over zijn, daarna krijgt u 429 trial_limit_reached. Ontwerppartners krijgen een bètasleutel (Authorization: Bearer <sleutel>) zonder daglimiet. De validator blijft gratis.

Stuur zonder sleutel één verzoek tegelijk (anders 429 one_request_at_a_time). Groottelimieten voor iedereen: factuur-JSON tot 2 MB en 2.000 regels; ZUGFeRD-pdf's tot 500 regels en 5.000 tekens per tekstveld; hoogstens 1.000 notities (100 in pdf's); getallen met hoogstens 15 cijfers voor en 10 na de komma (400 invalid_invoice); te valideren documenten tot 20 MB en 75.000 XML-elementen, ongeveer 3.000 uitgebreide regels (413 document_too_large).

Eenvoudige regels

Bij een fout

U krijgt 400 met alle problemen tegelijk, elk met het JSON-pad, de officiële regel en de EN 16931-bedrijfsterm. De meldingen van de API zijn in het Engels:

{
  "code": "invalid_invoice",
  "message": "The invoice has 1 problem. Fix it and try again.",
  "problems": [{
    "path": "invoice.buyerReference",
    "message": "Peppol requires buyerReference or orderReference.",
    "rule": "PEPPOL-EN16931-R003",
    "businessTerm": "BT-10"
  }]
}

422 generated_invoice_invalid betekent dat de gemaakte XML niet aan de officiële regels voldoet; validation.errors geeft de reden. Meestal ontbreekt een veld dat een nationale regel vereist.

Een bestaande factuur valideren

curl -X POST https://valinvo.bmk-hub.com/v1/validate \
  -H 'X-Accept-Terms: 1.0' \
  -H 'Content-Type: application/xml' \
  --data-binary @factuur.xml
{"ruleSet": "peppol-bis-3.0.21-ubl-invoice", "valid": true, "errors": [], "warnings": []}

De regelset wordt uit het document afgeleid: XRechnung 3.0 (UBL Invoice, UBL CreditNote, CII), Peppol BIS Billing 3.0 (UBL Invoice, UBL CreditNote) en ZUGFeRD 2.x / Factur-X in CII (profielen MINIMUM, BASIC WL, BASIC, EN 16931 en EXTENDED, gecontroleerd volgens de regels 2.5.2). Een ongeldige factuur is een gewoon 200-resultaat met valid: false en de lijst met fouten.

Een ZUGFeRD-/Factur-X-pdf kunt u rechtstreeks sturen. We controleren de factuur-XML die erin zit, de pdf zelf op PDF/A-3 (met veraPDF) en of de metadata van de pdf hetzelfde profiel en dezelfde bijlage noemen als de XML; de regelset heet dan bijvoorbeeld zugferd-2.5.2-en16931+pdf-a-3b. PDF/A-fouten hebben regel-ID's zoals PDF/A-3 6.2.11.4.1-1 (sectie en test van ISO 19005-3), metadatafouten beginnen met ZF-XMP:

curl -X POST https://valinvo.bmk-hub.com/v1/validate \
  -H 'X-Accept-Terms: 1.0' \
  -H 'Content-Type: application/pdf' \
  --data-binary @factuur.pdf

Een pdf zonder factuurbijlage krijgt 400 no_embedded_invoice, een onleesbare of met een wachtwoord beveiligde 400 invalid_pdf.

OpenAPI

De hele API als OpenAPI 3-beschrijving: openapi.json. Importeer die in Postman, Insomnia of een codegenerator.

Snelstart · Peppol-validator · Foutcodes