La API de Factuza

1. Para quién es esto

Para software que ya gestiona un negocio —un taller, una clínica, una academia, un ERP vertical— y necesita que sus facturas cumplan VeriFactu sin reescribir la parte fiscal. Tu sistema sigue siendo el que manda; Factuza pone la numeración, la huella encadenada, el PDF y la remisión.

Lo que no es: una pasarela de firma ni un simple generador de PDF. Cada factura que emites por aquí nace con su registro de facturación, entra en la cadena de huellas y se remite a la Agencia Tributaria igual que si la hubieras emitido desde la web.

2. Autenticación: la clave de API

Toda la API acepta dos credenciales: el token de una persona (lo que usan la web y la app) o una clave de API, que es la de una máquina. Para integrar, la tuya es la segunda.

Una clave se crea desde el área de clientes, con tu usuario de administrador, y viaja en una cabecera:

X-Api-Key: fzk_x8Kq2vN...

Tres reglas que conviene saber antes

• La clave se ve una vez. Al crearla te la enseñamos entera y no vuelve a aparecer: en nuestra base solo queda su huella SHA-256. Si la pierdes, se revoca y se crea otra — no hay «recuperar», y es a propósito.
• Una máquina no gestiona máquinas. Con una clave no se pueden crear ni revocar claves. Si una se filtrara, quien la tenga no puede fabricarse sucesoras ni borrar el rastro.
• Revocar es inmediato. La siguiente petición que use esa clave recibe un 401. No hay caché ni ventana de gracia.

La clave hereda los permisos de tu cuenta: sus emisores, su plan y su licencia. No puede emitir a nombre de un NIF que no sea el tuyo, y si tu licencia caduca deja de emitir igual que la web — pero sigue pudiendo consultar y descargar lo ya emitido, porque tus libros son tuyos.

3. Tu primera factura, paso a paso

Cinco llamadas. Todas con la misma cabecera y ninguna con token de usuario. El ejemplo usa el entorno de pruebas, donde nada cuenta ni se remite a la AEAT.

curl https://func-factuza-test-obt1.azurewebsites.net/api/emisores \
  -H "X-Api-Key: $FACTUZA_CLAVE"

{ "emisores": [ { "emisorId": 2, "nif": "B87654323",
                 "nombreRazon": "Pruebas Automaticas SL" } ],
  "plan": "PYME", "tope": 1, "usados": 1, "disponibles": 0 }

curl https://func-factuza-test-obt1.azurewebsites.net/api/series \
  -H "X-Api-Key: $FACTUZA_CLAVE"

{ "series": [ { "serieId": 1, "codigo": "PRU", "activa": true,
                "siguienteNumero": "PRU-2026/0457" } ], "total": 1 }

curl -X POST https://func-factuza-test-obt1.azurewebsites.net/api/facturas \
  -H "X-Api-Key: $FACTUZA_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "nifEmisor": "B87654323",
    "nombreEmisor": "Pruebas Automaticas SL",
    "numSerieFactura": "",          // lo pone la serie
    "serieId": 1,
    "fechaExpedicion": "2026-08-23",
    "tipoFactura": "F1",
    "descripcion": "Primera factura por API",
    "nifDestinatario": "B12345674",
    "nombreDestinatario": "Cliente de pruebas SL",
    "baseImponible": 100,
    "tipoImpositivo": 21
  }'

{ "facturaId": 457,
  "numSerieFactura": "PRU-2026/0457",
  "huella": "9F2A…64 caracteres en hexadecimal" }

curl https://func-factuza-test-obt1.azurewebsites.net/api/facturas/457/pdf \
  -H "X-Api-Key: $FACTUZA_CLAVE" -o factura.pdf

curl https://func-factuza-test-obt1.azurewebsites.net/api/claves-api/consumo \
  -H "X-Api-Key: $FACTUZA_CLAVE"

{ "desde": "2026-08-01…", "hasta": "2026-09-01…",
  "porEmisor": [ { "nif": "B87654323", "registros": 12,
                   "incluidos": 3000, "restantes": 2988,
                   "exceso": 0, "eurosDeExceso": 0 } ],
  "totalRegistros": 12, "peticionesPorMinuto": 120 }

4. Los cuatro flujos que importan

Emitir

POST /facturas para el caso simple, POST /facturas/detallada cuando hay varias líneas, descuentos, o tratamientos de IVA distintos del normal (exenta, inversión del sujeto pasivo, no sujeta por localización, suplido). Sin destinatario sale una simplificada (F2), que no da derecho a deducir el IVA a quien la recibe.

Anular y rectificar — no son lo mismo

• POST /facturas/{id}/anular deja la factura anulada, no borrada: genera su propio registro de anulación, que también se encadena y se remite.
• POST /facturas/{id}/rectificar crea una factura nueva que apunta a la original, y la original sigue existiendo. Es lo que hay que hacer cuando el importe o los datos estaban mal.

Una factura ya cobrada no se anula. Es una regla del motor, no de la interfaz.

Gastos

POST /gastos da de alta un gasto deducible, que queda pendiente hasta que alguien lo da por bueno con POST /gastos/{id}/validar. Esa parada es deliberada: un gasto mal leído que entra solo en la contabilidad no se nota hasta que llega el trimestre.

Si tienes la foto o el PDF y no los datos, POST /ocr/analizar devuelve un borrador con lo que ha leído y una lista de en qué no se fía de sí mismo. Nunca crea el gasto: lo propone.

Exportación legal

GET /exportar/registros?desde=&hasta= devuelve los registros de facturación en el formato estandarizado del artículo 10 del RD 1007/2023: un XML por registro, la cadena de huellas en CSV y un manifiesto para poder recalcularlas y comprobar que nadie ha tocado nada. Es lo que hay que poder entregar en una inspección.

GET /exportar/gestoria es otra cosa distinta: el paquete cómodo para el asesor, con PDF y CSV.

5. Cuotas y límites

La asimetría es deliberada y vale la pena entenderla: un tope mensual que cortara la emisión dejaría a un obligado tributario sin poder cumplir la ley por un asunto comercial nuestro. Emitir una factura no es un capricho, tiene fecha. Así que el tope mensual avisa y se cobra.

El límite por minuto sí corta, y por un motivo distinto: un bucle roto en una integración no es la obligación legal de nadie — es una avería que, sin freno, se lleva por delante el servicio de los demás. El 429 además te avisa de que tienes un fallo.

6. Errores

Los errores traen un cuerpo JSON con error y, cuando ayuda, un detalle. Están escritos para que se entiendan sin conocer nuestras tripas: «No puedes emitir facturas a nombre de X. Tu cuenta emite como Y» dice qué pasa y cómo se arregla.

7. Catálogo de rutas

Lo más usado. Todas cuelgan de https://func-factuza-prod-obt1.azurewebsites.net/api en producción y de …-test-… en pruebas.

Hay más de sesenta rutas en total —presupuestos, recurrentes, cobros, series, usuarios—. Si echas en falta alguna, escríbenos y te decimos si existe.

8. Compromiso de versión

• No quitamos ni renombramos campos de una respuesta sin avisar con 90 días. Añadir campos nuevos sí puede pasar en cualquier momento: tu cliente debe ignorar los que no conozca.
• No cambiamos el significado de un campo existente. Si algo tiene que significar otra cosa, será un campo nuevo.
• Los códigos de estado son parte del contrato. Si hoy una operación responde 201, seguirá respondiendo 201.
• Los cambios que rompen se anuncian por correo a las cuentas con clave viva, no solo en una página que hay que ir a mirar.