A API de Factuza

1. Para quen é isto

Para software que xa xestiona un negocio —un taller, unha clínica, unha academia, un ERP vertical— e precisa que as súas facturas cumpran VeriFactu sen reescribir a parte fiscal. O teu sistema segue sendo o que manda; Factuza pon a numeración, a pegada encadeada, o PDF e a remisión.

O que non é: unha pasarela de sinatura nin un simple xerador de PDF. Cada factura que emites por aquí nace co seu rexistro de facturación, entra na cadea de pegadas e remítese á Axencia Tributaria igual que se a emitises desde a web.

2. Autenticación: a clave de API

Toda a API acepta dúas credenciais: o testemuño dunha persoa (o que usan a web e a app) ou unha clave de API, que é a dunha máquina. Para integrar, a túa é a segunda.

Unha clave créase desde a área de clientes, co teu usuario de administrador, e viaxa nunha cabeceira:

X-Api-Key: fzk_x8Kq2vN...

Tres regras que convén saber antes

• A clave vese unha vez. Ao creala amosámoscha enteira e non volve aparecer: na nosa base só queda a súa pegada SHA-256. Se a perdes, revócase e créase outra — non hai «recuperar», e é a propósito.
• Unha máquina non xestiona máquinas. Cunha clave non se poden crear nin revogar claves. Se unha se filtrase, quen a teña non pode fabricarse sucesoras nin borrar o rastro.
• Revogar é inmediato. A seguinte petición que use esa clave recibe un 401. Non hai caché nin xanela de graza.

A clave herda os permisos da túa conta: os seus emisores, o seu plan e a súa licenza. Non pode emitir a nome dun NIF que non sexa o teu, e se a túa licenza caduca deixa de emitir igual que a web — pero segue podendo consultar e descargar o xa emitido, porque os teus libros son teus.

3. A túa primeira factura, paso a paso

Cinco chamadas. Todas coa mesma cabeceira e ningunha con testemuño de usuario. O exemplo usa o contorno de probas, onde nada conta nin se remite á 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. Os catro fluxos que importan

Emitir

POST /facturas para o caso simple, POST /facturas/detallada cando hai varias liñas, descontos, ou tratamentos de IVE distintos do normal (exenta, inversión do suxeito pasivo, non suxeita por localización, suplido). Sen destinatario sae unha simplificada (F2), que non dá dereito a deducir o IVE a quen a recibe.

Anular e rectificar — non son o mesmo

• POST /facturas/{id}/anular deixa a factura anulada, non borrada: xera o seu propio rexistro de anulación, que tamén se encadea e se remite.
• POST /facturas/{id}/rectificar crea unha factura nova que apunta á orixinal, e a orixinal segue existindo. É o que hai que facer cando o importe ou os datos estaban mal.

Unha factura xa cobrada non se anula. É unha regra do motor, non da interface.

Gastos

POST /gastos dá de alta un gasto deducible, que queda pendente ata que alguén o dá por bo con POST /gastos/{id}/validar. Esa parada é deliberada: un gasto mal lido que entra só na contabilidade non se nota ata que chega o trimestre.

Se tes a foto ou o PDF e non os datos, POST /ocr/analizar devolve un borrador co que leu e unha lista de en que non se fía de si mesmo. Nunca crea o gasto: propono.

Exportación legal

GET /exportar/registros?desde=&hasta= devolve os rexistros de facturación no formato estandarizado do artigo 10 do RD 1007/2023: un XML por rexistro, a cadea de pegadas en CSV e un manifesto para poder recalculalas e comprobar que ninguén tocou nada. É o que hai que poder entregar nunha inspección.

GET /exportar/gestoria é outra cousa distinta: o paquete cómodo para o asesor, con PDF e CSV.

5. Cotas e límites

A asimetría é deliberada e paga a pena entendela: un tope mensual que cortase a emisión deixaría a un obrigado tributario sen poder cumprir a lei por un asunto comercial noso. Emitir unha factura non é un capricho, ten data. Así que o tope mensual avisa e cóbrase.

O límite por minuto si corta, e por un motivo distinto: un bucle roto nunha integración non é a obriga legal de ninguén — é unha avaría que, sen freo, leva por diante o servizo dos demais. O 429 ademais avísate de que tes un fallo.

6. Erros

Os erros traen un corpo JSON con error e, cando axuda, un detalle. Están escritos para que se entendan sen coñecer as nosas tripas: «No puedes emitir facturas a nombre de X. Tu cuenta emite como Y» di que pasa e como se arranxa.

7. Catálogo de rutas

O máis usado. Todas colgan de https://func-factuza-prod-obt1.azurewebsites.net/api en produción e de …-test-… en probas.

Hai máis de sesenta rutas en total —orzamentos, recorrentes, cobros, series, usuarios—. Se botas en falta algunha, escríbenos e dicímosche se existe.

8. Compromiso de versión

• Non quitamos nin renomeamos campos dunha resposta sen avisar con 90 días. Engadir campos novos si pode pasar en calquera momento: o teu cliente debe ignorar os que non coñeza.
• Non cambiamos o significado dun campo existente. Se algo ten que significar outra cousa, será un campo novo.
• Os códigos de estado son parte do contrato. Se hoxe unha operación responde 201, seguirá respondendo 201.
• Os cambios que rompen anúncianse por correo ás contas con clave viva, non só nunha páxina que hai que ir mirar.