Crear y gestionar credenciales API

Fidelizador: tus credenciales API, todas en un panel

Para todos los usuarios

Una credencial API permite que una aplicación externa (su sistema, un script, una integración de terceros) autentique llamadas programáticas a la API pública de Fidelizador, sin usar una sesión de usuario. Es el mecanismo recomendado para enviar correos o consultar datos desde código propio.

Antes de empezar

• Necesita tener un usuario del equipo asignado en esta instancia. Con el rol Usuario puede ver el listado de credenciales; crear, editar o revocar una credencial requiere el rol Administrador — con el rol Usuario esos controles no aparecen.
• Decida de antemano qué necesita hacer la credencial (enviar correos, leer estadísticas, administrar remitentes, etc.) para elegir bien sus permisos.

Crear una credencial API

Fidelizador: crea y gestiona tus credenciales API

1. Acceda al panel y abra Configuración → Credenciales API.
2. Pulse Crear.
3. Complete los campos:
   • Nombre: una etiqueta para identificar la credencial (por ejemplo API producción, Integración e-commerce).
   • Tipo de acceso: Acceso completo o Permisos específicos (ver Permisos por credencial).
   • Permisos: solo si eligió "Permisos específicos".
   • Fecha de expiración: ver Fecha de expiración.
   • Lista de IPs permitidas (opcional): ver Lista de IPs permitidas.
4. Confirme.

Guardar la credencial

Al crear la credencial, la plataforma muestra dos valores una única vez:

• El ID de la credencial.
• La credencial API completa (el secreto).

Cópielos y guárdelos de inmediato en un lugar seguro. Una vez que cierre esta ventana, no es posible volver a visualizar el valor completo de la credencial — si lo pierde, debe crear una credencial nueva. La credencial se usa como token Bearer en las llamadas a la API; el formato exacto y cómo enviarla junto con el identificador de su instancia están en la documentación de la API pública.

Permisos por credencial

Cada credencial tiene uno de dos tipos de acceso:

Tipo	Efecto
Acceso completo	Permite el uso de todos los endpoints de integración sin restricciones. Disponible en todos los planes.
Permisos específicos	Restringe la credencial solo a los permisos que seleccione (ver tabla). Requiere que su plan incluya permisos por API key — si el plan no lo incluye, esta opción aparece bloqueada con la indicación de que debe actualizar su plan.

Permisos disponibles cuando el tipo de acceso es "Permisos específicos":

Grupo	Permiso	Habilita
Correo	Enviar correos	Envío de correos vía API
Correo	Ver actividad de correos	Consultar actividad, desuscripciones, quejas y restricciones
Remitentes	Ver remitentes	Listar y buscar remitentes
Dominios	Ver dominios	Listar dominios y su estado de verificación
Dominios	Administrar dominios	Ejecutar la verificación DNS de un dominio (requiere también "Ver dominios")
Estadísticas	Ver estadísticas	Consultar reportes agregados
Plantillas	Ver plantillas	Listar plantillas de correo
Plantillas	Administrar plantillas	Sin efecto hoy: crear, editar, publicar y eliminar plantillas son acciones exclusivas del panel
Campos	Ver campos	Listar el catálogo de campos
Campos	Crear campos	Crear un campo del catálogo, con sus opciones
Formularios	Ver formularios	Listar formularios y ver su detalle
Consentimiento	Ver consentimientos	Listar términos y finalidades, consultar el historial y resolver el consentimiento vigente de un contacto
Consentimiento	Registrar consentimientos	Registrar un consentimiento capturado fuera de Fidelizador (requiere también "Ver consentimientos")
Webhooks	Ver webhooks	Listar webhooks y ver su detalle
Webhooks	Administrar webhooks	Crear, editar, eliminar y probar webhooks, y rotar su secreto

Una credencial con "Permisos específicos" requiere al menos un permiso seleccionado.

Cuántas credenciales conviene crear

Una credencial por cada sistema o ambiente que se integre, en lugar de una compartida entre todos. La razón es que el valor secreto de una credencial no se puede cambiar: para dar de baja el acceso hay que revocarla, y eso corta las llamadas de todo lo que la estuviera usando. Con credenciales separadas:

• Puede dar de baja un proyecto, o cortarle el acceso a un proveedor externo, sin interrumpir el resto de sus integraciones.
• Puede darle a cada una solo los permisos que ese sistema necesita, en lugar de un conjunto que sea la suma de todos.
• Puede restringir por IP cada una según desde dónde llama ese sistema, y fijar vencimientos distintos.
• El log de auditoría distingue qué credencial hizo cada cambio.

Recomendación

Separe al menos sus ambientes de prueba y de producción. Es el caso donde una credencial compartida molesta primero: al revocarla por una prueba, deja de funcionar producción.

Lista de IPs permitidas

Campo opcional: una IP o rango de direcciones IP (CIDR) por línea (por ejemplo 192.168.1.0/24, 203.0.113.42). Si se deja vacío, la credencial acepta llamadas desde cualquier IP. Si se completa, solo las IPs indicadas pueden usarla — cualquier otra origen es rechazado aunque la credencial sea válida.

Una llamada rechazada por la lista de IPs recibe un 403 cuyo code es ip_not_allowed, distinto del forbidden genérico que devuelve una credencial sin los permisos necesarios. Es lo que permite distinguir "su red no está autorizada" de "su credencial no tiene ese permiso" sin abrir un ticket. Detalle en Errores genéricos.

La respuesta no indica qué direcciones están configuradas ni con cuál llegó la petición. Al diagnosticar, verifique con qué dirección de salida llega realmente su sistema: una IP dinámica de su proveedor, o el NAT de su nube, suele no ser la que registró.

Recomendación

Deje la lista vacía mientras prueba la integración y complétela recién cuando las llamadas funcionen. Así, si algo falla, ya sabe que el problema no es la lista.

Fecha de expiración

Al crear o editar una credencial, elija entre:

• 3 meses o 1 año desde hoy.
• Sin expiración — la plataforma pide confirmación adicional antes de crear una credencial sin fecha de vencimiento, dado el mayor riesgo si la credencial se filtra.
• Personalizada — cualquier fecha futura.

La credencial es válida hasta el final del día seleccionado (23:59:59) en su zona horaria.

Editar una credencial

Fidelizador: edita una credencial API

Desde la pantalla de credenciales, una credencial activa puede editarse: nombre, tipo de acceso, permisos, lista de IPs permitidas y fecha de expiración. El valor secreto de la credencial no es editable — para cambiarlo, revoque la credencial y cree una nueva.

Revocar una credencial

Fidelizador: revoca una credencial API

Desde la pantalla de credenciales puede revocar una credencial activa. Efecto:

• La credencial deja de aceptarse de inmediato en cualquier llamada a la API.
• Permanece visible en el listado con estado Revocada, junto con su fecha de revocación.

Una vez revocada, la credencial ya no puede editarse ni reactivarse desde el panel. Si necesita volver a operar, debe crear una credencial nueva.

Dudas frecuentes

¿Cuántas credenciales API puedo crear?

No hay un límite fijo en el número de credenciales.

¿Puedo recuperar el valor de una credencial que ya cerré sin copiar?

No. La plataforma no almacena el valor en texto plano; debe revocarla y crear una nueva.

¿Qué pasa si la fecha de expiración se cumple?

La credencial deja de aceptarse en la API automáticamente, sin necesidad de revocarla manualmente.

¿"Permisos específicos" no está disponible para mí?

Esta opción depende de su plan. Si aparece bloqueada, debe actualizar su plan para usarla; mientras tanto, solo puede crear credenciales de "Acceso completo".

¿Cómo uso la credencial en mis llamadas a la API?

Ver la documentación de la API pública.

Más preguntas en Preguntas frecuentes.