Claves de API
Una clave de API permite que un sitio web, una aplicación o su servidor trabajen con el proyecto sin iniciar sesión en la interfaz: enviar eventos, leer perfiles y gestionar segmentos, recorridos y campañas. Las claves se crean y se revocan en «Configuración» → «Claves de API».
La sección es visible para «Propietario», «Administrador» y «Gestor». Solo «Propietario» y «Administrador» pueden crear y revocar claves.
Tipos de clave
| Escritura | Secreta | |
|---|---|---|
| Empieza por | cdp_wk_ |
cdp_sk_ |
| Qué permite | solo enviar eventos | enviar eventos y realizar acciones en el proyecto según los permisos elegidos |
| Dónde usarla | código del sitio web, aplicación móvil, servidor | solo en su servidor |
| Se puede mostrar a terceros | sí, es visible en el código de las páginas del sitio | no, manténgala en secreto |
| Límite de solicitudes | 6000 por minuto | 1200 por minuto (por defecto) |
La clave de escritura es pública por naturaleza: está en el código de cada página del sitio. Con ella solo se pueden enviar eventos, por lo que una filtración no da acceso a los datos. Para que un sitio ajeno no pueda enviar eventos en su nombre, en la sección «Sitio web» puede indicar los dominios desde los que se acepta la clave; consulte Conexión del sitio web.
La clave secreta da acceso desde el servidor a los datos del proyecto. Nunca la incluya en el código de las páginas, en aplicaciones móviles ni en repositorios públicos.
Cómo crear una clave
- Abra «Claves de API».
- En la tarjeta «Nueva clave», introduzca un «Nombre» que le permita saber después dónde se usa la clave, por ejemplo «Sitio web» o «Servidor de la tienda en línea».
- Elija el «Tipo»: Escritura o Secreta.
- Para una clave secreta, marque los «Permisos de la clave»: solo los que la integración necesite realmente.
- Pulse «Crear clave».
Justo después de crearla, la clave completa aparecerá en la parte superior de la página. Pulse «Copiar» y guárdela, por ejemplo en un gestor de contraseñas o en las variables de entorno del servidor. La clave secreta se muestra una sola vez: solo guardamos su huella y no es posible recuperarla. Si la pierde, cree una nueva y revoque la anterior.
La clave de escritura para el sitio web es más cómodo crearla directamente en la sección «Sitio web»: allí se inserta automáticamente en el código de instalación y está disponible en cualquier momento; consulte Conexión del sitio web.
La tabla de claves muestra el nombre, quién la creó y cuándo, el tipo, el comienzo de la clave (por ejemplo, cdp_sk_a1b2…), el número de permisos y la hora del último uso.
Permisos de la clave secreta
Solo puede otorgar a la clave los permisos que usted mismo tiene. Los permisos se aplican a todo el proyecto: no es posible limitar una clave a recorridos o segmentos concretos.
| Permiso | Qué permite |
|---|---|
| Leer perfiles | el perfil por identificador y sus eventos |
| Datos personales sin enmascarar | correo electrónico, teléfono y otros datos personales sin ocultar; sin este permiso se enmascaran |
| Modificar perfiles y consentimientos | consentimientos de envío, vinculación de Telegram |
| Eliminar perfiles (GDPR) | eliminación del perfil a petición del cliente |
| Catálogo de eventos y atributos | lista de eventos y propiedades de los perfiles |
| Leer segmentos / Modificar segmentos | ver, crear, modificar, eliminar y recalcular segmentos |
| Leer recorridos e informes; Editar borradores e inscribir participantes; Publicar, pausar y archivar recorridos | trabajo con recorridos |
| Lectura de campañas e informes; Creación y edición de campañas; Inicio, pausa y cancelación de campañas | trabajo con campañas |
| Lectura del catálogo de productos y recomendaciones; Carga y eliminación de productos | productos y recomendaciones |
| Analítica | informes |
Ejemplo: a una clave para sincronizar clientes VIP desde el CRM le bastan los permisos «Leer segmentos» y «Modificar segmentos».
Todas las acciones realizadas con una clave secreta se registran en el registro de auditoría del proyecto en nombre de la clave; consulte Configuración del proyecto, plan y auditoría.
Cómo revocar una clave
- Busque la clave en la tabla y pulse «Revocar».
- Confirme la acción.
Las solicitudes con esa clave dejarán de funcionar de inmediato (respuesta 401). La clave revocada permanece en la lista con la marca «Revocada» para que se vea su historial. No se puede restaurar; si la necesita, cree una nueva.
Revoque la clave de inmediato si pudo llegar a manos de terceros, si un empleado con acceso a ella dejó la empresa o si la integración ya no se usa.
Qué debe saber
- Límites. Si se supera el límite de solicitudes o la cuota mensual de eventos del plan, la API responde
429. Distribuya los envíos de forma uniforme y repita la solicitud tras una pausa. - Sustitución segura de una clave. Cree una clave nueva, actualícela en el servidor, compruebe que las solicitudes llegan (campo «Último uso») y solo entonces revoque la anterior.
- Una clave para cada integración. Así el registro de auditoría muestra quién hizo qué y, ante una filtración, basta con revocar una sola clave.
- Para enviar eventos y llamar a la API desde el servidor, consulte el artículo Integración desde el servidor.