Your business logic, our fiscal backend

curl -X POST https://app.beel.es/api/v1/invoices \
  -H "Authorization: Bearer beel_sk_test_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STANDARD",
    "recipient": { "customer_id": "550e8400-e29b-41d4-a716-446655440000" },
    "lines": [
      {
        "description": "Monthly subscription",
        "quantity": 1,
        "unit_price": 29.00,
        "discount_percentage": 0
      }
    ]
  }'

Examples use beel_sk_test_. Copy, paste and test in your sandbox without risk.

1. 1

   Event-driven: invoice from domain events

   Your app emits events (OrderCompleted, SubscriptionRenewed). A consumer listens, calls POST /invoices with Idempotency-Key = event_id and guarantees a unique invoice per event.

   Node.js

   import { BeeL } from '@beel_es/sdk';
   
   const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY! });
   
   // Create a draft invoice
   const invoice = await beel.invoices.create({
     type: 'STANDARD',
     recipient: { customer_id: '550e8400-e29b-41d4-a716-446655440000' },
     lines: [
       { description: 'Monthly subscription', quantity: 1, unit_price: 29.00, discount_percentage: 0 },
     ],
   });
   
   // Issue it to assign an invoice number and trigger VeriFactu
   const issued = await beel.invoices.issue(invoice.id);
   console.log(issued.invoice_number); // e.g. "A-2026/0001"

2. 2

   Serverless: on-demand cloud functions

   AWS Lambda, Vercel Functions or Cloudflare Workers receive a payload and fetch BeeL. Respond to the frontend with invoice_id in milliseconds and near-zero per-call cost.

3. 3

   Background jobs: async invoicing queues

   Enqueue jobs with Sidekiq, Celery or Bull. The worker calls BeeL. when it has capacity, updates your DB and notifies the user. Ideal if invoicing shouldn't block the frontend.

4. 4

   Multi-tenant: one API key per tenant

   Your tenants table has a beel_api_key column. When invoicing, read the active tenant's key and call BeeL. with it. Each tenant is an independent fiscal entity.

5. 5

   Signed webhooks to react to the fiscal lifecycle

   Subscribe to invoice.emitted, invoice.email.sent, invoice.cancelled and verifactu.status.updated. Constant-time HMAC-SHA256 verification included in the official Node SDK.

   Node.js

   import express from 'express';
   import { WebhookVerifier } from '@beel_es/sdk';
   
   const verifier = new WebhookVerifier(process.env.BEEL_WEBHOOK_SECRET!);
   
   app.post(
     '/webhooks/beel',
     express.raw({ type: 'application/json' }),
     (req, res) => {
       try {
         const event = verifier.verify(
           req.body.toString('utf8'),
           req.headers['beel-signature'] as string,
         );
   
         // event.type is one of:
         //   'invoice.emitted' | 'invoice.email.sent'
         //   'invoice.cancelled' | 'verifactu.status.updated'
         if (event.type === 'verifactu.status.updated') {
           console.log(event.data.new_status); // 'ACCEPTED' | 'REJECTED'
         }
   
         res.status(200).send('OK');
       } catch {
         res.status(400).send('Invalid signature');
       }
     },
   );