Test mode

Test and live API keys. A test-mode key runs the real engine but never bills, never reaches a real network, and returns sandbox-marked output, so you can build and rehearse against production behaviour before you go 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 real network. Build and rehearse your integration with a test key, then switch to a live key for production.

Key prefixes

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.

Creating a test key

1. Sign in to the Beliq dashboard.
2. Go to Settings → 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.

What a test key does

• Never bills. Test calls do not count against your monthly document quota and never appear on an invoice.
• Never reaches a real network. Delivery is refused for a test key. Once send and receive ship, a test key exercises them against provider sandboxes only.
• Returns sandbox-marked output (see below), so a specimen can never be mistaken for a production invoice.
• Runs the real engine. Same formats, same authority-pinned 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).

Sandbox markers

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.
• XML output carries a comment inserted right after the XML declaration, for example:

<?xml version="1.0" encoding="UTF-8"?>
<!-- beliq SANDBOX / SPECIMEN: generated with a test-mode API key. Not a 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.

What test mode covers today

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

Send and receive are in development and return 503 TRANSMISSION_DISABLED for every key, live or test. When they ship, a test key will run them against provider sandboxes: real message flow and status transitions, never a real network and never billed.

Rate and volume caps

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.

Telling live and test apart in responses

• Every /v1/* response carries an x-beliq-livemode header, true on a live key and false on a test key.
• GET /v1/me returns the keyPrefix of the calling key, so you can confirm which one your integration is using.
• Every webhook event carries livemode in its envelope. Test activity is livemode: false, so you can route or drop it in your handler.

Example

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.