DEVELOPER GUIDE · PYTHON + NODE.JS

Python and Node.js invoice validation examples.

Start your integration with two small clients that send UTF-8 XML to POST /v1/invoices/validate. They read the API key from APIVECT_API_KEY, send an explicit Idempotency-Key and make no automatic retry.

Download Python and Node.js examples (ZIP)

Extract the ZIP into one folder. It contains both clients, a README, an MIT licence and a local stub test. No third-party client libraries are required.

1. Use synthetic input

The public synthetic Peppol example is available with its EUPL 1.2 licence notice. The client package does not include that fixture or any customer data. You can download it with the notice, or use your own non-production XML. Do not put PII in a test document unless your controls allow it.

2. Set the key and run one request

The examples are tested with Python 3.12 and Node.js 22, using the standard library and built-in fetch. Choose either client. The commands below are PowerShell; replace the placeholder with your Invoice API key.

$env:APIVECT_API_KEY = "av_live_replace_me"
python .\invoice_validate.py .\valid-invoice.xml --idempotency-key "invoice-example-001"
node .\invoice_validate.mjs .\valid-invoice.xml --idempotency-key "invoice-example-001"

Keep the key on the server or in a secret manager. The examples do not print the XML, key or authorization header. Python uses a 20-second socket-I/O timeout; Node uses a 20-second abort deadline. Python's timeout is not a total request deadline.

3. Read the result correctly

A completed validation can return HTTP 200 with valid: false. That is a validation result with findings, not a transport failure. The clients print finding codes for that response. HTTP errors are reported separately. If a timeout or network failure leaves completion uncertain, repeat the exact same bytes with the same idempotency key only after your application decides how to resolve it; do not generate a new key for an automatic retry.

4. Run the local stub test

With both runtimes installed, run the included test from the extracted folder. It starts a loopback HTTP server, verifies method/path/content type/authentication/idempotency and checks completed validations, HTTP errors, redirects and malformed responses. It sends no request to ApiVect production and uses only a synthetic key.

python test_examples.py

Read the general API quickstart · Read the Invoice Validation API contract · Understand BR-CO-10