Resumen

La API de Beel es una API RESTful de facturación diseñada específicamente para autónomos en España, con soporte completo para la normativa VeriFactu.

URL Base

https://app.beel.es/api/v1/{recurso}

La URL base es la misma tanto para el entorno de sandbox como para producción. El entorno se determina automáticamente según la API Key utilizada:

• API Key de sandbox: beel_sk_test_xxx → Entorno de pruebas
• API Key de producción: beel_sk_live_xxx → Entorno de producción

Por ejemplo GET https://app.beel.es/api/v1/facturas para listar facturas.

Características principales

• Cumplimiento normativo VeriFactu (sin coste adicional)
• Gestión completa de facturas (ordinarias, rectificativas, simplificadas)
• Gestión de clientes y productos
• Configuración de impuestos y series de facturación
• Generación de PDF para todas las facturas emitidas
• Envío por email

Claves API

Las claves API se crean y gestionan desde el panel de control de Beel en app.beel.es. Cada clave API está asociada a un entorno específico (sandbox o producción).

Consulta la sección de Autenticación para más detalles sobre cómo autenticar tus peticiones.

Plan Pro

El plan Pro incluye:

• 250 facturas emitidas al mes (los borradores no cuentan para el límite)
• Generación de PDF para todas las facturas emitidas
• Envío a VeriFactu sin coste adicional
• Acceso completo a la API

Precios:

• 19€/mes + IVA (facturación mensual)
• 179€/año + IVA (facturación anual, ahorra 2 meses)

Idempotencia

Recomendamos enviar todas las peticiones de escritura (POST, PUT) con una cabecera X-Idempotency-Key para garantizar que las operaciones no se ejecuten de forma duplicada.

curl -X POST "https://app.beel.es/api/v1/facturas" \
  -H "X-API-Key: beel_sk_xxx" \
  -H "X-Idempotency-Key: mi-clave-unica-12345" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

¿Por qué es importante?

Si por un error de red o de tu aplicación envías la misma petición de creación de factura dos veces sin usar X-Idempotency-Key, se crearán dos facturas independientes y ambas contarán para tu límite de uso mensual.

Al incluir una clave de idempotencia:

• Si la petición se repite con la misma clave, la API detectará la duplicación
• Se devolverá el resultado de la primera petición sin ejecutar la operación de nuevo
• Evitas duplicados accidentales y cargos innecesarios en tu plan

La clave de idempotencia puede ser cualquier string único (UUID, referencia de tu sistema, etc.). Se recomienda usar un valor único por cada operación lógica que quieras realizar.

Métodos HTTP

La API utiliza métodos REST estándar: GET, POST, PUT y DELETE.

GET

Los métodos GET se utilizan para leer datos. El filtrado, ordenación o paginación se hace mediante parámetros de consulta.

curl "https://app.beel.es/api/v1/facturas?estado=EMITIDA&limit=10" \
  -H "X-API-Key: beel_sk_xxx"

POST

Los métodos POST se utilizan para crear nuevos recursos. Los datos se envían como application/json en el cuerpo de la petición.

curl -X POST "https://app.beel.es/api/v1/facturas" \
  -H "X-API-Key: beel_sk_xxx" \
  -H "X-Idempotency-Key: crear-factura-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "clienteId": "cliente-123",
    "lineas": [
      {
        "descripcion": "Consultoría",
        "cantidad": 1,
        "precio": 100.00
      }
    ]
  }'

PUT

Los métodos PUT se utilizan para actualizar recursos existentes.

curl -X PUT "https://app.beel.es/api/v1/clientes/cliente-123" \
  -H "X-API-Key: beel_sk_xxx" \
  -H "X-Idempotency-Key: actualizar-cliente-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Nuevo nombre del cliente"
  }'

DELETE

Los métodos DELETE se utilizan para eliminar o desactivar recursos.

curl -X DELETE "https://app.beel.es/api/v1/clientes/cliente-123" \
  -H "X-API-Key: beel_sk_xxx"