3 SDKs oficiales

SDKs para tu stack favorito

Java, TypeScript/Node.js y Python. Generados desde la spec OpenAPI 3.0, con tipos completos, reintentos automáticos, errores tipados y verificación de webhooks. Emite facturas Verifactu con el SDK que ya usas.

Empezar gratis Ver documentación

7 días gratis · sin tarjeta · OpenAPI 3.0 descargable

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"

Por qué los SDKs de BeeL.

¿Qué incluyen los SDK de facturación de BeeL.?

No son un wrapper fino sobre fetch. Cada SDK trae el kit que tu equipo espera en cualquier API profesional.

Tipos desde OpenAPI 3.0

Modelos auto-generados desde el contrato OpenAPI. Autocompletado total, errores en build, zero drift con el backend.

Reintentos automáticos

Backoff exponencial en 429 y 5xx. Los errores de cliente (400, 401, 404, 422) nunca se reintentan. Configurable.

Errores tipados

BeeLAuthError, BeeLNotFoundError, BeeLValidationError, BeeLConflictError, BeeLRateLimitError. Captura por tipo en lugar de mirar el status.

Idempotency-Key automático

Cada POST genera un Idempotency-Key. Si reintentas, el servidor devuelve la respuesta original en lugar de duplicar.

Verificación de webhooks

WebhookVerifier incluido — HMAC-SHA256 con comparación en tiempo constante. Rechaza payloads falsos antes de procesarlos.

Descarga de PDF

beel.downloadPdf(id) devuelve el buffer + nombre de archivo sugerido. Sin pelearse con Content-Disposition.

Instalar

En un solo comando

Elige tu gestor de paquetes favorito. Los tres SDKs están disponibles en los registros oficiales.

Node.js

npm install @beel_es/sdk

Java y Python llegan pronto. TypeScript/Node.js ya está publicado en npm.

Quickstart

De cero a Verifactu en 10 líneas

El mismo flujo en cualquier lenguaje: crear borrador, emitir. BeeL. registra la factura ante la AEAT automáticamente.

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"])

Los ejemplos usan beel_sk_test_ — copia y pega en tu sandbox sin riesgo.

Cómo empezar en 4 pasos

Diez minutos desde el npm install hasta tu primera factura registrada ante Hacienda.

1
Instala el SDK
npm install @beel_es/sdk. Tipos TypeScript incluidos, zero dependencias pesadas.
Node.js
$ npm install @beel_es/sdk
2
Configura tu API key de test
Usa una key con prefijo beel_sk_test_. Nada se envía a la AEAT en modo sandbox, puedes probar todo el flujo sin consecuencias.
.env
BEEL_API_KEY=beel_sk_test_a1b2c3d4e5f6g7h8

Crea tu primera factura

Una llamada a invoices.create() te devuelve el borrador con id. Otra llamada a invoices.issue() la finaliza, asigna número y dispara 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
Escucha los eventos
Suscríbete al webhook verifactu.status.updated para saber cuándo la AEAT acepta tu factura en tiempo real. Firma HMAC verificada por el SDK.

La suite de desarrollador

¿Quieres la integración montada sola?

La CLI, el SDK tipado y el plugin de Claude Code son la misma caja de herramientas. Instala el plugin y Claude monta la integración por ti —y la verifica con la CLI contra el sandbox antes de tocar producción.

Estás aquí

SDK de Node/TypeScript

El código que tu producto envía a producción: tipado, con reintentos automáticos e idempotencia.

$npm i @beel_es/sdk

CLI

Opera y automatiza desde la terminal o tu CI. Agent-first y sandbox por defecto.

$npx @beel_es/cli invoices create

Ver

Plugin de Claude Code

Claude lee la doc y monta la integración por ti, y la verifica con la CLI contra el sandbox.

$/plugin install beel-api@beel

Ver

Pricing transparente, sin sorpresas

Los SDKs son gratis. Pagas por facturas emitidas en producción. El sandbox es ilimitado.

Ver precios

Preguntas frecuentes

¿Qué SDKs oficiales hay disponibles?

Node.js / TypeScript ya está disponible. Java y Python llegan pronto. Mientras tanto, puedes integrar cualquier lenguaje vía REST directo usando la especificación OpenAPI 3.0 publicada en docs.beel.es.

¿Hay entorno de pruebas para la API?

Sí. El entorno de pruebas se activa usando una API key con prefijo beel_sk_test_. La URL base es la misma que en producción (https://app.beel.es/api/v1), así que puedes probar toda la funcionalidad sin emitir facturas reales ni enviar nada a la AEAT.

¿Cómo me autentico contra la API?

Usa el header Authorization: Bearer seguido de tu API key. Por ejemplo: Authorization: Bearer beel_sk_live_... en producción, o beel_sk_test_... en pruebas.

¿Cuáles son los rate limits?

Los límites son por endpoint: validación de NIF 100 req/h (con API key), importación CSV 3/h (máx. 1.000 registros), operaciones masivas hasta 50 facturas por request, y hasta 10 webhooks activos por cuenta.

¿Las facturas creadas por API cumplen con Verifactu?

Sí, de forma automática. Cuando emites una factura para un emisor español, BeeL. la registra ante la AEAT, genera el QR oficial y te notifica el estado (aceptada/rechazada) vía webhook verifactu.status.updated. No necesitas añadir flags en el request.

¿Qué eventos webhook ofrece BeeL.?

Cuatro eventos oficiales: invoice.emitted (factura creada y finalizada), invoice.email.sent (factura enviada por email), invoice.cancelled (factura cancelada), y verifactu.status.updated (estado Verifactu aceptado/rechazado por la AEAT).

¿Cómo funciona el pricing de la API?

El precio depende del volumen mensual de facturas emitidas. Los planes van desde 250 facturas/mes hasta 5.000. La facturación anual ofrece un ~20% de descuento sobre la mensual. No hay coste por llamada: sólo cuentan las facturas emitidas, no las de prueba ni los demás endpoints.

El SDK que ya usas, facturando desde hoy

Modo test gratuito. Pasa a producción cuando estés listo.

Crear cuenta gratis Leer los docs

7 días gratis · sin tarjeta · Soporte por email

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 para tu stack favorito

Tipos desde OpenAPI 3.0

Reintentos automáticos

Errores tipados

Idempotency-Key automático

Verificación de webhooks

Descarga de PDF

En un solo comando

De cero a Verifactu en 10 líneas

Cómo empezar en 4 pasos

Instala el SDK

Configura tu API key de test

Crea tu primera factura

Escucha los eventos

¿Quieres la integración montada sola?

SDK de Node/TypeScript

CLI

Plugin de Claude Code

Pricing transparente, sin sorpresas

El SDK que ya usas, facturando desde hoy

SDKs para tu stack favorito

Tipos desde OpenAPI 3.0

Reintentos automáticos

Errores tipados

Idempotency-Key automático

Verificación de webhooks

Descarga de PDF

En un solo comando

De cero a Verifactu en 10 líneas

Cómo empezar en 4 pasos

Instala el SDK

Configura tu API key de test

Crea tu primera factura

Escucha los eventos

¿Quieres la integración montada sola?

SDK de Node/TypeScript

CLI

Plugin de Claude Code

Pricing transparente, sin sorpresas

El SDK que ya usas, facturando desde hoy