Autenticación API
En resumen
- Envía tu API key en el header
X-API-KEYde cada solicitud. - Usa la clave del ambiente al que llamas:
zrl_test_en TesteCF,zrl_cert_en CerteCF yzrl_live_en eCF. - 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
- JavaScript
- C#
- PHP
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"] }'
async function consultarEstado(encfs) {
const response = await fetch(
"https://api.zarelafact.com/TesteCF/documentos-ecf/status/batch",
{
method: "POST",
headers: {
"X-API-KEY": process.env.ZARELA_API_KEY,
"Content-Type": "application/json",
Accept: "application/json",
},
body: JSON.stringify({ encfs }),
}
);
return await response.json();
}
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
public class ZarelaClient
{
private readonly HttpClient _client = new HttpClient();
public ZarelaClient(string apiKey)
{
_client.DefaultRequestHeaders.Add("X-API-KEY", apiKey);
}
public async Task<string> ConsultarEstado(string payloadJson)
{
var content = new StringContent(payloadJson, Encoding.UTF8, "application/json");
var response = await _client.PostAsync(
"https://api.zarelafact.com/TesteCF/documentos-ecf/status/batch",
content);
return await response.Content.ReadAsStringAsync();
}
}
<?php
function consultarEstado(array $encfs, string $apiKey) {
$ch = curl_init('https://api.zarelafact.com/TesteCF/documentos-ecf/status/batch');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-KEY: ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['encfs' => $encfs]),
]);
$result = curl_exec($ch);
curl_close($ch);
return json_decode($result, true);
}
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ódigo | Causa | Qué hacer |
|---|---|---|
401 INVALID_API_KEY | Falta 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_SCOPE | La clave no tiene el permiso que pide la ruta. | Usa una clave con ese permiso (ver Permisos). |
402 PAYMENT_REQUIRED | Producció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). |
429 | Superaste el límite de solicitudes o la cuota del plan. | Ver Límites. |
503 SERVICE_UNAVAILABLE | ZarelaFact 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
| Respuesta | Qué significa | Qué hacer |
|---|---|---|
429 RATE_LIMIT_EXCEEDED | Má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_REQUIRED | La 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_EXCEEDED | Agotaste 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
- Guarda las claves en un gestor de secretos, nunca en el código ni en un repositorio.
- Tienes una clave activa por ambiente y se muestra completa una sola vez: guárdala al crearla.
- Al rotarla, la nueva reemplaza a la anterior al instante: ten listo el despliegue antes de rotar.
- Respeta
Retry-Aftercuando recibas429 RATE_LIMIT_EXCEEDEDo503 SERVICE_UNAVAILABLE. Un402o un429 PLAN_LIMIT_EXCEEDEDno se resuelve reintentando.
Siguiente: Formato JSON de e-CF.