BeeL.es
Volver a la API
Developer Tools

API de Facturación para Developers

Si facturas por código, BeeL es tu backend de facturación

Scripts automatizados, CLIs personalizados, herramientas internas. Si escribes código para facturar, la API de BeeL te da todo el motor fiscal sin construirlo. Integra en minutos, factura desde terminal o cron jobs.

¿Por qué los developers eligen la API de BeeL?

Cuando eres desarrollador y facturar es parte de tu flujo, necesitas una API que hable tu idioma: REST, JSON, idempotencia, OpenAPI.

Contrato OpenAPI 3.0 descargable

Especificación completa de todos los endpoints, parámetros, respuestas y errores. Genera clientes tipados para TypeScript, Python, Go, Rust con herramientas estándar (openapi-generator). No necesitas leer documentación humana, el contrato es la fuente de verdad.

Dos entornos: test y producción

test.beel.es para desarrollo y pruebas con datos ficticios. app.beel.es para producción con facturas reales. Misma API, datos completamente aislados. Desarrolla y prueba sin riesgo antes de desplegar.

Idempotencia nativa con headers

X-Idempotency-Key incluido en POST requests. Retry seguro sin duplicados. Si tu script falla a mitad de proceso y lo reintentas, BeeL reconoce la clave y devuelve el resultado original. Cero facturas duplicadas por errores de red o timeouts.

Authentication vía API Keys

No OAuth flows complejos. Una API key en el header X-API-Key y listo. Rotas keys desde el panel sin tocar código. Perfecto para scripts, cron jobs y CLIs donde OAuth es sobrematar.

Perfecto para CLIs y scripts

curl, httpie, Postman, tu lenguaje favorito (Node, Python, Go, Ruby). La API es REST puro sin dependencias específicas. Escribe un script bash de 10 líneas y factura desde terminal.

Sin SDKs obligatorios ni lock-in

No necesitas instalar librerías propietarias. Usa fetch, axios, requests, http.get nativo de tu lenguaje. La API es HTTP/JSON estándar. Cambias de herramienta o lenguaje sin problemas.

Casos de uso típicos para developers

Ejemplos reales de cómo developers usan la API en su día a día.

1

CLI para facturar desde terminal

Crea un script CLI que lee datos de un CSV o argumentos, llama a la API y emite facturas masivamente. Útil para importar datos o facturar lotes de trabajo completados.

  • $ beel-invoice --client acme --amount 1500 --description 'Proyecto X'
  • Script valida datos localmente antes de llamar a la API
  • Output: invoice_id y link al PDF descargado
2

Cron job mensual para facturación recurrente

Configura un cron que el día 1 de cada mes lee tu lista de clientes recurrentes (retainers, SaaS) y emite facturas automáticamente.

  • 0 9 1 * * /usr/local/bin/facturar-recurrentes.sh
  • Script itera clientes, genera factura con fecha del mes actual
  • Logs guardados para auditoría, notificaciones por Slack/email si falla
3

GitHub Actions para facturar al mergear a main

Workflow de CI que factura automáticamente cuando mergeas una PR a main. Útil si tu repo representa trabajo facturable (proyectos de clientes).

  • Trigger: on push to main
  • Lee metadata del commit o PR (cliente, horas, descripción)
  • Llama a POST /facturas si cumple condiciones (tag, label, etc.)
4

Webhook receiver para integrar con otras APIs

Servidor Express/Flask que recibe webhooks de Stripe, PayPal, Shopify, etc. y transforma los datos al formato de BeeL para emitir facturas automáticamente.

  • POST /webhook/stripe valida firma de Stripe
  • Extrae datos del evento (customer, amount, description)
  • POST a BeeL con X-Idempotency-Key = stripe_payment_id
5

Panel interno con datos de facturación en tiempo real

Frontend custom (React, Vue, Svelte) que consume GET /facturas para mostrar dashboards financieros. Filtras por fecha, cliente, exportas a CSV.

  • GET /facturas?fecha_inicio=2024-01-01&estado=emitida
  • Renderizas tablas, gráficos, métricas de facturación
  • Botón de descarga de PDF por factura (GET /facturas/:id/pdf)

Por qué la API de BeeL es developer-friendly

Diseñada pensando en automatización, integración y experiencia de desarrollo.

OpenAPI spec descargable

openapi.json disponible públicamente. Genera clientes tipados, valida requests offline, integra con herramientas de testing (Postman, Insomnia). La API es autodocumentada.

Errores claros y consistentes

Códigos HTTP estándar (400, 401, 404, 422, 500) con mensajes de error en JSON estructurados. Sabes exactamente qué falló y cómo arreglarlo sin leer docs extensas.

Latencia <200ms en producción

Infraestructura optimizada para responder rápido. Tus scripts no se bloquean esperando respuestas. Rate limit de 1000 req/hora por defecto, escalable a más con planes enterprise.

Versionado de API con retrocompatibilidad

/api/v1 es estable y no rompe hacia atrás. Si añadimos features nuevas, son opt-in. Tu código escrito hoy funcionará en 2 años sin cambios.

Preguntas frecuentes para developers

¿Hay rate limiting en la API?

Sí, 1000 requests/hora por defecto en el plan API estándar. Si llegas al límite, recibes 429 Too Many Requests con header Retry-After indicando cuándo puedes reintentar. Para volúmenes mayores, planes enterprise con rate limits personalizados.

¿Puedo hacer llamadas en paralelo o debo secuenciar?

Puedes hacer llamadas en paralelo sin problema. La API es stateless y thread-safe. Si emites 100 facturas simultáneamente (Promise.all en JS, asyncio en Python), funciona. Solo asegúrate de respetar el rate limit de 1000 req/hora.

¿Cómo manejo errores de red o timeouts?

Usa X-Idempotency-Key en todas tus llamadas POST. Si tu request falla por timeout o error de red, reintenta con la misma clave. BeeL responderá con el resultado original si la operación ya se completó, o ejecutará la operación si no llegó. Retry seguro sin duplicados.

¿Puedo usar webhooks para recibir notificaciones de BeeL?

Actualmente BeeL no envía webhooks a tu sistema (roadmap futuro). Si necesitas polling, usa GET /facturas con fecha de última sincronización para obtener facturas nuevas. Alternativamente, almacena invoice_ids cuando emites y solo consultas esas.

¿Hay SDKs oficiales para Node, Python, Go?

No hay SDKs oficiales mantenidos por BeeL. Sin embargo, puedes generar clientes tipados a partir del OpenAPI spec usando herramientas como openapi-generator o Swagger Codegen. Esto te da tipos TypeScript, clases Python, structs Go automáticamente.

¿Listo para automatizar tu facturación?

Integra la API de BeeL. y empieza a facturar en minutos.

Sin permanencia • 15€/mes hasta 250 facturas • Cancela cuando quieras