Saltar al contenido

Desarrolladores

API de facturas

Consulta gratis desde tu propio código tus facturas, clientes, empresas, pagos, programaciones periódicas, archivos de proveedores subidos, informes de IVA o antigüedad y Próximas acciones ordenadas por prioridad. Lifetime Pro, por 49 € con impuestos incluidos, añade operaciones de escritura y webhooks salientes con un solo pago, sin cuota mensual ni renovación anual.

URL base

https://freebillgen.com/api/v1

Autenticación

Cada solicitud utiliza un token Bearer. Crea uno en Ajustes → Claves de API, asígnale los permisos de lectura y escritura por recurso que necesite, establece una caducidad opcional y envíalo en cada solicitud:

Authorization: Bearer <your-api-key>

Las solicitudes se autentican en la cuenta que creó la clave y se comprueban frente a los permisos asignados. Mantén el token en secreto y revócalo si queda expuesto o deja de ser necesario.

Qué puedes hacer

  • Leer facturas, clientes, empresas, pagos y programaciones periódicas
  • Crearlos y actualizarlos (API de escritura - Pro)
  • Obtener informes de IVA y de antigüedad en JSON
  • Leer la misma cola acotada de Próximas acciones que utiliza el panel
  • Leer archivos de facturas electrónicas de proveedores que hayas subido manualmente a la bandeja de entrada (no es un endpoint de recepción Peppol ni de correo electrónico)
  • Descargar mapeos genéricos OASIS UBL y UN/CEFACT CII para revisión (sin validación de perfiles)
  • Registrar endpoints de webhooks para eventos de facturas y pagos (Pro)
  • Usar Idempotency-Key en las escrituras compatibles: si cambian los datos con la misma clave, la API devuelve 409
  • Paginación por cursor mediante links.next, ajustable con per_page (máx. 100)
  • Permitir que los agentes de IA lean cualquier factura compartida mediante schema.org/Invoice JSON-LD y Accept: application/json o text/markdown en cada enlace firmado
  • Servidor MCP sin autenticación, solo lectura en https://freebillgen.com/api/mcp (get_invoice, verify_invoice) para agentes de IA

Convenciones

Idempotencia
En las llamadas compatibles de creación y acción, envía una Idempotency-Key única. Si reintentas los mismos datos, la API devuelve el resultado original. Si cambias los datos con la misma clave, devuelve 409.
Paginación
Las listas de recursos persistentes se paginan por cursor. Sigue links.next o envía ?cursor=... y ajusta ?per_page= hasta un máximo de 100. La cola acotada de acciones indica su límite y si el resultado se ha truncado.
Importes
Los importes monetarios son cadenas JSON exactas con la escala ISO 4217 de la moneda, como "121.00" para EUR o "500" para JPY. Los precios unitarios pueden conservar una precisión de entrada adicional.
IDs
Cada recurso se identifica mediante un id opaco, nunca con un número secuencial.

Ejemplo: listar tus facturas

curl https://freebillgen.com/api/v1/invoices \
  -H "Authorization: Bearer $FREEBILLGEN_API_KEY"

Abrir la referencia interactiva completa de la API →

Preguntas sobre la API de facturas

¿La API de facturas es gratuita?

Sí. La API de lectura está incluida sin coste en el plan gratuito. La API de escritura y los webhooks salientes forman parte de Lifetime Pro por 49 €, con impuestos incluidos: un pago, sin cuota mensual ni renovación anual.

¿Cómo me autentico?

Crea un token Bearer en Ajustes -> Claves de API, asígnale permisos de lectura o escritura por recurso y envíalo como cabecera Authorization: Bearer en cada solicitud. Las claves se limitan a tu propia cuenta. Puedes revocarlas o asignarles una fecha de caducidad.

¿Puedo crear facturas de forma programática?

Sí, mediante la API de escritura incluida en Pro. Produce las mismas facturas profesionales que la aplicación web, con numeración secuencial y tratamiento configurable del IVA aplicados en el servidor. La API no certifica el cumplimiento de la legislación local.

¿Cómo evito crear facturas duplicadas al reintentar?

Envía una Idempotency-Key única en la llamada de creación. Si reintentas los mismos datos con esa clave, la API devuelve el resultado original. Si reutilizas la clave con datos distintos, devuelve 409 en vez de repetir silenciosamente otra factura.

¿Puedo leer las facturas que he recibido?

Sí, gratis. GET /api/v1/inbox enumera los archivos UBL/CII compatibles de proveedores que subiste manualmente y que FreeBillGen analizó, conservando el original para auditoría. GET /api/v1/inbox/{id} devuelve uno de ellos. Reconocer la sintaxis no equivale a validar un perfil, y estos endpoints no convierten FreeBillGen en un endpoint de recepción Peppol, de una red pública ni de correo electrónico.

¿Puede un agente de IA leer una factura sin una cuenta?

Sí. Cada factura que compartes mediante su enlace público firmado puede ser leída por agentes en esa misma URL. La página incorpora schema.org/Invoice JSON-LD; al enviar Accept: application/json devuelve una factura estructurada con partes, partidas, totales, saldo pendiente y opciones de pago, mientras que Accept: text/markdown devuelve una representación clara y compacta. También hay un servidor Model Context Protocol (MCP) sin autenticación y de solo lectura en https://freebillgen.com/api/mcp, con las herramientas get_invoice y verify_invoice. La firma del enlace es el token de acceso. Trata la URL completa como un secreto, porque cualquiera que la reciba puede abrir la factura.

Consigue una clave de API gratis

Crea una cuenta, abre Ajustes -> Claves de API y empieza gratis con la API de lectura. No se exige tarjeta. Si más adelante necesitas operaciones de escritura o webhooks salientes, Lifetime Pro cuesta 49 € una sola vez, con impuestos incluidos y sin renovación.

Crear una cuenta