Autenticación

Para desarrolladores

Para llamar a la API pública de Fidelizador necesita dos datos: una API key, que se crea en el panel, y el identificador de su instancia. Ambos van en los headers de cada llamada.

La API key funciona así:

• Se crea una vez, en el panel. No hay un endpoint que la emita ni una llamada previa para obtenerla.
• No hay token que refrescar. No existe un access_token que expire en horas ni un flujo de refresh. La API key sirve hasta su fecha de expiración, si tiene una, o hasta que se revoque.
• Va en cada llamada. Todos los requests llevan la misma API key.

Antes de empezar

• Rol Administrador en la instancia. Con el rol Usuario puede ver el listado de API keys, pero no crear una.
• Saber qué va a hacer la integración. Por ejemplo, enviar correos, leer estadísticas o consultar remitentes. De eso dependen los permisos que le dará a la API key.

Crear la API key

1. En el panel, abra Configuración → Credenciales API y pulse Crear.

   

   Credenciales API, dentro de Configuración. El botón Crear, arriba a la derecha, abre el formulario.

2. En Nombre, escriba el de la integración que va a usar la API key.

3. Elija la Fecha de expiración.

4. En Tipo de acceso, elija Acceso completo, o Permisos específicos para limitarla a lo que la integración necesita.

5. Si quiere restringir desde dónde se puede usar, complete Lista blanca de IPs. Es opcional.

   

   El formulario de creación: nombre y fecha de expiración a la izquierda, alcance de la API key a la derecha.

6. Pulse Crear. La plataforma muestra dos valores: el ID de la credencial y Su nueva credencial API. La integración usa el segundo, tal como aparece.

   

   El diálogo Credencial API creada, con el ID de la credencial y la API key completa.

Los permisos, la lista de IPs permitidas y la fecha de expiración se explican en Crear y gestionar credenciales API.

Importante

Esta es la única vez que la API key se muestra en pantalla. Cópiela antes de cerrar la ventana: la plataforma guarda solo su huella, así que una API key perdida se reemplaza, no se recupera.

Identificar su instancia

Una misma cuenta puede tener varias instancias, cada una con sus dominios, remitentes y datos. Además de la API key, cada llamada indica sobre qué instancia opera, con el header X-Instance-Slug.

Ese valor es el slug, el identificador corto de la instancia, y aparece en dos lugares del panel:

• En la dirección del navegador, justo después del dominio: …/<slug>/es/dashboard.
• En el selector Instancia, arriba a la derecha.

El selector Instancia muestra la instancia activa.

Los headers de cada llamada

Toda llamada a la API lleva estos dos headers, sin excepción:

Authorization: Bearer <API_KEY>
X-Instance-Slug: <slug>

Los ejemplos de esta documentación usan tres variables de entorno. Expórtelas en la terminal y podrá copiar y pegar los ejemplos tal cual:

export API_HOST=cl2api.fidelizador.com
export API_KEY=<API_KEY>
export SLUG=<slug>

Si la primera llamada falla

Las respuestas de autenticación no indican el motivo del rechazo, para no revelar qué instancias existen a quien llama sin API key.

Respuesta	Qué significa	Qué revisar
401unauthorized	Falta el header Authorization, la API key no es válida, venció o fue revocada, o el slug no corresponde a ninguna instancia. La respuesta es idéntica en todos los casos.	Que el request lleve los dos headers, y tanto la API key completa como el slug. Ver unauthorized.
403forbidden	La API key autenticó, pero no puede hacer esa operación: le falta el permiso, o la instancia está deshabilitada.	Los permisos de la API key, en el panel. Ver forbidden.
403ip_not_allowed	La IP desde la que llama su sistema no está permitida. Hay dos listas de IPs permitidas, la de la instancia y la de la API key, y la respuesta no indica cuál la rechazó.	La IP pública desde la que llama su sistema, contra la lista de IPs permitidas de la API key. Si la IP está permitida ahí, o la lista está vacía, la rechazó la lista de la instancia. Ver ip-not-allowed.

Si recibe un 403, la API key y el slug son correctos. Revise los permisos de la API key, la lista de IPs permitidas o si la instancia está habilitada.

Vigencia y rotación

La API key es válida hasta la fecha de expiración elegida al crearla, o indefinidamente si se eligió Sin expiración. Mientras la API key está activa, puede editar esa fecha desde el panel. Si se acerca, extiéndala: no hace falta crear otra.

El valor de la API key no se puede cambiar. Para rotarla:

1. Cree una API key nueva.
2. Reemplace la anterior en la integración.
3. Revoque la anterior.

Si revoca la anterior antes de configurar la nueva, la integración queda sin acceso hasta completar el cambio. Una API key vencida o revocada deja de aceptarse de inmediato, y las llamadas que la usan reciben 401.