Documentación Simple*Factu

Documentación de la API Simple*Factu para integraciones con Veri*Factu (AEAT).

Simple*Factu es el intermediario entre tu sistema de facturación y Hacienda (AEAT). Tú envías un JSON con los datos de la factura; nosotros construimos el XML, lo firmamos con tu certificado y lo enviamos a AEAT por SOAP.

Cómo funciona en 30 segundos

Tu sistema   →   POST /v1/send-invoice (JSON + x-idempotency-key)
                      │
              Simple*Factu valida y encola
                      │
              ← 202 PENDING (jobId)
                      │
Tu sistema   →   GET /v1/jobs/:jobId  (consulta periódica)
                      │
              Proceso en segundo plano → XML SOAP mTLS → AEAT
                      │
              ← SUCCEEDED + CSV + URL de verificación + QR

Cuando el trabajo llega a SUCCEEDED tienes el CSV (código de verificación de AEAT) y el QR que debes imprimir en la factura. Todo lo demás — huellas, encadenamiento, sistema informático (SIF), firma SOAP, reintentos — lo gestionamos nosotros.

¿Actualizaste la integración? Ver Registro de cambios.

Lista de comprobación para producción (ERP)

  1. Credenciales de QA (API key + permisos / scopes) — Autenticación / Entornos
  2. Certificado FNMT (.pfx) subido con POST /me/certificate
  3. Primera factura en QA → trabajo SUCCEEDED — Inicio rápido
  4. Manejo de errores 4xx/AEAT y trabajos DEAD — Errores
  5. Consulta periódica estable o webhooks + reconciliación con registros
  6. Paso a producción (nueva API key + mismo flujo) — Entornos

Por dónde empezar

  1. Conceptos clave — qué es una huella, el encadenamiento, el CSV y el primer registro.
  2. Entornos — QA vs producción, base URL /v1.
  3. Inicio rápido — primera factura con curl contra la API alojada (sin instalar nada).
  4. Envío de facturas — diccionario de campos de POST /send-invoice.
  5. Anulación de facturas — diccionario de POST /cancel-invoice.
  6. Autenticación — API key, certificado e idempotencia.
  7. Verificar NIF y consultar AEAT — antes y después del envío.
  8. Registros AEAT — historial inmutable (solo altas).
  9. Webhooks — notificaciones invoice.succeeded / invoice.failed.
  10. Plan y uso — límites y HTTP 402.
  11. Gestoría — panel y API para asesorías con varios autónomos.
  12. Referencia API — OpenAPI interactiva (Scalar).
  13. Registro de cambios — qué cambió respecto a integraciones antiguas.

Contrato técnico ampliado (BFF, administración, gestoría): INTEGRATION.md en GitHub.

¿Cómo accedo?

Perfil Cómo usar Simple*Factu
Autónomo o pyme que usa la app web Registro en simplefactu.com — certificado y envío desde Ajustes Veri*Factu; archivo en Facturas → Registros AEAT
Gestoría / asesoría Panel Gestoría (ruta /partner) o API de gestoría — una cuenta hija por autónomo
ERP o integrador (servidor a servidor) API key emitida por soporte; POST /v1/send-invoice desde tu servidor — Autenticación

Los conceptos (huella, encadenamiento, CSV) son los mismos en todos los casos — solo cambia quién llama a la API.

Soporte

Cada respuesta de la API incluye un requestId. Si algo falla, escríbenos a soporte@simplefactu.com con ese UUID y podremos ver la traza completa del envío.