Test mode

A test API key runs the real engine, never bills, never reaches a production network and returns sandbox-marked output, so you can rehearse before going live.

Every Beliq API key is either live or test. A test key runs the same engine, the same rulesets, and the same validation as a live key, but its output is stamped as a sandbox specimen, it never bills, and it can never reach a production network. Build and rehearse your integration with a test key, then switch to a live key for production.

The mode is baked into the key at creation and cannot be changed afterwards. You can tell them apart at a glance:

The whole key, prefix included, is hashed, so a caller cannot flip the mode by editing the string. Keys minted before test mode existed carry a plain blq_ prefix and are treated as live.

1. Sign in to the Beliq dashboard.
2. Go to Integration → API Keys and click Create API Key.
3. Choose Test or Live, give the key a label, and copy it once. Live is the default, so an omitted choice never mints a non-billing key by accident.

Each key row shows a Live or Test badge, so you always know which key does what.

The Playground runs without an API key, so it carries its own Live / Test switch. It starts on Test, which means a run you did not think about costs nothing against your plan quota and returns sandbox-marked output like any other test call. Switch it to Live when you want the production bytes.

• Never bills. Test calls do not count against your monthly document quota and never appear on an invoice.
• Never reaches a production network. A test key reaches a delivery partner’s sandbox. On Peppol that sandbox is on the real Peppol test network. See Rehearsing delivery.
• Returns sandbox-marked output (see below), so a specimen can never be mistaken for a production invoice.
• Runs the real engine. Same formats, same rulesets, same validation verdict as live. Only the billing, the network, and the marking differ.
• Has its own limits, tracked separately from your plan (see Rate and volume caps).

Test-mode output is marked so it cannot pass as a production document:

• PDF output carries a diagonal SANDBOX / SPECIMEN watermark on every page. It scales to the page size and does not obscure the content. A hybrid ZUGFeRD / Factur-X PDF that POST /v1/generate builds, or that POST /v1/convert re-wraps, is watermarked after veraPDF checked it, and the watermarked file does not pass veraPDF’s PDF/A-3b profile. With a live key, both return the file as it was checked.
• XML output carries a comment inserted right after the XML declaration, for example:

<?xml version="1.0" encoding="UTF-8"?>
<!-- beliq SANDBOX / SPECIMEN: generated in test mode. Not a valid production invoice and not transmitted to any network. -->
<rsm:CrossIndustryInvoice ...>

The XML comment is easy to strip, which is by design: the rate and volume caps are the real guardrail on test compute, and the watermark is the durable mark on rendered PDFs.

Test keys work against the live compute endpoints today: generate, validate, parse and convert.

Managed delivery is not open yet. Every transmission endpoint, POST /v1/send and the receiving surface included, answers 503 TRANSMISSION_DISABLED today in both key modes. The rest of this section is the contract a rehearsal will run under, so you can build against it; subscribe for the date it opens.

A rehearsal runs against the delivery partner’s own sandbox, not a simulator Beliq wrote. That is deliberate: a simulator that always delivers invites you to believe production will work because test did, so where a partner’s sandbox cannot do something this page says so instead of modelling it.

What that means differs by network, and it is the partner’s sandbox that sets the difference:

Your test identifier

You cannot rehearse as yourself. A document on the Peppol test network whose sender is not the registered participant would be the dishonesty the partner-sandbox choice exists to avoid, so Beliq issues your organization an identifier of its own, one per network:

curl -X POST https://api.beliq.eu/v1/participants/sandbox \
  -H "Authorization: Bearer blq_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"network":"peppol","country":"DE"}'

• It names nobody. The identifier Beliq allocates fails its country’s VAT check digit, and a tax authority only issues numbers whose check digit passes. So it cannot be a real company’s number, and it cannot collide with a real company’s live registration.
• One per organization per network. A second call hands back the one you hold and finishes an issuance a first call left half done, so it is safe to repeat. 201 when this call issued it, 200 when you already had it.
• network is peppol or sdi. Peppol also takes your organization’s own country, which becomes the country on every envelope the identifier sends. An SdI identifier takes no country, because the number names no company in any country.
• It needs a role that can write integration resources (owner, admin or developer), like an API key does. An identifier spends a registration at the partner, so a viewer or a billing member cannot issue one.
• Issuance is capped at ten calls an hour per organization, and new identifiers are capped across all organizations together, per network, because every registration is spent in one partner account everyone shares. Only a call that allocates a number counts.
• A Peppol identifier publishes Peppol BIS 3.0 and XRechnung UBL, and nothing else. Those are the two UBL syntaxes Beliq generates for Peppol. A document of another type may be refused by the access point rather than delivered.
• Publishing takes a few minutes after issuance. A send aimed at an identifier the network has not published yet is recorded as rejected by the recipient.

List your test identifiers with GET /v1/participants, called with a test key. A key lists the registrations of its own mode only, and each item says which mode it is in with livemode.

Rehearsing a send means two edits, not one

Both the request and the invoice name the sender, and Beliq refuses a send where the two disagree. So pointing a rehearsal at your test identifier means changing it in two places:

A mismatch is 400 DOCUMENT_PARTY_MISMATCH. The check compares the identifiers a document carries, so a Peppol document with no EndpointID passes it. POST /v1/send validates the document it builds, and for a Peppol BIS invoice that includes PEPPOL-EN16931-R020, “Seller electronic address MUST be provided”, a fatal rule. POST /v1/transmissions validates nothing outside a France lane: it queues the document you give it.

What arrives in your test inbox

Received documents arrive as inbound transmissions in your test mode, reach transmission.received, and are read back with GET /v1/transmissions?direction=inbound. Two things to design for:

• Anyone may send to your test identifier. A document addressed to it is filed whoever sent it, and the sender’s own identifier is shown as the counterparty. On Peppol you can send yourself one on demand with POST /v1/participants/sandbox/test-invoice, which always sends to your own identifier and never to anyone else’s.
• On Italy SdI the inbox fills by itself. The partner’s sandbox writes synthetic invoices to every company registered on Beliq’s account, roughly two to three an hour from the first sweep after your identifier is registered. They are the partner’s own feed, not your sends coming back, and they are real FatturaPA shapes across several document types, signed .p7m and bare XML. Each one fires a transmission.received webhook where you have an endpoint configured, so a handler written against Italy will see steady traffic you did not create.

Because test compute is free, test keys are capped independently of your plan. Live keys use your plan’s limits instead.

Test and live traffic use separate burst counters, so exercising a test key never eats into your production budget.

The monthly allowance runs on the UTC calendar month, so it resets on the 1st. Your plan quota does not: its window is anchored on your billing day. GET /v1/me called with a test key reports this allowance and this reset date, never the plan’s.

• Every /v1/* response carries an x-beliq-livemode header, true on a live key and false on a test key.
• GET /v1/me returns livemode in the body, alongside the keyPrefix of the calling key. Read livemode if your client only sees a parsed body, and to know which allowance the quota block describes.
• Every webhook event carries livemode in its envelope. For the job, quota and subscription events a test key emits no webhook at all: the call is recorded in your history and goes no further, so livemode is not the live/test switch for those handlers. The transmission events are the exception: a test-mode transmission does fire them, with livemode: false, to every endpoint you have. See Test mode and livemode.

curl -X POST https://api.beliq.eu/v1/validate \
  -H "Authorization: Bearer blq_test_abc123..." \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml -i

The -i flag prints the response headers, so you can see x-beliq-livemode: false confirming the call ran in test mode.