Feedback API

Almirant expone una API REST publica (no MCP) para la ingesta de feedback desde widgets embebidos en sitios web o desde integraciones servidor-a-servidor. Esta API es independiente del servidor MCP y no requiere una API Key de Almirant.

Autenticacion

La Feedback API utiliza un sistema de autenticacion basado en Public Keys y widget tokens:

• Public Key (pk_...): Identifica la fuente de feedback. Se obtiene al crear una fuente de feedback en Almirant y es segura para exponer en el frontend.
• Widget Token: Token temporal firmado que se obtiene mediante el endpoint bootstrap. Tiene una duracion limitada y se usa para validar las peticiones de ingesta.

Endpoints

GET /feedback/widget/bootstrap

Inicializa el widget de feedback. Devuelve la configuracion de la fuente y un token temporal firmado necesario para enviar feedback.

Query Parameters:

Nombre	Tipo	Requerido	Descripcion
publicKey	string	Si	Public Key de la fuente de feedback (pk_...)

Ejemplo de peticion:

curl "https://api.almirant.ai/feedback/widget/bootstrap?publicKey=pk_abc123def456"

Respuesta exitosa (200):

{
  "success": true,
  "data": {
    "source": {
      "publicKey": "pk_abc123def456",
      "type": "widget",
      "name": "Web App Feedback"
    },
    "token": "eyJzb3VyY2VJZCI6Ii4uLiJ9.a1b2c3d4e5f6",
    "expiresAt": 1708531200,
    "config": {
      "requireCaptcha": true
    }
  }
}

Errores:

Codigo	Descripcion
404	Fuente de feedback no encontrada para la publicKey proporcionada
403	El origen (dominio) de la peticion no esta en la lista de dominios permitidos

---

POST /feedback/ingest

Envia un item de feedback. Requiere el token obtenido del endpoint bootstrap.

Headers:

Content-Type: application/json

Body:

Nombre	Tipo	Requerido	Descripcion
publicKey	string	Si	Public Key de la fuente de feedback
token	string	Si	Widget token obtenido de bootstrap
message	string	Si	Contenido del feedback (1-5000 caracteres)
category	string	No	Categoria: bug, feature_request, improvement, question, praise, other
email	string	No	Email del remitente
pageUrl	string	No	URL de la pagina donde se envio el feedback
locale	string	No	Idioma/locale del usuario
captchaToken	string	No	Token de hCaptcha (requerido si la fuente tiene captcha habilitado)

Ejemplo de peticion:

curl -X POST "https://api.almirant.ai/feedback/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "publicKey": "pk_abc123def456",
    "token": "eyJzb3VyY2VJZCI6Ii4uLiJ9.a1b2c3d4e5f6",
    "message": "El formulario de registro no valida emails correctamente",
    "category": "bug",
    "email": "[email protected]",
    "pageUrl": "https://miapp.com/registro",
    "locale": "es"
  }'

Respuesta exitosa (201):

{
  "success": true,
  "data": {
    "id": "fb-uuid-001",
    "status": "new",
    "createdAt": "2025-02-15T10:30:00.000Z"
  }
}

Errores:

Codigo	Descripcion
400	Token de captcha invalido o ausente (cuando captcha es requerido)
401	Widget token invalido o expirado
403	El origen (dominio) de la peticion no esta permitido
404	Fuente de feedback no encontrada
409	Feedback duplicado detectado (mismo contenido enviado recientemente)
429	Rate limit excedido

Flujo completo de integracion

1. Widget se carga en la pagina del usuario
   |
2. GET /feedback/widget/bootstrap?publicKey=pk_...
   |-- Obtiene token temporal + configuracion
   |
3. Usuario escribe feedback y envia
   |
4. POST /feedback/ingest
   |-- publicKey + token + message + metadata
   |
5. Feedback aparece en Almirant como item nuevo

Protecciones

La API incluye las siguientes protecciones:

• Validacion de origen: Solo acepta peticiones desde los dominios configurados en la fuente de feedback (soporta wildcards como *.midominio.com)
• Widget tokens firmados: Tokens HMAC-SHA256 con expiracion temporal
• Rate limiting: Limita el numero de peticiones por IP y fuente dentro de una ventana temporal
• Deduplicacion: Detecta y rechaza feedback duplicado enviado recientemente (basado en hash SHA-256 del contenido normalizado)
• hCaptcha: Verificacion de captcha opcional por fuente (habilitada por defecto)

Categorias de feedback

Categoria	Descripcion
bug	Reporte de error o mal funcionamiento
feature_request	Solicitud de nueva funcionalidad
improvement	Sugerencia de mejora sobre funcionalidad existente
question	Pregunta o solicitud de informacion
praise	Comentario positivo
other	Categoria por defecto cuando no se especifica

Integracion servidor-a-servidor

Para integraciones desde backend (sin widget), el flujo es el mismo: primero llama a bootstrap para obtener un token y luego envia el feedback a ingest. La diferencia es que debes asegurarte de que el dominio de origen este en la lista de permitidos de la fuente de feedback, o configurar la fuente sin restricciones de dominio.

Vincular feedback con ideas

El feedback ingresado puede vincularse a items del Idea Hub usando el MCP tool link_feedback_to_idea_item. Esto crea trazabilidad entre el feedback de usuarios y las decisiones de producto.