L'API de Factuza

1. Per a qui és això

Per a programari que ja gestiona un negoci —un taller, una clínica, una acadèmia, un ERP vertical— i necessita que les seves factures compleixin VeriFactu sense reescriure la part fiscal. El teu sistema continua sent el que mana; Factuza hi posa la numeració, l'empremta encadenada, el PDF i la remissió.

El que no és: una passarel·la de signatura ni un simple generador de PDF. Cada factura que emets per aquí neix amb el seu registre de facturació, entra a la cadena d'empremtes i es remet a l'Agència Tributària igual que si l'haguessis emès des del web.

2. Autenticació: la clau d'API

Tota l'API accepta dues credencials: el testimoni d'una persona (el que fan servir el web i l'app) o una clau d'API, que és la d'una màquina. Per integrar, la teva és la segona.

Una clau es crea des de l'àrea de clients, amb el teu usuari d'administrador, i viatja en una capçalera:

X-Api-Key: fzk_x8Kq2vN...

Tres regles que convé saber abans

• La clau es veu una vegada. En crear-la te l'ensenyem sencera i no torna a aparèixer: a la nostra base només en queda l'empremta SHA-256. Si la perds, es revoca i se'n crea una altra — no hi ha «recuperar», i és a propòsit.
• Una màquina no gestiona màquines. Amb una clau no es poden crear ni revocar claus. Si una es filtrés, qui la tingui no es pot fabricar successores ni esborrar el rastre.
• Revocar és immediat. La petició següent que faci servir aquella clau rep un 401. No hi ha memòria cau ni finestra de gràcia.

La clau hereta els permisos del teu compte: els seus emissors, el seu pla i la seva llicència. No pot emetre a nom d'un NIF que no sigui el teu, i si la teva llicència caduca deixa d'emetre igual que el web — però continua podent consultar i descarregar el ja emès, perquè els teus llibres són teus.

3. La teva primera factura, pas a pas

Cinc crides. Totes amb la mateixa capçalera i cap amb testimoni d'usuari. L'exemple fa servir l'entorn de proves, on res no compta ni es remet a l'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. Els quatre fluxos que importen

Emetre

POST /facturas per al cas simple, POST /facturas/detallada quan hi ha diverses línies, descomptes, o tractaments d'IVA diferents del normal (exempta, inversió del subjecte passiu, no subjecta per localització, suplert). Sense destinatari surt una simplificada (F2), que no dona dret a deduir l'IVA a qui la rep.

Anul·lar i rectificar — no són el mateix

• POST /facturas/{id}/anular deixa la factura anul·lada, no esborrada: genera el seu propi registre d'anul·lació, que també s'encadena i es remet.
• POST /facturas/{id}/rectificar crea una factura nova que apunta a l'original, i l'original continua existint. És el que cal fer quan l'import o les dades estaven malament.

Una factura ja cobrada no s'anul·la. És una regla del motor, no de la interfície.

Despeses

POST /gastos dona d'alta una despesa deduïble, que queda pendent fins que algú la dona per bona amb POST /gastos/{id}/validar. Aquella aturada és deliberada: una despesa mal llegida que entra sola a la comptabilitat no es nota fins que arriba el trimestre.

Si tens la foto o el PDF i no les dades, POST /ocr/analizar retorna un esborrany amb el que ha llegit i una llista de què no es fia d'ell mateix. Mai no crea la despesa: la proposa.

Exportació legal

GET /exportar/registros?desde=&hasta= retorna els registres de facturació en el format estandarditzat de l'article 10 del RD 1007/2023: un XML per registre, la cadena d'empremtes en CSV i un manifest per poder recalcular-les i comprovar que ningú no ha tocat res. És el que cal poder lliurar en una inspecció.

GET /exportar/gestoria és una altra cosa diferent: el paquet còmode per a l'assessor, amb PDF i CSV.

5. Quotes i límits

L'asimetria és deliberada i val la pena entendre-la: un topall mensual que tallés l'emissió deixaria un obligat tributari sense poder complir la llei per un assumpte comercial nostre. Emetre una factura no és un caprici, té data. Així que el topall mensual avisa i es cobra.

El límit per minut sí que talla, i per un motiu diferent: un bucle trencat en una integració no és l'obligació legal de ningú — és una avaria que, sense fre, s'enduu per davant el servei dels altres. El 429 a més t'avisa que tens una fallada.

6. Errors

Els errors porten un cos JSON amb error i, quan ajuda, un detalle. Estan escrits perquè s'entenguin sense conèixer les nostres entranyes: «No puedes emitir facturas a nombre de X. Tu cuenta emite como Y» diu què passa i com s'arregla.

7. Catàleg de rutes

El més utilitzat. Totes pengen de https://func-factuza-prod-obt1.azurewebsites.net/api en producció i de …-test-… en proves.

Hi ha més de seixanta rutes en total —pressupostos, recurrents, cobraments, sèries, usuaris—. Si te'n falta alguna, escriu-nos i et diem si existeix.

8. Compromís de versió

• No treiem ni reanomenem camps d'una resposta sense avisar amb 90 dies. Afegir camps nous sí que pot passar en qualsevol moment: el teu client ha d'ignorar els que no conegui.
• No canviem el significat d'un camp existent. Si alguna cosa ha de significar una altra cosa, serà un camp nou.
• Els codis d'estat són part del contracte. Si avui una operació respon 201, continuarà responent 201.
• Els canvis que trenquen s'anuncien per correu als comptes amb clau viva, no només en una pàgina que cal anar a mirar.