Saltar al contenido

Desarrolladores

API de facturas

Consultá gratis desde tu propio código tus facturas, clientes, empresas, pagos, programaciones periódicas, archivos de proveedores cargados, informes de IVA o antigüedad y Próximas acciones ordenadas por prioridad. Lifetime Pro, por EUR 49 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 usa un token Bearer. Creá uno en Ajustes → Claves de API, asignale los permisos de lectura o escritura que necesites para cada recurso, fijá un vencimiento opcional y envialo en cada solicitud:

Authorization: Bearer <tu-clave-de-api>

Las solicitudes se autentican en la cuenta que creó la clave y se comprueban según los permisos asignados. Mantené el token en secreto y revocalo si queda expuesto o ya no lo necesitás.

Qué podés 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 usa 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 de Peppol ni de correo electrónico)
  • Descargar mapeos genéricos de 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 y de 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, enviá una Idempotency-Key única. Si repetís datos idénticos, recibís el resultado exitoso original; si cambian, la API devuelve 409.
Paginación
Las listas de recursos guardados se paginan por cursor: seguí links.next (o pasá ?cursor=...) y ajustá ?per_page= (máx. 100). El flujo acotado de acciones informa su límite y si quedó truncado.
Importes
Los importes monetarios son cadenas JSON exactas con la escala ISO 4217 de la moneda, por ejemplo, "121.00" para EUR o "500" para JPY. Los precios unitarios pueden conservar más decimales de los ingresados.
ID
Cada recurso se direcciona por un id opaco, nunca por 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 gratis?

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 EUR 49, con impuestos incluidos: un pago, sin cuota mensual ni renovación anual.

¿Cómo me autentico?

Creá un token Bearer en Ajustes -> Claves de API, asignale permisos de lectura/escritura por recurso, y enviálo como encabezado Authorization: Bearer en cada solicitud. Las claves están limitadas a tu propia cuenta y se pueden revocar o hacer vencer.

¿Puedo crear facturas mediante programación?

Sí, mediante la API de escritura, que forma parte de Pro. Usa la misma lógica de numeración y cálculo del IVA que la aplicación web. Esto no certifica el cumplimiento fiscal de una operación.

¿Cómo evito crear facturas duplicadas al reintentar?

Enviá una Idempotency-Key única en la llamada de creación. Si repetís datos idénticos con esa clave, recibís el resultado original. Si reutilizás la clave con datos distintos, la API devuelve 409 en vez de repetir silenciosamente otra factura.

¿Puedo leer las facturas que recibí?

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 compartís por su enlace público firmado es legible por agentes en la misma URL: la página incorpora schema.org/Invoice JSON-LD, y enviar Accept: application/json devuelve una factura estructurada (partes, ítems, totales, saldo a pagar, opciones de pago), mientras que Accept: text/markdown devuelve una representación limpia y de pocos tokens. También hay un servidor de Model Context Protocol (MCP) 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. Tratá la URL completa como un secreto, porque cualquiera que la reciba puede abrir la factura.

Conseguí una clave de API gratis

Creá una cuenta, abrí Ajustes -> Claves de API y empezá gratis con la API de lectura. No se exige tarjeta. Si más adelante necesitás operaciones de escritura o webhooks salientes, Lifetime Pro cuesta EUR 49 una sola vez, con impuestos incluidos y sin renovación.

Crear una cuenta