Saltar al contenido principal

Autenticación API

En resumen
  1. Envía tu API key en el header X-API-KEY de cada solicitud.
  2. Usa la clave del ambiente al que llamas: zrl_test_ en TesteCF, zrl_cert_ en CerteCF y zrl_live_ en eCF.
  3. No hay login ni token que renovar: la clave funciona hasta que la revoques.

Así una caja o un POS nunca se queda sin poder facturar porque venció un token.

Encabezados​

X-API-KEY: {tu_api_key}
Content-Type: application/json
Accept: application/json

Ejemplos​

La misma solicitud autenticada (una consulta por lote) en varios lenguajes:

curl -X POST \
https://api.zarelafact.com/TesteCF/documentos-ecf/status/batch \
-H 'X-API-KEY: zrl_test_...' \
-H 'Content-Type: application/json' \
-d '{ "encfs": ["E310000000010"] }'

Errores de autenticación​

Los errores de la solicitud tienen siempre esta forma:

{
"ok": false,
"correlationId": "ae5acff4-583c-4e30-b305-11befe8c922e",
"error": {
"code": "INVALID_API_KEY",
"message": "API key no pertenece al ambiente solicitado"
}
}
CódigoCausaQué hacer
401 INVALID_API_KEYFalta la clave, está mal escrita, fue revocada, venció o es de otro ambiente.Revisa el header X-API-KEY y usa la clave activa del ambiente correcto.
403 INSUFFICIENT_SCOPELa clave no tiene el permiso que pide la ruta.Usa una clave con ese permiso (ver Permisos).
402 PAYMENT_REQUIREDProducción (eCF) sin plan pagado: Partner sin plan, pago vencido o los 50 e-CF gratis del mes ya usados.Paga el plan en el enlace details.billingUrl (ver Planes y pagos).
429Superaste el límite de solicitudes o la cuota del plan.Ver Límites.
503 SERVICE_UNAVAILABLEZarelaFact no puede atender en este momento (un problema temporal nuestro). Tu clave no tiene nada que ver: una caída nuestra nunca responde 401.Espera los segundos de Retry-After y reintenta la misma solicitud. No cambies ni revoques la clave.

Guarda el correlationId de cada error: con él, soporte encuentra tu solicitud sin pedirte datos fiscales.

Límites​

RespuestaQué significaQué hacer
429 RATE_LIMIT_EXCEEDEDMás de 1,000 solicitudes en un minuto con la misma clave. Las solicitudes sin clave o con una clave inválida cuentan contra tu IP, con el mismo límite; si tu IP lo agota, recibe 429 durante ese minuto aunque luego envíe una clave válida.Espera los segundos de Retry-After y reintenta con espera creciente. Corrige la clave antes de reintentar un 401.
402 PAYMENT_REQUIREDLa producción necesita un plan pagado (o se acabaron los 50 e-CF gratis del mes). TesteCF y CerteCF nunca lo responden.Reintentar no sirve: paga el plan en details.billingUrl.
429 PLAN_LIMIT_EXCEEDEDAgotaste el cupo de tu plan pagado más su margen de tolerancia en el periodo de cobro (e-CF aceptados más los que van en camino).Reintentar no sirve: sube de plan (ver el margen de tolerancia).

Buenas prácticas​

  1. Guarda las claves en un gestor de secretos, nunca en el código ni en un repositorio.
  2. Tienes una clave activa por ambiente y se muestra completa una sola vez: guárdala al crearla.
  3. Al rotarla, la nueva reemplaza a la anterior al instante: ten listo el despliegue antes de rotar.
  4. Respeta Retry-After cuando recibas 429 RATE_LIMIT_EXCEEDED o 503 SERVICE_UNAVAILABLE. Un 402 o un 429 PLAN_LIMIT_EXCEEDED no se resuelve reintentando.

Siguiente: Formato JSON de e-CF.