- Documentación
- Guía · Versión 1.0
- Claves API y webhooks
Claves API y webhooks
En esta página
Una clave API permite a una aplicación — tu sitio web, tu tienda — publicar mediante la API en nombre del espacio de trabajo; un webhook avisa a esa aplicación, con una llamada firmada, cuando una publicación cambia de estado.
Los menús Claves de API y Webhooks están reservados a los administradores y al propietario del espacio. El funcionamiento de la propia API se describe en la referencia de la API.
Crear una clave API
Menú Claves de API, y luego Crear una clave de API:
| Campo | Nota |
|---|---|
| Nombre | Obligatorio, 100 caracteres como máximo. Sirve para reconocer la aplicación que usa la clave: «Sitio web», «Tienda». |
| Marca | Opcional. Vacía, la clave cubre «Todo el espacio de trabajo». Una clave limitada a una marca no ve ni publica nada de las demás. |
| Permisos | Al menos uno. Cada permiso abre una parte de la API: consulta Permisos. |
Crear la clave abre la ventana Tu nueva clave de API, que muestra el Identificador (qsc_…) y el Secreto (qss_…), cada uno con un botón para copiarlo.
El secreto se muestra una sola vez. Cópialo antes de cerrar la ventana con He copiado el secreto: ya no se podrá volver a leer, solo sustituir por una clave nueva.
Una clave también sirve para conectar un asistente conversacional a Quiet Social, mediante el servidor MCP: leerá tus publicaciones y preparará borradores con los permisos de la clave. Créale una clave aparte, solo con los permisos necesarios y, si es posible, limitada a una marca.
Seguir y revocar una clave
La lista muestra, para cada clave, su Nombre, su Identificador, su Marca, sus Permisos, su Último uso y su Estado: Activa o Revocada. El filtro Solo las activas se aplica por defecto.
Una clave no se modifica. Para cambiar sus permisos o su marca, crea una nueva, cambia la aplicación a esa clave y luego revoca la antigua.
Revocar corta el acceso de la aplicación desde su siguiente petición. Una clave revocada no se reactiva.
La creación y la revocación de una clave quedan anotadas en el historial, como la declaración, la modificación, la reactivación y la eliminación de un webhook.
Declarar un webhook
Menú Webhooks, y luego Dar de alta un webhook:
| Campo | Nota |
|---|---|
| Dirección | Obligatoria. En https, en una dirección pública: una dirección local, privada o reservada se rechaza en cuanto se introduce. |
| Eventos | Al menos uno, tomado del catálogo. |
| Marca | Opcional. Vacía, el endpoint recibe los eventos de «Todo el espacio de trabajo». Limitado a una marca, solo recibe los de esa marca. |
Dar de alta abre la ventana Secreto de firma. Tu aplicación lo usa para verificar la firma de cada llamada. Se muestra una sola vez: cópialo antes de cerrar con He copiado el secreto.
Los webhooks declarados mediante la API aparecen en esta lista, y los declarados aquí son visibles para la API: es el mismo endpoint.
Gestionar un webhook
La lista muestra la Dirección, la Marca, los Eventos, el Estado — Activo o Suspendido —, el número de Fallos consecutivos y el Último éxito. El menú de cada fila ofrece:
- Enviar una prueba: una notificación de control,
webhook.test, sale por el mismo camino que una real. Su resultado aparece en las entregas del endpoint. Un endpoint Suspendido no recibe pruebas: reactívalo primero. Cinco pruebas por minuto y por endpoint como máximo, panel y API en conjunto. - Reactivar, para un endpoint Suspendido tras fallos repetidos o una dirección rechazada: comprueba antes que vuelve a responder. La dirección se comprueba una vez más, y una dirección todavía prohibida impide la reactivación. El contador de fallos vuelve a cero, y la suspensión volverá si nada ha cambiado.
- Editar la dirección o los eventos. La marca no se cambia.
- Eliminar: la dirección ya no recibe nada, y el historial de sus entregas se va con ella.
Las entregas
La página de un webhook repite su estado — incluida la fecha del Último fallo — y lista sus Entregas, las más recientes primero: el Evento, el Estado, el número de Intentos, la Respuesta (el código HTTP devuelto por tu aplicación) y la Fecha.
| Statut (Estado) | Significado |
|---|---|
| En espera | La entrega espera su primer intento o un reintento. |
| Entregada | Tu aplicación respondió con un código 2xx. |
| Fallida | Todos los intentos fallaron. |
| Dirección rechazada | En el momento del envío, la dirección llevaba a un destino prohibido; el endpoint queda suspendido. |
Las entregas se conservan 30 días. Los reintentos y la suspensión se detallan en la referencia de los webhooks.