Entornos y claves
Preproducción es el entorno de pruebas de la AEAT; producción es el real. La API sirve los dos desde la misma URL, y es la clave la que decide a cuál llegas.
Dos entornos, una URL
La AEAT mantiene dos registros independientes: uno de preproducción, para que los sistemas se prueben sin efectos, y el de producción. Cada obligado que das de alta en la consola pertenece a uno de los dos, y esa elección es fija: un obligado de preproducción remite al entorno de pruebas y su QR apunta al cotejador de pruebas; uno de producción, al real.
Como son registros distintos, el mismo NIF puede estar dado de alta en los dos entornos, cada uno con su propia cadena de huellas, su certificado y sus series. Así se ensaya con el NIF real —el certificado electrónico es el mismo— sin que nada de lo que se prueba se mezcle con la facturación de verdad.
| Preproducción | Producción | |
|---|---|---|
| Entorno del obligado | preprod | prod |
| Clave que lo alcanza | vf_test_… | vf_live_… |
| A dónde se remite | Entorno de pruebas de la AEAT | AEAT (registros reales) |
| Cotejo del QR | prewww2.agenciatributaria.gob.es | www2.agenciatributaria.gob.es |
| Coste | Gratuito | Bajo contrato |
| Requisito | Cuenta y certificado | Declaración responsable del SIF en vigor y contrato |
Claves y su entorno
Toda llamada a /v1 se autentica con Authorization: Bearer <clave>. El prefijo de la clave dice de qué entorno es, y la API lo aplica en cada resolución por NIF: con una clave vf_test_…, un obligado_nif sólo puede referirse a un obligado de preproducción; con una vf_live_…, sólo a uno de producción.
Si el NIF no existe en el entorno de la clave, la API responde 404 con un detalle que lo dice: «No existe un obligado con NIF … en prod para esta clave (vf_live_)». Es el error que verás si pruebas con la clave equivocada.
La clave se muestra una sola vez, al crearla. Después la consola y la API sólo conservan su prefijo y un hash. Si la pierdes, revócala y crea otra.
Perfiles y ámbito
Además del entorno, una clave tiene un perfil (qué puede hacer) y, opcionalmente, un ámbito (sobre qué obligados).
| Perfil | Puede | Para |
|---|---|---|
integracion | Emitir facturas y anulaciones, reencolar y subsanar, leer registros y obligados, leer webhooks. | El software que factura. Es la que va en tu ERP o CRM. |
lectura | Sólo consultar: registros, obligados, webhooks, claves. | Cuadros de mando, conciliación, auditoría. |
administracion | Todo: además, dar de alta obligados, cargar certificados, crear claves y webhooks. | La consola la usa por ti. No la metas en el código de nadie. |
El ámbito restringe la clave a un subconjunto de obligados de la cuenta. Es útil cuando un mismo tenant gestiona varios NIF y quiere que cada sistema sólo vea el suyo. Una clave acotada no puede dar de alta obligados: quedarían fuera de su propio ámbito.
Las claves se crean en la consola (Claves API → Nueva) o por API con POST https://verifactu-api.zctechpartners.cloud/v1/apikeys usando una clave administrativa. Cada llamada autenticada cuenta para el límite de 120 peticiones por minuto y clave; al superarlo la API responde 429 con Retry-After.
Paso a producción
- Da de alta el obligado en Producción desde la consola (mismo NIF, mismo certificado si es el de la empresa).
- Crea una clave de integración de Producción (
vf_live_…). - Sustituye la clave en la configuración de tu software. La URL no cambia.
- Revisa que tus webhooks apunten a tu entorno real: las suscripciones son de la cuenta, no del entorno, así que la misma URL recibirá eventos de producción.
- Emite la primera factura real y cotéjala en la Sede con el QR impreso.
vf_live_ pueden crearse, pero es responsabilidad tuya no emitir facturas reales con ellas antes de tiempo.