URL base
https://freebillgen.com/api/v1Autenticación
Cada solicitud utiliza un token Bearer. Crea uno en Configuración → Claves de API, asígnale los ámbitos de lectura/escritura por recurso que necesite, establece una caducidad opcional y envíalo en cada solicitud:
Authorization: Bearer <your-api-key>Las solicitudes se autentican con la cuenta que creó la clave y se verifican frente a los ámbitos asignados. Mantén el token en secreto y revócalo si queda expuesto o ya no es necesario.
Qué puedes hacer
- Leer facturas, clientes, empresas, pagos y programaciones recurrentes
- Crear y actualizar esos recursos (API de escritura - Pro)
- Obtener informes de IVA y de antigüedad de saldos en formato JSON
- Leer la misma cola acotada de próximas acciones que utiliza el panel de control
- Leer archivos de factura electrónica de proveedores que hayas subido manualmente a la Bandeja de entrada (no es un punto de recepción Peppol/correo electrónico)
- Descargar mapeos genéricos de OASIS UBL y UN/CEFACT CII para revisión (no validados por perfil)
- Registrar endpoints de webhook para eventos de facturas y pagos (Pro)
- Idempotency-Key en escrituras compatibles: si cambian los datos de la solicitud con la misma clave, se devuelve 409
- Paginación por cursor mediante links.next, ajustable con per_page (máx. 100)
- Permite que los agentes de IA lean cualquier factura compartida: schema.org/Invoice JSON-LD, además de Accept: application/json o text/markdown en cada enlace de uso compartido firmado
- Servidor MCP de solo lectura sin autenticación en https://freebillgen.com/api/mcp (get_invoice, verify_invoice) para agentes de IA
Convenciones
- Idempotencia
- En las llamadas de creación y acción compatibles, envía un Idempotency-Key único. Reintentar con datos de solicitud idénticos reproduce el éxito original; si los datos de la solicitud cambian, se devuelve 409.
- Paginación
- Las listas de recursos persistidos se paginan mediante cursor: sigue links.next (o pasa ?cursor=...) y ajusta ?per_page= (máx. 100). El feed de acciones acotado informa de su límite y de si está truncado.
- Importes
- Los importes monetarios son cadenas JSON exactas con formato ajustado a la escala ISO 4217 de la divisa; por ejemplo, "121.00" para EUR o "500" para JPY. Los precios unitarios pueden conservar una precisión de entrada adicional.
- Identificadores
- Cada recurso se identifica mediante un id opaco, nunca 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 en el plan gratuito sin coste alguno. La API de escritura y los webhooks salientes están incluidos en Lifetime Pro de 49 € (impuestos incluidos): un único pago, sin cuota mensual ni renovación anual.
¿Cómo me autentico?
Crea un token Bearer en Configuración -> Claves de API, asígnale ámbitos de lectura/escritura por recurso y envíalo como cabecera Authorization: Bearer en cada solicitud. Las claves están limitadas a tu propia cuenta y pueden revocarse o caducar.
¿Puedo crear facturas mediante programación?
Sí, a través de la API de escritura, que forma parte del complemento Pro. Genera las mismas facturas profesionales que la aplicación web, con numeración secuencial y gestión configurable del IVA aplicada en el servidor. La API no certifica el cumplimiento de la normativa local.
¿Cómo evito crear facturas duplicadas al reintentar?
Envíe una Idempotency-Key única en la llamada de creación. Si reintenta con los mismos datos de solicitud y esa clave, se devuelve el resultado original. Si la reutiliza con datos de solicitud modificados, se devuelve 409 en lugar de reproducir silenciosamente una factura distinta.
¿Puedo leer las facturas que he recibido?
Sí, gratis. GET /api/v1/inbox lista los archivos de proveedor UBL/CII compatibles que usted haya subido manualmente y FreeBillGen haya analizado, y conserva el original para auditoría; GET /api/v1/inbox/{id} devuelve uno. El reconocimiento de sintaxis no equivale a validación de perfil, y estos endpoints no convierten a FreeBillGen en un punto de recepción Peppol, de red gubernamental ni de correo electrónico.
¿Puede un agente de IA leer una factura sin una cuenta?
Sí. Cada factura que comparta mediante su enlace público firmado es legible por agentes en la misma URL: la página incluye JSON-LD de schema.org/Invoice y, al enviar Accept: application/json, se devuelve una factura estructurada (partes, líneas, totales, saldo pendiente, opciones de pago), mientras que Accept: text/markdown devuelve una representación limpia con pocos tokens. También hay un servidor MCP (Model Context Protocol) de solo lectura y sin autenticación 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, ya que cualquier persona que la reciba puede abrir la factura.