3. Crea tu API key

La API key identifica a tu sistema. Tienes una key activa por ambiente: hasta tres, una para cada uno.

Ambiente	Para qué	¿Cuándo la creas?	Empieza por
TesteCF	Desarrollo y pruebas. Sin validez fiscal.	Ahora, para empezar a integrar.	zrl_test_
CerteCF	Pruebas de certificación con la DGII.	Al empezar la certificación.	zrl_cert_
eCF	Producción: comprobantes reales.	Cuando quieras: emite cuando ZarelaFact active tu producción, después de la aprobación de la DGII. Antes responde 423 PRODUCTION_NOT_ACTIVE.	zrl_live_

1. En el portal, entra a Desarrolladores → API keys y pulsa Crear key en el ambiente (empieza por Pruebas, TesteCF).
2. Escribe una descripción que identifique al sistema, por ejemplo Integración ERP.
3. Copia la key: se muestra completa una sola vez, al crearla. Guárdala en tu backend; después el portal solo la muestra resumida.

Envía la clave en el header X-API-KEY de cada solicitud. No hay login ni token:

X-API-KEY: zrl_test_...

Trátala como una contraseña

Guárdala en variables de entorno o en un gestor de secretos, nunca en el código, en el navegador ni en la app del POS. No la escribas completa en tus logs.

Permisos

Las claves que creas en el portal pueden validar, emitir y consultar:

Permiso	Qué permite
ecf:validate	Validar documentos sin emitirlos (?validate=true).
ecf:create	Emitir e-CF.
status:read	Consultar estados por lote y los documentos en contingencia.
ecf:read	Descargar el XML firmado y el PDF de cada documento (ver Representación impresa).

Las anulaciones, la respuesta a la aprobación comercial y la certificación también se hacen desde el portal. Para hacerlas por API, la clave necesita además el permiso tenant:admin: al crearla, marca Permiso de administración. Esa casilla solo la ven el propietario y los administradores de la cuenta; dale ese permiso solo a sistemas de confianza. Leer la lista de documentos recibidos no lo necesita: basta ecf:read, que trae la clave estándar.

Límites

• Hasta 1,000 solicitudes por minuto por clave, igual en todos los planes. Si te pasas, la API responde 429 RATE_LIMIT_EXCEEDED con el header Retry-After. Las solicitudes con una clave inválida no tienen cupo propio: cuentan contra tu IP.
• Crear claves es gratis en los tres ambientes, también la de producción. La cantidad de e-CF al mes en producción depende de tu plan (una cuenta directa tiene 50 gratis): ver Planes y pagos.

Buenas prácticas

• Si la pierdes o se expone, rótala: la nueva reemplaza a la anterior al instante, así que instálala enseguida en tu backend.
• Revocar la deja sin efecto y te permite crear otra en ese ambiente.
• Cada ambiente solo acepta sus claves: una de CerteCF en eCF responde 401.

Ya tienes todo lo necesario. Siguiente: 4. Integra tu software.