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.

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

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.

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

1. Parties: Map your customer/supplier records to seller and buyer objects. Ensure vatId uses the two-letter country prefix (e.g. DE123456789).
2. 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).
3. Tax breakdown: Provide vatRate and vatCategoryCode per line. Common category codes: S (standard rate), Z (zero-rated), E (exempt), AE (reverse charge).
4. Totals: Beliq validates that totalNetAmount + totalTaxAmount = totalGrossAmount and that line totals sum correctly.

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)));
    }
  }
}

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.

Beliq reports the syntax it saw, the profile it detected, the rule versions that ran, the verdict summary and the verifiability seal in response headers, so you can log the audit trail without parsing the body. Two worth wiring in first: x-request-id (quote it in support requests) and x-validation (a one-line verdict for your logs).

The full list, with which responses carry each one, is in the Response headers reference.

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.