Saltar al contenido

Desarrolladores

API de facturas

Consulte gratis desde su propio código sus facturas, clientes, empresas, pagos, programaciones recurrentes, archivos de proveedores subidos, reportes de IVA o antigüedad y Próximas acciones ordenadas por prioridad. Lifetime Pro, por EUR 49.00 con impuestos incluidos, agrega 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. Cree uno en Ajustes → Claves de API, asígnele los permisos de lectura y escritura por recurso que necesite, establezca una caducidad opcional y envíelo 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. Mantenga el token en secreto y revóquelo si queda expuesto o deja de ser necesario.

Qué puede hacer

  • Leer facturas, clientes, empresas, pagos y programaciones recurrentes
  • Crearlos y actualizarlos (API de escritura - Pro)
  • Obtener reportes de IVA y de antigüedad de saldos en JSON
  • Leer la misma cola acotada de Próximas acciones que utiliza el panel
  • Leer archivos de facturas electrónicas de proveedores que haya 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íe una Idempotency-Key única. Si reintenta los mismos datos, la API devuelve el resultado original. Si cambia los datos con la misma clave, devuelve 409.
Paginación
Las listas de recursos persistentes se paginan por cursor. Siga links.next o envíe ?cursor=... y ajuste ?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 montos 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 direcciona mediante un id opaco, nunca un número secuencial.

Ejemplo: listar sus 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 gratis?

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

¿Cómo me autentico?

Cree un token Bearer en Configuración -> Claves de API, asígnele ámbitos de lectura/escritura por recurso y envíelo como un encabezado Authorization: Bearer en cada solicitud. Las claves se limitan a su propia cuenta y pueden revocarse o caducar.

¿Puedo crear facturas mediante programación?

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íe una Idempotency-Key única en la llamada de creación. Si reintenta los mismos datos con esa clave, la API devuelve el resultado original. Si reutiliza 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 lista los archivos UBL/CII compatibles de proveedores que subió 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 comparte 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, conceptos, 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. Trate la URL completa como un secreto, porque cualquiera que la reciba puede abrir la factura.

Obtenga una clave de API gratis

Cree una cuenta, abra Ajustes -> Claves de API y empiece gratis con la API de lectura. No se exige tarjeta de pago. Si más adelante necesita operaciones de escritura o webhooks salientes, Lifetime Pro cuesta EUR 49.00 una sola vez, con impuestos incluidos y sin renovación.

Crear una cuenta