Ir al contenido
Quiet Social

Claves API y webhooks

Esta documentación está traducida del francés. Si ambas versiones difieren, prevalece la versión francesa.

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.