FAQ

Respostes breus a les preguntes que més sorgeixen en desenvolupar contra l'API pública de Factuarea. Cadascuna enllaça amb la guia que la cobreix per complet.

Accés i claus

Com aconsegueixo accés a l'API?

L'API està en beta privada: escriu a info@factuarea.com des de l'email associat a la teva empresa, indicant la teva raó social, tax ID, cas d'ús i volum estimat de factures. Responem en ≤ 5 dies laborables. Consulta Sol·licitar accés beta.

Aquesta clau és live o test?

Llegeix el prefix: fact_live_ opera sobre la teva empresa real (producció), fact_test_ sobre un sandbox aïllat. El prefix és la única font de veritat — cap paràmetre de la petició canvia l'entorn. Consulta Mode de prova i sandbox.

He perdut el secret de la meva API key. El puc recuperar?

No. El backend només emmagatzema un hash bcrypt del secret, que es mostra una sola vegada en crear-lo. Rota la clau des del dashboard per emetre un nou secret i torna a desplegar-lo. Consulta Autenticació › Rotació.

Com roto una clau sense downtime?

Rota des del dashboard: el secret antic i el nou es mantenen vàlids durant un període de gràcia, així que pots desplegar el nou sense perdre peticions. Revoca una clau només quan sospitis una fuita — això la invalida a l'instant (401 api_key_revoked). Consulta Autenticació › Rotació i revocació.

Mode de prova

Les dades de test estan aïllades de producció?

Sí — de manera estructural, no per un filtre. Una clau fact_test_ opera sobre una empresa sandbox dedicada, així que els recursos creats en test mai són visibles per a una clau fact_live_ (i viceversa), i la numeració fiscal de test mai toca les teves sèries de producció. Consulta Mode de prova › Aïllament de dades.

Per què no es disparen els meus webhooks en mode de prova?

En test, els efectes externs estan desactivats: VeriFactu → AEAT, FACe, els emails i l'entrega de webhooks estan tots neutralitzats. Els esdeveniments es continuen registrant amb livemode: false i es poden consultar via GET /v1/events, però no s'entreguen als teus endpoints. Usa POST /v1/webhook_endpoints/{id}/ping per provar el teu receptor. Consulta Mode de prova › Què està desactivat.

Documents

Quina diferència hi ha entre delete, annul i void d'una factura?

DELETE /v1/invoices/{id} només funciona amb esborranys. Un cop emesa una factura no es pot eliminar: usa POST /v1/invoices/{id}/annul (registra una raó documentada i crea el registre d'anul·lació d'AEAT quan VeriFactu està activat) o POST /v1/invoices/{id}/void (irreversible, registra un void_reason, rebutjat si la factura ja ha estat rectificada). Consulta Migració des de Holded › Diferències intencionades.

Diners i dates

Com es representen els imports monetaris?

En euros, amb dos decimals, a l'estil Stripe — la forma canònica és una cadena decimal com "1234.56". Parseja els diners com a decimal fix, mai com a float binari, i deixa que l'API calculi els totals a partir de les línies en brut. Consulta Imports i dates › Diners.

Quin format usen les dates?

Les dates de calendari com issued_on i due_on usen YYYY-MM-DD (per exemple 2026-05-15). Les marques de temps com created i expires_at són ISO 8601 en UTC amb sufix Z — p. ex. 2026-05-15T10:23:18Z. Consulta Imports i dates.

Quina zona horària usen les quotes?

La quota mensual del límit de peticions es reinicia el dia 1 a les 00:00 Europe/Madrid, mentre que les marques de temps es retornen en UTC. Consulta Imports i dates › Zona horària de les quotes i Límits de peticions.

Idempotència i reintents

Què passa si reenvio una Idempotency-Key?

Dins del TTL de 24h, l'API retorna la resposta cacheada (estat, headers i body) sense tornar a executar el handler, afegint el header Idempotent-Replayed: true. Un 4xx cacheat també es reenvia. Reutilitzar la clau amb un body diferent respon 409 idempotency_key_reused. Consulta Idempotència.

Un replay idempotent compta contra el meu rate limit?

No. Una clau reenviada dins del seu TTL no compta contra la teva quota. Claus diferents amb el mateix payload compten cadascuna, una a una. Consulta Idempotència › Què NO és la idempotència.

Quina és la longitud màxima de la Idempotency-Key?

Entre 1 i 64 caràcters. Qualsevol valor únic opac serveix (es recomana UUID v7, però UUID v4, ULID o nanoid també valen). Consulta Idempotència › Format de la clau.

Límits de peticions i errors

Com conec la meva quota restant?

Cada resposta (inclosa 429) porta X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset; un 429 afegeix Retry-After amb els segons que cal esperar. Els límits depenen del tier de la teva clau. Consulta Límits de peticions.

Com he de reintentar una petició fallida?

4xx (excepte 429) → no reintentis, corregeix la petició. 429 → respecta Retry-After. 5xx → back-off exponencial amb jitter, fins a 5 intents. Consulta Errors › Estratègia de reintents.

On reporto un problema amb una petició concreta?

Agafa el request_id de l'embolcall d'error (també és al header X-Request-Id) i envia'l a suport — ens permet correlacionar logs, mètriques i traces. Consulta Suport.