Integration guides

Practical guides for integrating Beliq into your invoicing, ERP, and accounting workflows.

These guides cover topics that apply across countries and invoice formats.

Choosing a standard and profile

Beliq supports multiple e-invoice standards. Pick the one that fits your use case:

Use case	Standard	Profile	Output
German B2G invoicing (Leitweg-ID)	`xrechnung`	`xrechnung` (default)	`xml`
German hybrid invoices (human + machine readable)	`zugferd`	`en16931` or `basic`	`pdf`
French hybrid invoices	`facturx`	`en16931` or `basic`	`pdf`
Cross-border EU via Peppol Network (incl. Belgium B2B)	`peppol-bis`	`peppol` (default)	`xml`

If you omit profile, Beliq picks the safest default for the chosen standard. See the Peppol BIS Billing 3.0 reference for what the peppol profile produces, and the country guides for country-specific requirements.

Mapping your data to Beliq’s invoice schema

Beliq’s invoice schema follows EN 16931. When mapping from your system:

Parties: Map your customer/supplier records to seller and buyer objects. Ensure vatId uses the two-letter country prefix (e.g. DE123456789).
Line items: Each line needs quantity, unitCode (UN/ECE Rec. 20), unitPrice, and lineTotal. Common unit codes: C62 (units), HUR (hours), DAY (days), KGM (kilograms).
Tax breakdown: Provide vatRate and vatCategoryCode per line. Common category codes: S (standard rate), Z (zero-rated), E (exempt), AE (reverse charge).
Totals: Beliq validates that totalNetAmount + totalTaxAmount = totalGrossAmount and that line totals sum correctly.

Idempotency and retries

If a generate request times out or fails with a 5xx error, it is safe to retry. Sending the same invoice payload again produces the same result.

For production integrations, implement exponential backoff:

async function generateWithRetry(payload, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch("https://api.beliq.eu/v1/generate", {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(payload),
      });
      if (response.ok) return response;
      if (response.status < 500) throw new Error(`Client error: ${response.status}`);
    } catch (err) {
      if (attempt === maxRetries) throw err;
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
    }
  }
}

Webhooks

Beliq can post signed event notifications to your endpoint when jobs finish, quota thresholds are crossed, or a subscription changes. See the Webhooks reference for the event catalog, payload shapes, signature verification, and the delivery and retry behaviour.

Response headers

Every API response includes useful metadata headers:

Header	Description
`x-request-id`	Unique request identifier (UUID) for log correlation and support
`x-schematron-version`	EN 16931 Schematron version used for validation (on generate/validate responses)

Rate limits

On /v1/*, rate limits are enforced per Beliq account. If you hit a limit, the API returns 429 RATE_LIMITED; use retries with backoff and respect Retry-After.

Rate-limit response headers include x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset.

Monthly quotas are tied to your subscription plan. Check current usage in the dashboard or handle the QUOTA_EXCEEDED error code.

If you run multiple API instances, configure shared rate-limit storage so limits stay consistent.