Feedback API

O Almirant expõe uma API REST pública (não MCP) para ingestão de feedback de widgets incorporados em sites ou de integrações servidor a servidor. Essa API é independente do servidor MCP e não exige uma API Key do Almirant.

Autenticação

A Feedback API usa um sistema de autenticação baseado em Public Keys e widget tokens:

• Public Key (pk_...): identifica a fonte de feedback. Ela é obtida ao criar uma fonte de feedback no Almirant e pode ser exposta no frontend com segurança.
• Widget Token: token temporário assinado, obtido pelo endpoint bootstrap. Tem duração limitada e é usado para validar as solicitações de ingestão.

Endpoints

GET /feedback/widget/bootstrap

Inicializa o widget de feedback. Retorna a configuração da fonte e um token temporário assinado necessário para enviar feedback.

Parâmetros de consulta:

Nome	Tipo	Obrigatório	Descrição
publicKey	string	Sim	Public Key da fonte de feedback (pk_...)

Exemplo de solicitação:

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

Resposta bem-sucedida (200):

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

Erros:

Código	Descrição
404	Fonte de feedback não encontrada para a publicKey fornecida
403	A origem (domínio) da solicitação não está na lista de domínios permitidos

---

POST /feedback/ingest

Envia um item de feedback. Exige o token obtido pelo endpoint bootstrap.

Cabeçalhos:

Content-Type: application/json

Corpo:

Nome	Tipo	Obrigatório	Descrição
publicKey	string	Sim	Public Key da fonte de feedback
token	string	Sim	Widget token obtido de bootstrap
message	string	Sim	Conteúdo do feedback (1 a 5000 caracteres)
category	string	Não	Categoria: bug, feature_request, improvement, question, praise, other
email	string	Não	E-mail do remetente
pageUrl	string	Não	URL da página em que o feedback foi enviado
locale	string	Não	Idioma/locale do usuário
captchaToken	string	Não	Token do hCaptcha (obrigatório se a fonte tiver captcha habilitado)

Exemplo de solicitação:

curl -X POST "https://api.almirant.ai/feedback/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "publicKey": "pk_abc123def456",
    "token": "eyJzb3VyY2VJZCI6Ii4uLiJ9.a1b2c3d4e5f6",
    "message": "O formulário de cadastro não valida e-mails corretamente",
    "category": "bug",
    "email": "[email protected]",
    "pageUrl": "https://miapp.com/registro",
    "locale": "es"
  }'

Resposta bem-sucedida (201):

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

Erros:

Código	Descrição
400	Token de captcha inválido ou ausente (quando o captcha é obrigatório)
401	Widget token inválido ou expirado
403	A origem (domínio) da solicitação não é permitida
404	Fonte de feedback não encontrada
409	Feedback duplicado detectado (mesmo conteúdo enviado recentemente)
429	Limite de taxa excedido

Fluxo completo de integração

1. O widget é carregado na página do usuário
   |
2. GET /feedback/widget/bootstrap?publicKey=pk_...
   |-- Obtém token temporário + configuração
   |
3. O usuário escreve o feedback e o envia
   |
4. POST /feedback/ingest
   |-- publicKey + token + message + metadata
   |
5. O feedback aparece no Almirant como um item novo

Proteções

A API inclui as seguintes proteções:

• Validação de origem: aceita solicitações somente dos domínios configurados na fonte de feedback (suporta curingas como *.midominio.com)
• Widget tokens assinados: tokens HMAC-SHA256 com expiração temporária
• Limitação de taxa: limita o número de solicitações por IP e fonte dentro de uma janela temporal
• Desduplicação: detecta e rejeita feedback duplicado enviado recentemente (com base no hash SHA-256 do conteúdo normalizado)
• hCaptcha: verificação de captcha opcional por fonte (habilitada por padrão)

Categorias de feedback

Categoria	Descrição
bug	Relato de erro ou mau funcionamento
feature_request	Solicitação de nova funcionalidade
improvement	Sugestão de melhoria em funcionalidade existente
question	Pergunta ou solicitação de informação
praise	Comentário positivo
other	Categoria padrão quando não especificada

Integração servidor a servidor

Para integrações de backend (sem widget), o fluxo é o mesmo: primeiro chame bootstrap para obter um token e depois envie o feedback para ingest. A diferença é que você deve garantir que o domínio de origem esteja na lista de permitidos da fonte de feedback ou configurar a fonte sem restrições de domínio.

Vincular feedback a ideias

O feedback recebido pode ser vinculado a itens do Idea Hub usando a ferramenta MCP link_feedback_to_idea_item. Isso cria rastreabilidade entre o feedback dos usuários e as decisões de produto.