Which official SDKs are available?

Node.js / TypeScript is already available. Java and Python are coming soon. In the meantime, you can integrate from any language via direct REST using the OpenAPI 3.0 spec published at docs.beel.es.

Is there a test environment for the API?

Yes. The test environment is enabled by using an API key with the beel_sk_test_ prefix. The base URL is the same as production (https://app.beel.es/api/v1), so you can test the full functionality without emitting real invoices or sending anything to the Spanish tax authority.

How do I authenticate against the API?

Use the Authorization: Bearer header followed by your API key. For example: Authorization: Bearer beel_sk_live_... in production, or beel_sk_test_... in test mode.

What are the rate limits?

Limits are per-endpoint: NIF validation 100 req/h (with API key), CSV imports 3/h (max 1,000 records), Holded imports 5/h (max 5,000 records), bulk operations up to 50 invoices per request, and up to 10 active webhooks per account.

Are invoices created via API Verifactu-compliant?

Yes, automatically. When you issue an invoice from a Spanish-registered account, BeeL. registers it with the Spanish tax authority (AEAT), generates the official QR code, and notifies you of the status (accepted/rejected) via the verifactu.status.updated webhook. No flags needed in the request body.

Which webhook events does BeeL. expose?

Four official events: invoice.emitted (invoice created and finalized), invoice.email.sent (invoice sent by email), invoice.cancelled (invoice cancelled), and verifactu.status.updated (Verifactu status accepted/rejected by AEAT).

How does API pricing work?

Pricing is based on the monthly volume of invoices emitted. Plans range from 50 invoices/month to 5,000. Annual billing offers ~20% off monthly pricing. There is no per-call cost — only emitted invoices count, not test invoices or other endpoints.

3 official SDKs

SDKs for your favorite stack

Java, TypeScript/Node.js and Python. Generated from the OpenAPI 3.0 spec, fully typed, with automatic retries, typed errors, and webhook verification. Issue Verifactu invoices from the SDK you already use.

Test mode included · OpenAPI 3.0 downloadable

Node.js

import { BeeL } from '@beel_es/sdk';

const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY! });

// 1. Draft
const draft = await beel.invoices.create({
  type: 'STANDARD',
  recipient: { customer_id: '550e8400-e29b-41d4-a716-446655440000' },
  lines: [
    { description: 'Consulting', quantity: 1, unit_price: 100, discount_percentage: 0 },
  ],
});

// 2. Issue (assigns number + triggers VeriFactu)
const issued = await beel.invoices.issue(draft.id);
console.log(issued.invoice_number); // "A-2026/0001"

Why BeeL. SDKs

Built for production

Not a thin fetch wrapper. Every SDK ships with the toolkit your team expects from a professional API.

Types from OpenAPI 3.0

Models auto-generated from the OpenAPI contract. Full autocomplete, build-time errors, zero drift with the backend.

Automatic retries

Exponential backoff on 429 and 5xx. Client errors (400, 401, 404, 422) are never retried. Configurable.

Typed errors

BeeLAuthError, BeeLNotFoundError, BeeLValidationError, BeeLConflictError, BeeLRateLimitError. Catch by class instead of checking status codes.

Automatic Idempotency-Key

Every POST generates an Idempotency-Key. On retry, the server returns the original response instead of duplicating.

Webhook verification

WebhookVerifier included — HMAC-SHA256 with constant-time comparison. Reject spoofed payloads before processing.

PDF download

beel.downloadPdf(id) returns the buffer + suggested file name. No wrestling with Content-Disposition.

Install

One command

Pick your favorite package manager. All three SDKs are published to the official registries.

Node.js

npm install @beel_es/sdk

Java and Python are coming soon. TypeScript/Node.js is already live on npm.

Quickstart

Zero to Verifactu in 10 lines

Same flow in every language: create draft, issue. BeeL. registers the invoice with the Spanish tax authority automatically.

Node.js

import { BeeL } from '@beel_es/sdk';

const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY! });

// 1. Draft
const draft = await beel.invoices.create({
  type: 'STANDARD',
  recipient: { customer_id: '550e8400-e29b-41d4-a716-446655440000' },
  lines: [
    { description: 'Consulting', quantity: 1, unit_price: 100, discount_percentage: 0 },
  ],
});

// 2. Issue (assigns number + triggers VeriFactu)
const issued = await beel.invoices.issue(draft.id);
console.log(issued.invoice_number); // "A-2026/0001"

import es.beel.sdk.BeeL;
import es.beel.sdk.generated.model.*;

BeeL beel = new BeeL(System.getenv("BEEL_API_KEY"));

// 1. Draft
Invoice draft = beel.invoices.create(
  new CreateInvoiceRequest()
    .type("STANDARD")
    .recipient(new Recipient().customerId("550e8400-e29b-41d4-a716-446655440000"))
    .addLinesItem(new CreateInvoiceRequestLinesInner()
      .description("Consulting")
      .quantity(1)
      .unitPrice(100.0)
      .discountPercentage(0))
);

// 2. Issue
Invoice issued = beel.invoices.issue(draft.getId());
System.out.println(issued.getInvoiceNumber());

import os
from beel import BeeL

beel = BeeL(api_key=os.environ["BEEL_API_KEY"])

# 1. Draft
draft = beel.invoices.create(
    type="STANDARD",
    recipient={"customer_id": "550e8400-e29b-41d4-a716-446655440000"},
    lines=[{
        "description": "Consulting",
        "quantity": 1,
        "unit_price": 100,
        "discount_percentage": 0,
    }],
)

# 2. Issue
issued = beel.invoices.issue(draft["id"])
print(issued["invoice_number"])

Examples use beel_sk_test_ — copy-paste into your sandbox without risk.

Get started in 4 steps

Ten minutes from npm install to your first invoice registered with the tax authority.

1
Install the SDK
npm install @beel_es/sdk. TypeScript types included, zero heavy dependencies.
Node.js
```
$ npm install @beel_es/sdk
```
2
Set your test API key
Use a key with the beel_sk_test_ prefix. Nothing is sent to AEAT in sandbox mode — test the full flow with no consequences.
.env
```
BEEL_API_KEY=beel_sk_test_a1b2c3d4e5f6g7h8
```

Create your first invoice

A call to invoices.create() returns the draft with id. A second call to invoices.issue() finalizes it, assigns a number, and triggers Verifactu.

Node.js

import { BeeL } from '@beel_es/sdk';

const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY! });

// 1. Draft
const draft = await beel.invoices.create({
  type: 'STANDARD',
  recipient: { customer_id: '550e8400-e29b-41d4-a716-446655440000' },
  lines: [
    { description: 'Consulting', quantity: 1, unit_price: 100, discount_percentage: 0 },
  ],
});

// 2. Issue (assigns number + triggers VeriFactu)
const issued = await beel.invoices.issue(draft.id);
console.log(issued.invoice_number); // "A-2026/0001"

4
Listen for events
Subscribe to the verifactu.status.updated webhook so you know when the tax authority accepts the invoice in real time. HMAC signature verified by the SDK.

Transparent pricing, no surprises

The SDKs are free. You pay only for invoices emitted in production. Sandbox is unlimited.

starter

15,90€/month

or 19,90€/month billed monthly

50 invoices/month

growth

24,90€/month

or 32,90€/month billed monthly

250 invoices/month

pro

49,90€/month

or 64,90€/month billed monthly

1,000 invoices/month

scale

79,90€/month

or 109,90€/month billed monthly

2,500 invoices/month

enterprise

129,90€/month

or 164,90€/month billed monthly

5,000 invoices/month

Prices billed annually. Save ≈ 20% vs paying monthly. By subscribing you accept the Terms and Conditions, including the API terms of use.

Frequently asked questions

The SDK you already use, issuing invoices today

Free test mode. Flip to production when you're ready.

Cancel anytime · Email support

import { BeeL } from '@beel_es/sdk'; const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY! }); // 1. Draft const draft = await beel.invoices.create({ type: 'STANDARD', recipient: { customer_id: '550e8400-e29b-41d4-a716-446655440000' }, lines: [ { description: 'Consulting', quantity: 1, unit_price: 100, discount_percentage: 0 }, ], }); // 2. Issue (assigns number + triggers VeriFactu) const issued = await beel.invoices.issue(draft.id); console.log(issued.invoice_number); // "A-2026/0001"

import es.beel.sdk.BeeL; import es.beel.sdk.generated.model.*; BeeL beel = new BeeL(System.getenv("BEEL_API_KEY")); // 1. Draft Invoice draft = beel.invoices.create( new CreateInvoiceRequest() .type("STANDARD") .recipient(new Recipient().customerId("550e8400-e29b-41d4-a716-446655440000")) .addLinesItem(new CreateInvoiceRequestLinesInner() .description("Consulting") .quantity(1) .unitPrice(100.0) .discountPercentage(0)) ); // 2. Issue Invoice issued = beel.invoices.issue(draft.getId()); System.out.println(issued.getInvoiceNumber());

import os from beel import BeeL beel = BeeL(api_key=os.environ["BEEL_API_KEY"]) # 1. Draft draft = beel.invoices.create( type="STANDARD", recipient={"customer_id": "550e8400-e29b-41d4-a716-446655440000"}, lines=[{ "description": "Consulting", "quantity": 1, "unit_price": 100, "discount_percentage": 0, }], ) # 2. Issue issued = beel.invoices.issue(draft["id"]) print(issued["invoice_number"])

SDKs for your favorite stack

Types from OpenAPI 3.0

Automatic retries

Typed errors

Automatic Idempotency-Key

Webhook verification

PDF download

One command

Zero to Verifactu in 10 lines

Get started in 4 steps

Install the SDK

Set your test API key

Create your first invoice

Listen for events

Which official SDKs are available?

Is there a test environment for the API?

How do I authenticate against the API?

What are the rate limits?

Are invoices created via API Verifactu-compliant?

Which webhook events does BeeL. expose?

How does API pricing work?

The SDK you already use, issuing invoices today

SDKs for your favorite stack

Types from OpenAPI 3.0

Automatic retries

Typed errors

Automatic Idempotency-Key

Webhook verification

PDF download

One command

Zero to Verifactu in 10 lines

Get started in 4 steps

Install the SDK

Set your test API key

Create your first invoice

Listen for events

Which official SDKs are available?

Is there a test environment for the API?

How do I authenticate against the API?

What are the rate limits?

Are invoices created via API Verifactu-compliant?

Which webhook events does BeeL. expose?

How does API pricing work?

The SDK you already use, issuing invoices today