API de Facturatum: integra tu facturación con claves de API y permisos por ámbito

Qué es la API de Facturatum y para qué sirve

La API de Facturatum es la API de usuario del producto: las mismas operaciones que hace la aplicación web (facturas, clientes, contabilidad, tesorería, bancos, modelos de Hacienda) disponibles para tus propios programas. No es una versión reducida ni un segundo sistema: lo que creas por API aparece en la app, cuenta para la contabilidad y, al emitirse, genera su registro Verifactu.

Sirve para no teclear dos veces: crear facturas desde los pedidos de tu tienda online, sincronizar clientes con tu CRM, llevar los datos de tesorería a tu cuadro de mando o consultar el resultado del IVA antes de cerrar el trimestre.

Para quién es

• Equipos técnicos de pymes que quieren unir su ERP, su tienda o su TPV con la facturación.
• Desarrolladores freelance e integradores que montan automatizaciones para sus clientes.
• Asesorías con herramientas propias que necesitan leer datos contables o fiscales de sus clientes.
• Quien quiera usar agentes de IA: para ese caso está el servidor MCP, con OAuth y sobre esta misma API.

Autenticación con claves de API

Cada clave tiene el formato `fkt_<prefijo>_<secreto>` y se envía en la cabecera `X-Api-Key`. Una clave actúa como el usuario que la creó: se aplican sus permisos en cada empresa, su suscripción y sus cuotas, igual que si trabajara en la app. Por eso una clave nunca da más poder que su propietario: si el usuario tiene rol de solo lectura, la clave recibe un 403 al intentar escribir aunque tenga el ámbito de escritura.

• El secreto se muestra una sola vez, al crear la clave; Facturatum guarda solo su hash.
• Caduca a los 90 días por defecto; una clave sin caducidad hay que pedirla de forma explícita.
• La API tiene operaciones para crear, listar (sin secretos) y revocar claves con una sesión de usuario, pero aún no hay pantalla en la aplicación: mientras tanto, las claves se emiten bajo petición. Si no se indican ámbitos, la clave nace con `invoices:read`, `invoices:validate`, `clients:read` y `dashboard:read`.
• Si creas la clave indicando una empresa (`X-Company-Id`), solo sirve para esa empresa: usarla con otra responde 403.
• Cada usuario puede tener hasta 10 claves activas, y revocar una no afecta a las demás.

1. 1

   Consigue una clave con los ámbitos justos

   Pide acceso; para facturar necesitas al menos `invoices:validate` e `invoices:write`. Guarda el secreto en tu gestor de secretos.

2. 2

   Valida la factura

   Envías el contenido a `POST /api/invoices/validate`. Si es válida, la respuesta incluye un `validationToken`.

3. 3

   Crea el borrador

   Llamas a `POST /api/invoices` con `asDraft: true` y la cabecera `X-Validation-Token`. El token vale una vez, durante 30 minutos, y está ligado a tu usuario, la empresa y ese contenido. Sin `asDraft`, la factura se emite en la misma llamada.

4. 4

   Edita si hace falta

   Para un `PUT /api/invoices/{id}` repites la validación y envías un token nuevo.

5. 5

   Emite con cuidado

   Emitir genera el registro Verifactu y lo remite a la AEAT: es irreversible y exige el permiso de emisión del usuario.

Códigos de respuesta que conviene tratar

Documentación y contrato

El contrato completo está en Swagger (`/swagger-ui/index.html`) y en OpenAPI (`/v3/api-docs`), con los esquemas de autenticación por JWT y por `X-Api-Key`; en producción requieren autenticación. Te damos acceso cuando habilitamos tu integración. La documentación técnica de Politeia Soft está en docs.politeiasoft.com. Si tienes dudas sobre una integración, escríbenos.

Buenas prácticas de integración

• Crea una clave por integración y dale solo los ámbitos que usa.
• Usa un usuario con el rol mínimo: solo lectura si la integración solo consulta.
• No subas las claves al repositorio ni las pegues en un chat; si se filtran, revócalas.
• Renueva las claves antes de que caduquen en lugar de pedirlas sin caducidad.
• Envía siempre `X-Company-Id` y comprueba que es la empresa correcta antes de escribir.
• Crea siempre con `asDraft: true` y emite en un paso aparte: la emisión es irreversible.

Cuánto cuesta

Las claves funcionan con la suscripción del usuario a Facturatum Pro (5,99 € al mes o 59,90 € al año, IVA incluido) y respetan las mismas cuotas que la aplicación. Para pedir acceso, escríbenos.