CelMex Unlockers | Liberación de Celulares Rápida y Segura

Cómo obtener tu API key, cómo enviarla, cómo funciona el registro automático de IPs y qué debes proteger en producción.

Método de autenticación

CelMex API v1 usa un solo método de autenticación:

Authorization: Bearer clx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

No se soportan:

usuario y contraseña por request;
API key en query string;
autenticación desde cookies;
autenticación parcial en frontend público.

Qué es tu API key

Tu API key es la credencial privada de tu cuenta API. Debes tratarla igual que una contraseña de servidor.

Reglas principales:

Cada cuenta API puede tener 1 API key productiva y 1 API key sandbox.
Las llaves son por entorno y no son intercambiables.
Al regenerar una llave, la anterior de ese entorno deja de funcionar de inmediato.
El valor completo solo se muestra cuando se crea o regenera.
Debes guardarla en variables de entorno o secretos de servidor.

Prefijos:

producción: clx_live_...
sandbox: clx_test_...

Cómo obtenerla

Si tu cuenta ya tiene acceso API habilitado:

Entra a tu panel de CelMex.
Abre la sección API.
Genera o regenera la llave de sandbox.
Genera o regenera la llave de producción.
Guárdalas de inmediato en tu backend.

Si no ves esa sección, tu cuenta todavía no tiene acceso API habilitado.

Regla importante de entorno

No mezcles llaves ni URLs entre entornos.

Ejemplos incorrectos:

usar una clx_test_... contra https://celmexunlockers.com/api/v1
usar una clx_live_... contra un sandbox distinto al asignado
asumir que una llave generada en local servirá en el sitio desplegado

En todos esos casos, la respuesta esperada es INVALID_API_KEY.

Cómo enviarla correctamente

Tu backend debe incluir el header Authorization en cada request:

Authorization: Bearer clx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Buenas prácticas:

Envía la key solo desde tu backend.
No la expongas en frontend público ni apps cliente sin servidor.
No la pongas en URLs, query params o screenshots compartidos.
Si registras logs, ocúltala siempre parcialmente.

Ejemplo con cURL

curl -X GET "https://celmexunlockers.com/api/v1/account" \
  -H "Authorization: Bearer clx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Ejemplo con Node.js

const response = await fetch("https://celmexunlockers.com/api/v1/account", {
  headers: {
    Authorization: "Bearer " + process.env.CELMEX_API_KEY,
  },
});

const result = await response.json();
console.log(result);

Registro automático de IPs

La API registra automáticamente las IPs válidas desde las que usas tu key:

Máximo 5 IPs distintas por cuenta.
Las primeras IPs válidas quedan autorizadas automáticamente.
Si aparece una sexta IP distinta, la request es bloqueada.
Puedes eliminar IPs desde tu panel para liberar espacio.

Esto está pensado para que tu integración sea práctica y no tengas que precargar IPs manualmente antes de hacer la primera llamada.

Qué hacer si tu IP cambia mucho

Si tu infraestructura rota IPs con frecuencia, puedes consumir rápido tus 5 espacios.

Recomendación:

Usa servidores con salida por IP fija o muy estable.
Si cambias de proveedor o red, revisa tus IPs registradas en el panel.
Si haces despliegues temporales o pruebas desde distintas máquinas, elimina IPs viejas cuando ya no las uses.

Rate limiting

Cada cuenta API tiene límites operativos configurables por CelMex, por ejemplo:

requests por minuto;
creación de pedidos por minuto;
lecturas del listado paginado de servicios;
límite mensual opcional.

Si un límite se excede, la API responde 429 RATE_LIMITED.

En particular:

GET /api/v1/services debe usarse para sincronización paginada en background;
no debe usarse como fuente en vivo para cada pantalla o cada usuario;
si necesitas una copia completa del catálogo, recórrelo por páginas y hazlo como máximo una vez cada 24 horas.

Qué debes guardar para soporte

Cada respuesta de CelMex incluye un requestId.

Guárdalo junto con:

tu referencia interna;
el endpoint llamado;
fecha y hora aproximada;
el payload enviado;
el código de respuesta HTTP.

Si alguna vez reportas un problema, ese requestId acelera mucho la revisión.

Checklist de seguridad mínima

Antes de pasar a producción, te recomendamos validar esto:

La API key vive en variables de entorno.
Tienes separadas la llave sandbox y la llave producción.
Tu backend envía la key, no el frontend.
Tienes logs con requestId.
Estás usando HTTPS.
Usas Idempotency-Key al crear pedidos.
Tu salida de red usa IP estable o controlada.
Corriste el suite completo de sandbox con exit code 0.

Autenticación