Sondar.ia

API v1

Documentação da API

A API é a porta para outros programas conversarem com o Sondar.ia: automações (n8n, Zapier, Make), painéis e relatórios, e os sistemas da sua empresa. Por ela dá para consultar situações, grupos, números e a distribuição de conteúdo, agir (mudar o status de uma situação, planejar e marcar envios) e receber avisos na hora em que algo acontece (webhooks).

A API nunca envia mensagens nos grupos e, por padrão, não entrega texto de mensagens nem dados de membros.

Endereço

https://app.sondaria.com.br/api/v1

Acesso

Chave no cabeçalho Authorization, criada por um Admin na página API do sistema. Disponível no plano MAX.

Formato

JSON, sempre por HTTPS. Datas em ISO 8601 com fuso.

Começar em 5 minutos

  1. Crie uma chave. Um Admin abre API → Criar chave (no menu lateral), dá um nome (o programa que vai usar), marca as permissões e copia a chave. Ela aparece uma única vez.
  2. Teste a chave. No terminal:
    curl https://app.sondaria.com.br/api/v1/me \
      -H "Authorization: Bearer SUA_CHAVE"
    A resposta mostra de qual organização é a chave e o que ela pode fazer.
  3. Faça a primeira consulta. As situações críticas abertas agora:
    curl "https://app.sondaria.com.br/api/v1/incidents?status=open&severity=critical" \
      -H "Authorization: Bearer SUA_CHAVE"

No n8n

Use o nó HTTP Request. Em Authentication, escolha Generic Credential Type → Header Auth, com Name Authorization e Value Bearer SUA_CHAVE. Assim a chave fica guardada nas credenciais do n8n, e não escrita no fluxo. Para receber avisos, use o nó Webhook e cadastre o endereço de produção dele em API → Cadastrar webhook.

Chaves e segurança

Toda chamada leva a chave no cabeçalho:

Authorization: Bearer sdr_XXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

A chave funciona como uma senha. O sistema guarda só uma impressão digital dela (hash), então nem a equipe do Sondar.ia consegue recuperá-la: quem perde cria outra.

  • Nunca no endereço. ?api_key=… é recusado com erro 400, porque endereços ficam em históricos e registros de servidores.
  • Nunca em páginas ou aplicativos. A API é para programas em servidores. Uma chave dentro de uma página fica visível para qualquer visitante; por isso chamadas feitas direto do navegador são bloqueadas (sem CORS).
  • Uma chave por programa. Dá para revogar uma sem parar as outras, e o registro mostra quem fez o quê.
  • O mínimo de permissões. Um painel só precisa de read.
  • Validade. O padrão é 90 dias. Perto do fim, crie outra chave e troque no programa.
  • Restrição por IP (opcional): se o programa tem endereço fixo, a chave só funciona de lá.
  • Vazou? Revogue em API, no menu lateral. A chave para de funcionar na hora.
  • Só HTTPS. Em produção, chamadas por http são recusadas.
  • Estar logado no sistema não dá acesso à API, e a API não usa cookies.

Depois de 10 tentativas com chave errada em um minuto, o endereço IP fica bloqueado por um minuto (erro 429).

Permissões

Cada chave tem uma ou mais permissões (escopos). Chamar um endereço sem a permissão dele responde 403 insufficient_scope, dizendo qual falta.

PermissãoO que libera
read
Consultar
Ler situações, grupos, números, menções e a distribuição de conteúdo. Sem mensagens nem dados de membros.
incidents:write
Agir nas situações
Mudar o status, definir o responsável e registrar anotações.
distribution:write
Planejar e marcar envios
Planejar conteúdos, reagendar e marcar envios como enviados ou pulados.
personal:read
Ler mensagens e dados de membros
Texto das mensagens, nomes de quem escreveu e entradas e saídas com nome. Dados pessoais (LGPD): só marque se for mesmo necessário.

personal:read sozinha não basta: os endereços de mensagens também pedem read. As permissões de ação não incluem a de consulta.

Formato, paginação e erros

  • Respostas: {"data": …}; listas trazem também meta.
  • Envio de dados (POST e PATCH): corpo em JSON, com Content-Type: application/json, até 256 KB. Campos desconhecidos são ignorados.
  • Datas: ISO 8601 com fuso, como 2026-11-19T14:30:00-03:00. Nos filtros, também vale só o dia (2026-11-19). O fuso do sistema aparece em /me.
  • Ids: números inteiros. Um id que não existe ou é de outra organização responde 404.

Paginação

Listas aceitam page (começa em 1) e per_page (padrão 25, máximo 100).

{
  "data": [ … ],
  "meta": { "page": 1, "per_page": 25, "total": 132, "has_more": true }
}

Erros

Todo erro tem o mesmo formato. Use code no seu programa; message é para pessoas.

{
  "error": {
    "code": "validation_failed",
    "message": "Os dados enviados não passaram na validação.",
    "details": { "fields": { "scheduled_at": ["…"] } }
  }
}
HTTPcodeQuando
400credentials_in_url, invalid_idempotency_keyChave no endereço; Idempotency-Key em formato inválido.
401unauthenticatedChave ausente, errada, revogada ou vencida.
403insufficient_scope, ip_not_allowed, https_required, plan_requiredFalta permissão; IP fora da lista da chave; chamada sem HTTPS; o plano da organização não inclui a API (só o MAX inclui).
404not_foundNão existe (ou é de outra organização).
405method_not_allowedMétodo errado para o endereço.
409conflicts, conflict, idempotency_in_progressO plano tem avisos; a ação não cabe no estado atual; pedido repetido ainda em andamento.
413 / 415payload_too_large, unsupported_media_typeCorpo grande demais; corpo que não é JSON.
422validation_failed, idempotency_key_reusedDados inválidos (veja details.fields).
429rate_limitedMuitos pedidos. Espere os segundos do cabeçalho Retry-After.
500internal_errorFalha do nosso lado. Tente de novo; se continuar, fale com o suporte informando o X-Request-Id.

Limites e repetição segura

Cada chave pode fazer até 120 pedidos por minuto. Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining. Ao passar do limite, a resposta é 429 com Retry-After (segundos). Para acompanhar acontecimentos, prefira os webhooks a consultar de minuto em minuto.

Idempotency-Key

Se a internet cair no meio de um POST, seu programa não sabe se o pedido chegou. Para poder repetir sem criar em dobro, mande o cabeçalho Idempotency-Key com um identificador seu (de 8 a 128 caracteres; por exemplo, o id da execução no n8n). Por 24 horas, repetir o mesmo pedido com o mesmo identificador devolve a primeira resposta, com Idempotent-Replayed: true, sem executar de novo. Usar o mesmo identificador com um pedido diferente responde 422.

Endereços da API

Todos começam com https://app.sondaria.com.br/api/v1.

Chave

Método e caminhoPermissãoO que faz
GET /mequalquer chaveOrganização, nome e permissões da chave, limites, horário e fuso do servidor.

Grupos

Método e caminhoPermissãoO que faz
GET /groupsreadGrupos acompanhados, com saúde (health.score de 0 a 100, status: healthy, needs_attention, at_risk, critical, e os motivos), situações abertas e mensagens de hoje. Só os grupos acompanhados aparecem na API.
GET /groups/{id}readUm grupo, com situações abertas por criticidade e entradas e saídas dos últimos 30 dias.
GET /groups/{id}/members/timelinereadEntradas e saídas por semana e tamanho do grupo por dia. Filtro: weeks (1 a 52, padrão 12).
GET /groups/{id}/regionsreadMembros por estado (pelo DDD), só totais. Filtro: view=members|joined|left. complete: false indica amostra.
GET /groups/{id}/members/eventsread + personal:readQuem entrou e saiu, com nome. Filtro: since.

Situações (alertas)

Método e caminhoPermissãoO que faz
GET /incidentsreadLista, da atividade mais recente para a mais antiga. Filtros: status (open, closed, new, monitoring, in_progress, resolved, ignored), severity (um ou mais de normal, monitor, attention, critical, separados por vírgula), category, group_id, updated_since, started_since.
GET /incidents/{id}readDetalhes, com os motivos do alerta (reasons), assuntos e a linha do tempo.
GET /incidents/{id}/messagesread + personal:readAs mensagens da situação.
PATCH /incidents/{id}incidents:writeEnvie um ou mais de: status, note (anotação interna, até 1.000 caracteres), assignee_email (e-mail de alguém da organização, ou null para tirar o responsável). Fica na linha do tempo e na auditoria, com o nome da chave.

Categorias (category): instability, external_instability, complaint, churn_risk, conflict, collective_question, unanswered_question, mention, abnormal_activity, opportunity.

{
  "data": {
    "id": 12,
    "url": "https://…/incidentes/12",
    "group": { "id": 1, "name": "Clientes Premium" },
    "category": "instability", "category_label": "Instabilidade",
    "product": "Donna",
    "status": "new", "status_label": "Novo",
    "severity": "critical", "severity_label": "Crítico", "score": 100,
    "escalating": true,
    "title": "Problema de acesso — Donna",
    "summary": "5 participantes, 8 mensagens. Criticidade: Crítico. A conversa está piorando. Nenhuma resposta da equipe identificada.",
    "messages_count": 8, "participants_count": 5, "sentiment": "negative",
    "team_responded": false, "team_responded_at": null,
    "started_at": "2026-11-12T18:29:32-03:00",
    "last_activity_at": "2026-11-12T18:35:17-03:00",
    "resolved_at": null
  }
}

Números

Método e caminhoPermissãoO que faz
GET /stats/overviewreadO resumo de agora: mensagens de hoje, situações abertas por criticidade, perguntas sem resposta, resolvidas hoje e tempo médio de resposta.
GET /stats/dailyreadSérie por dia: mensagens, perguntas, tom negativo e positivo, entradas e saídas. Filtros: from, to (AAAA-MM-DD, até 92 dias; padrão: últimos 30) e group_id.
GET /mentions/termsreadTermos monitorados com as menções dos últimos 7 dias e dos 7 anteriores.

Distribuição de conteúdo

Método e caminhoPermissãoO que faz
GET /distribution/contentsreadConteúdos, com progresso (sends_sent de sends_total) e situação da revisão. Filtros: review=none|pending|changes|approved, origin=planned|insight|detected, type, created_since.
GET /distribution/contents/{id}readUm conteúdo com todos os envios.
GET /distribution/sendsreadEnvios por grupo. Filtros: status=planned|sent|skipped, due=true (planejados cujo horário já chegou), group_id, from, to. Em cada envio, state é planned, due, late, sent ou skipped.
POST /distribution/contentsdistribution:writePlaneja um conteúdo em um ou mais grupos (veja abaixo).
PATCH /distribution/sends/{id}distribution:writestatus: sent (marca como enviado), skipped ou planned; ou scheduled_at para mudar o horário.

Planejar não envia nada: o envio continua sendo feito por uma pessoa, no WhatsApp. O sistema lembra na hora e reconhece a mensagem quando ela sai.

curl -X POST https://app.sondaria.com.br/api/v1/distribution/contents \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: campanha-nov-0001" \
  -d '{
    "title": "Vídeo: como cadastrar um prazo",
    "type": "conteudo",
    "text": "Saiu vídeo novo mostrando como cadastrar um prazo.",
    "link": "https://youtu.be/abc123",
    "campaign": "Novembro",
    "group_ids": [1, 2],
    "scheduled_at": "2026-11-25T10:00:00-03:00",
    "mode": "stagger",
    "interval_minutes": 15
  }'
  • type: noticia, conteudo, novidade, evento, aviso, promocao, outro.
  • group_ids: grupos acompanhados da organização (até 50).
  • mode: same (mesmo horário, padrão), stagger (um grupo depois do outro, a cada interval_minutes) ou best (no dia escolhido, o horário em que cada grupo mais conversa).
  • repeat_weeks: repete toda semana por mais N semanas (0 a 12).
  • assignee_email: quem recebe o lembrete na hora (alguém da organização).

Se o plano tiver avisos (grupo com situação crítica aberta, link repetido, envios demais no dia, horário parado), a resposta é 409 conflicts com a lista em details.conflicts. Para planejar mesmo assim, repita com "confirm": true.

Mensagens

Método e caminhoPermissãoO que faz
GET /messagesread + personal:readMensagens dos grupos, da mais recente para a mais antiga, com o texto, o nome de quem escreveu e a análise. Filtros: group_id, since, until, q (busca no texto), from_team=true|false, only=questions|attention|unanswered.

Privacidade

O que sai pela API foi pensado para a LGPD:

  • Sem personal:read, nenhuma resposta leva texto de mensagem nem nome de membro. As situações vêm com título e resumo neutros (tipo, produto e números), sem citar pessoas nem trechos de conversas.
  • Com personal:read, vêm o título e o resumo completos, a recomendação, as mensagens e os nomes. Cada acesso desses fica marcado no registro como "dados pessoais". Só crie uma chave assim se o sistema de destino precisa mesmo dos dados e os protege.
  • Telefones não saem em nenhum caso. Quem não tem nome salvo aparece como "Participante 123".
  • Destaques da comunidade não existem na API: são de uso interno.
  • Nome de revisor, comentários de revisão e links de revisão também não saem.
  • Ao levar dados para outro sistema, sua organização passa a responder por eles lá (prazo de guarda, pedidos de exclusão).

Webhooks

Com um webhook, o Sondar.ia chama um endereço seu assim que algo acontece. Um Admin cadastra em API → Cadastrar webhook: nome, endereço e os acontecimentos. O segredo do webhook aparece uma única vez e serve para conferir a assinatura dos avisos.

EventoQuandoDados (data)
incident.createdUma situação nova foi encontradaincident
incident.severity_changedA criticidade de uma situação mudouincident, previous_severity
incident.status_changedO status de uma situação mudou (em atendimento, resolvido, ignorado…)incident, previous_status
content.send_dueChegou a hora de um envio planejadosend, content
content.sentUm conteúdo foi enviado em um gruposend, content
content.review_approvedUm conteúdo foi aprovado na revisãocontent, review
content.review_changes_requestedO revisor pediu ajustes em um conteúdocontent, review
pingBotão "Enviar teste"message

Os avisos nunca levam texto de mensagens nem nomes de membros: incident vem no mesmo formato da API sem personal:read. Conversas importadas de arquivo não disparam avisos.

O que chega

Um POST com corpo JSON e estes cabeçalhos:

POST /seu-endereco
Content-Type: application/json
User-Agent: Sondar-Webhooks/1.0
X-Sondar-Event: incident.created
X-Sondar-Delivery: 7c1f2c7e-6a53-4d9c-9a57-2f1f0f6c2b11
X-Sondar-Signature: t=1795113000,v1=5f8c…e21a

{
  "id": "7c1f2c7e-6a53-4d9c-9a57-2f1f0f6c2b11",
  "event": "incident.created",
  "created_at": "2026-11-19T21:50:00-03:00",
  "organization_id": 1,
  "data": {
    "incident": { "id": 12, "severity": "critical", "title": "Problema de acesso — Donna", "group": { "id": 1, "name": "Clientes Premium" }, "…": "…" }
  }
}

Regras da entrega

  • Responda rápido: qualquer código 2xx em até 5 segundos conta como entregue. Guarde o aviso e processe depois.
  • Novas tentativas: se falhar, o sistema tenta de novo depois de 1 min, 5 min, 30 min, 2 h e 6 h, e então desiste.
  • Pode chegar repetido ou fora de ordem. Use o id para ignorar um aviso que já processou.
  • Desligamento: depois de 15 falhas seguidas, o endereço é desligado e o Admin é avisado no sino. Para religar, use "Ligar" na página API.
  • Endereço: precisa ser https://, com nome de domínio público, na porta 443 ou 8443. Endereços internos (localhost, rede local) são recusados, e redirecionamentos não são seguidos.

Conferir a assinatura

Qualquer pessoa que descubra o seu endereço pode mandar um aviso falso. A assinatura prova que o aviso veio do Sondar.ia e não foi alterado no caminho. Confira sempre, antes de agir.

  1. Leia t (horário, em segundos) e v1 do cabeçalho X-Sondar-Signature.
  2. Calcule o HMAC-SHA256 do texto t + "." + corpo, usando o segredo do webhook. Use o corpo exatamente como chegou (o texto bruto, antes de transformar em objeto).
  3. Compare com v1 usando uma comparação em tempo constante.
  4. Recuse avisos com t mais antigo que 5 minutos (protege contra a repetição de um aviso capturado).

Node.js (também serve no nó "Code" do n8n)

const crypto = require('crypto');

function avisoValido(corpoBruto, cabecalho, segredo) {
  const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(cabecalho || '');
  if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false; // mais de 5 minutos
  const esperado = crypto.createHmac('sha256', segredo).update(m[1] + '.' + corpoBruto).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(m[2]));
}

PHP

function avisoValido(string $corpoBruto, string $cabecalho, string $segredo): bool
{
    if (! preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $cabecalho, $m)) return false;
    if (abs(time() - (int) $m[1]) > 300) return false; // mais de 5 minutos
    return hash_equals(hash_hmac('sha256', $m[1].'.'.$corpoBruto, $segredo), $m[2]);
}

// $corpoBruto = file_get_contents('php://input');
// $cabecalho  = $_SERVER['HTTP_X_SONDAR_SIGNATURE'] ?? '';

Se o segredo vazar, use "Trocar segredo" na página API: o anterior para de valer na hora.

Lista de segurança para quem integra

  • A chave fica num cofre de credenciais ou variável de ambiente, nunca no código, em planilhas ou em conversas.
  • Uma chave por programa, só com as permissões necessárias e com validade.
  • personal:read só quando indispensável; os dados recebidos são protegidos e apagados quando não forem mais necessários.
  • Restrição por IP ligada quando o programa tem endereço fixo.
  • Webhooks: assinatura conferida, avisos com mais de 5 minutos recusados, repetidos ignorados pelo id.
  • Erros 429 e 5xx tratados com espera crescente antes de tentar de novo; POST com Idempotency-Key.
  • Chaves que ninguém usa mais são revogadas (a tela mostra quando cada uma foi usada pela última vez).

Versões

Esta é a versão 1 (/api/v1). Dentro dela, só entram mudanças que não quebram quem já integrou: campos novos nas respostas, filtros novos, endereços novos e eventos novos. Seu programa deve ignorar campos que não conhece. Mudanças que quebram entram em uma versão nova, com aviso antes.

Atualizado em 19/11/2026.