Una clave de API es la credencial que otro sistema usa para registrar contactos y enviar correo en tu cuenta sin pasar por la pantalla. Así la tienda en línea de Casa Moura Cafés envía el correo transaccional pedido-confirmado en cada compra, o registra al cliente nuevo en la lista Clientes de la tienda.
Las claves están en Configuración › Integraciones, en la tarjeta Claves de API, y solo el Propietario las crea y revoca. El motivo: una clave alcanza la base de contactos sin pantalla, sin inicio de sesión y sin vencimiento. Si la pestaña no aparece para ti, habla con soporte.
Crear una clave
Haz clic en Nueva clave y completa:
- Nombre: el sistema que la usará, como Tienda en línea. Así sabrás cuál revocar.
- Qué puede hacer esta clave: los permisos. Marca solo los que el sistema usa. Un permiso no incluye a otro: Registrar y corregir contactos no da derecho a Leer contactos.
- Dónde puede actuar: aparece cuando la cuenta tiene espacios de envío. Mira abajo.
- Tipo de mensaje predeterminado: Transaccional o Marketing, usado cuando el envío no indica el tipo. Define qué consentimiento se exige y dónde aparece el envío en los informes: marketing respeta la baja, transaccional no. Ambos consumen la misma cuota. La tienda de Casa Moura usa Transaccional, porque la confirmación del pedido tiene que llegar incluso a quien salió de la lista de novedades.
La clave aparece una sola vez
Al crearla, la ventana Clave creada muestra el valor completo. Cópialo y guárdalo ahora: no vuelve a aparecer, ni siquiera para soporte. La ventana no se cierra al hacer clic afuera, a propósito: la salida es Finalizar. El sistema envía la clave en la cabecera Authorization: Bearer de cada llamada.
¿Perdiste la clave? No hay forma de recuperarla: crea otra y revoca la perdida.
Dónde puede actuar la clave
Con espacios de envío en la cuenta, el campo Dónde puede actuar define el alcance:
- Ninguno marcado: la clave actúa solo en la cuenta principal y no alcanza ningún espacio.
- Espacios marcados: actúa solo en ellos, sin la cuenta principal. Si necesitas ambos, usa dos claves.
- Todos los espacios actuales: atajo que marca los espacios que existen hoy. Un espacio creado después no entra por sí solo: hay que editar la clave y marcarlo.
Para que la llamada ocurra en un espacio, el sistema envía su identificador en la cabecera X-WiseData-Space; el valor aparece en Configuración › Espacios de envío.
Clave de homologación
Marca Clave de homologación para el entorno de pruebas del sistema. Con ella, el envío se acepta por completo, pero ningún correo sale y no se consume cuota: el mensaje va a la Bandeja de prueba, donde lees el contenido y simulas lo que pasaría.
Solo puede tener los permisos de envío y de lectura de campos y listas. No toca contactos: serían los contactos reales de la cuenta, y una prueba alteraría la base de verdad. En la lista, la clave aparece con la etiqueta Homologación; revisa la etiqueta antes de copiar una clave a la configuración del sistema, porque cambiar una por otra hace que producción deje de enviar sin ningún error visible.
Clave de plataforma
Aparece para cuentas con espacios de envío. Es para un sistema que atiende a varios clientes, cada uno en su espacio: crea espacios por la API y los alcanza todos, incluso los creados después. Es la única clave con los permisos de espacios y no puede ser de homologación.
Es la credencial de mayor alcance de la cuenta: si se filtra, alcanza la base de todos los espacios. Úsala solo si tu sistema realmente crea y opera espacios.
La lista de claves
Cada clave muestra sus cuatro últimos caracteres, su estado (Activa o Revocada), sus etiquetas, permisos, dónde actúa, el último uso y quién la creó. El último uso es lo que dice si una clave sigue en uso: una clave que nunca se usó probablemente quedó olvidada.
Editar
Editar cambia nombre, permisos, alcance y tipo sin cambiar el valor de la clave: el sistema sigue funcionando, y lo que cambió vale desde la siguiente llamada. Activar o desactivar la homologación en la edición cambia el comportamiento al instante; la pantalla avisa antes de guardar.
Revocar y reemplazar
Revocar hace que el sistema que usa la clave se detenga de inmediato. La clave sigue en la lista, marcada como revocada, para registrar cuándo ocurrió.
No existe cambiar el valor de una clave. Para reemplazarla sin detener el sistema: crea la nueva, instálala en el sistema, revisa su último uso y solo entonces revoca la antigua. Si la clave se filtró, el orden se invierte: revoca primero.
Buenas prácticas
- Una clave por sistema, con solo los permisos de ese sistema. Revocar una no tumba las demás.
- La clave es de servidor. Nunca en una página, aplicación, navegador o repositorio público.
Adónde ir después
- Webhooks: el camino de vuelta, WiseData Mail avisando a tu sistema qué pasó con cada correo.
- Bandeja de prueba: donde llegan los envíos de la clave de homologación.
- Métricas de la API: lo que envió la integración.
- Espacios de envío: el identificador de cada espacio para la API.
En resumen: crea una clave por sistema con solo los permisos necesarios, copia el valor en el momento porque no vuelve a aparecer, marca los espacios cuando la clave necesite actuar en ellos, usa la clave de homologación para las pruebas y, para reemplazarla, crea la nueva antes de revocar la antigua.