Crear y gestionar credenciales API
Para administradores e integradores
Una credencial API (API key) permite que una aplicación externa (su sistema, un script, una integración de terceros) autentique sus llamadas 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, consultar remitentes, etc.) para elegir bien sus permisos.
Crear una credencial API
- Acceda al panel y abra Configuración → Credenciales API.
- Pulse Crear.
- 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.
- Nombre: una etiqueta para identificar la credencial (por ejemplo
- 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 (la API key).
Cópielos y guárdelos de inmediato en un lugar seguro. Una vez que cierre esta ventana, no es posible volver a ver el valor completo de la credencial: si no lo guardó, tendrá que 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 usar todos los endpoints de integración sin restricciones de permisos por API key. Las restricciones de red y la fecha de expiración de la credencial siguen aplicando. 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 de estadísticas |
| Plantillas | Ver plantillas | Listar plantillas de correo |
| Plantillas | Administrar plantillas | No habilita ninguna acción: 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, ver su detalle y exportar sus envíos confirmados |
| Formularios | Registrar envíos de formulario | Registrar el envío de un formulario que su sistema presentó al contacto (requiere también "Ver formularios", porque el envío debe reflejar el formulario tal como está hoy) |
| Listas | Ver listas | Listar listas, ver su detalle, sus columnas, sus importaciones y la vista previa del último archivo |
| Listas | Administrar listas | Crear, editar y eliminar listas, declarar sus columnas e importar un archivo CSV |
| 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 interrumpe las llamadas de todo lo que la estuviera usando. Con credenciales separadas:
- Puede dar de baja un proyecto, o quitarle 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 actividad distingue qué credencial hizo cada cambio.
Separe al menos sus ambientes de prueba y de producción. Es donde una credencial compartida causa problemas antes: 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, con las direcciones públicas desde las que salen las llamadas de su sistema (por ejemplo 198.51.100.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 otro 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ó.
Para aislar problemas durante una prueba inicial, puede dejar temporalmente la lista vacía. Antes de usar la credencial en producción, restrínjala a las IPs de salida conocidas de su sistema cuando sea posible.
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
Desde la pantalla de credenciales, una credencial activa puede editarse: nombre, tipo de acceso, permisos, lista de IPs permitidas y fecha de expiración. Use la acción de editar de su fila, ajuste los datos en Editar credencial API y pulse Guardar. El valor secreto de la credencial no es editable. Para cambiarlo, cree una credencial nueva y después revoque la anterior.
Revocar una credencial
Desde la pantalla de credenciales puede revocar una credencial activa:
- En el listado, ubique la credencial y use la acción de revocar de su fila.
- Revise en el aviso Revocar credencial API que el nombre corresponde a la credencial que quiere revocar.
- Pulse Revocar.
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.