FAQ

Respuestas breves a las preguntas que más surgen al desarrollar contra la API pública de Factuarea. Cada una enlaza con la guía que la cubre por completo.

Acceso y claves

¿Cómo consigo acceso a la API?

La API está en beta privada: escribe a info@factuarea.com desde el email asociado a tu empresa, indicando tu razón social, tax ID, caso de uso y volumen estimado de facturas. Respondemos en ≤ 5 días laborables. Consulta Solicitar acceso beta.

¿Esta clave es live o test?

Lee el prefijo: fact_live_ opera sobre tu empresa real (producción), fact_test_ sobre un sandbox aislado. El prefijo es la única fuente de verdad — ningún parámetro de la petición cambia el entorno. Consulta Modo de prueba y sandbox.

He perdido el secreto de mi API key. ¿Puedo recuperarlo?

No. El backend solo almacena un hash bcrypt del secreto, que se muestra una sola vez al crearlo. Rota la clave desde el dashboard para emitir un nuevo secreto y vuelve a desplegarlo. Consulta Autenticación › Rotación.

¿Cómo roto una clave sin downtime?

Rota desde el dashboard: el secreto antiguo y el nuevo permanecen válidos durante un periodo de gracia, así que puedes desplegar el nuevo sin perder peticiones. Revoca una clave solo cuando sospeches una fuga — eso la invalida al instante (401 api_key_revoked). Consulta Autenticación › Rotación y revocación.

Modo de prueba

¿Los datos de test están aislados de producción?

Sí — de forma estructural, no por un filtro. Una clave fact_test_ opera sobre una empresa sandbox dedicada, así que los recursos creados en test nunca son visibles para una clave fact_live_ (y viceversa), y la numeración fiscal de test nunca toca tus series de producción. Consulta Modo de prueba › Aislamiento de datos.

¿Por qué no se disparan mis webhooks en modo de prueba?

En test, los efectos externos están desactivados: VeriFactu → AEAT, FACe, los emails y la entrega de webhooks están todos neutralizados. Los eventos se siguen registrando con livemode: false y se pueden consultar vía GET /v1/events, pero no se entregan a tus endpoints. Usa POST /v1/webhook_endpoints/{id}/ping para probar tu receptor. Consulta Modo de prueba › Qué está desactivado.

Documentos

¿Qué diferencia hay entre delete, annul y void de una factura?

DELETE /v1/invoices/{id} solo funciona con borradores. Una vez emitida una factura no se puede eliminar: usa POST /v1/invoices/{id}/annul (registra una razón documentada y crea el registro de anulación de AEAT cuando VeriFactu está activado) o POST /v1/invoices/{id}/void (irreversible, registra un void_reason, rechazado si la factura ya ha sido rectificada). Consulta Migración desde Holded › Diferencias intencionadas.

Dinero y fechas

¿Cómo se representan los importes monetarios?

En euros, con dos decimales, al estilo Stripe — la forma canónica es una cadena decimal como "1234.56". Parsea el dinero como decimal fijo, nunca como float binario, y deja que la API calcule los totales a partir de las líneas en bruto. Consulta Importes y fechas › Dinero.

¿Qué formato usan las fechas?

Las fechas de calendario como issued_on y due_on usan YYYY-MM-DD (por ejemplo 2026-05-15). Las marcas de tiempo como created y expires_at son ISO 8601 en UTC con sufijo Z — p. ej. 2026-05-15T10:23:18Z. Consulta Importes y fechas.

¿Qué zona horaria usan las cuotas?

La cuota mensual del límite de peticiones se reinicia el día 1 a las 00:00 Europe/Madrid, mientras que las marcas de tiempo se devuelven en UTC. Consulta Importes y fechas › Zona horaria de las cuotas y Límites de peticiones.

Idempotencia y reintentos

¿Qué pasa si reenvío una Idempotency-Key?

Dentro del TTL de 24h, la API devuelve la respuesta cacheada (estado, headers y body) sin volver a ejecutar el handler, añadiendo el header Idempotent-Replayed: true. Un 4xx cacheado también se reenvía. Reutilizar la clave con un body distinto responde 409 idempotency_key_reused. Consulta Idempotencia.

¿Un replay idempotente cuenta contra mi rate limit?

No. Una clave reenviada dentro de su TTL no cuenta contra tu cuota. Claves distintas con el mismo payload cuentan cada una, una a una. Consulta Idempotencia › Qué NO es la idempotencia.

¿Cuál es la longitud máxima de la Idempotency-Key?

Entre 1 y 64 caracteres. Cualquier valor único opaco sirve (se recomienda UUID v7, pero UUID v4, ULID o nanoid también valen). Consulta Idempotencia › Formato de la clave.

Límites de peticiones y errores

¿Cómo conozco mi cuota restante?

Cada respuesta (incluida 429) lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; un 429 añade Retry-After con los segundos que hay que esperar. Los límites dependen del tier de tu clave. Consulta Límites de peticiones.

¿Cómo debo reintentar una petición fallida?

4xx (excepto 429) → no reintentes, corrige la petición. 429 → respeta Retry-After. 5xx → back-off exponencial con jitter, hasta 5 intentos. Consulta Errores › Estrategia de reintentos.

¿Dónde reporto un problema con una petición concreta?

Coge el request_id del envoltorio de error (también está en el header X-Request-Id) y envíalo a soporte — nos permite correlacionar logs, métricas y trazas. Consulta Soporte.