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
- 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.
- 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.
- 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ão | O 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": ["…"] } }
}
}
| HTTP | code | Quando |
| 400 | credentials_in_url, invalid_idempotency_key | Chave no endereço; Idempotency-Key em formato inválido. |
| 401 | unauthenticated | Chave ausente, errada, revogada ou vencida. |
| 403 | insufficient_scope, ip_not_allowed, https_required, plan_required | Falta 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). |
| 404 | not_found | Não existe (ou é de outra organização). |
| 405 | method_not_allowed | Método errado para o endereço. |
| 409 | conflicts, conflict, idempotency_in_progress | O plano tem avisos; a ação não cabe no estado atual; pedido repetido ainda em andamento. |
| 413 / 415 | payload_too_large, unsupported_media_type | Corpo grande demais; corpo que não é JSON. |
| 422 | validation_failed, idempotency_key_reused | Dados inválidos (veja details.fields). |
| 429 | rate_limited | Muitos pedidos. Espere os segundos do cabeçalho Retry-After. |
| 500 | internal_error | Falha 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 caminho | Permissão | O que faz |
GET /me | qualquer chave | Organização, nome e permissões da chave, limites, horário e fuso do servidor. |
Grupos
| Método e caminho | Permissão | O que faz |
GET /groups | read | Grupos 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} | read | Um grupo, com situações abertas por criticidade e entradas e saídas dos últimos 30 dias. |
GET /groups/{id}/members/timeline | read | Entradas e saídas por semana e tamanho do grupo por dia. Filtro: weeks (1 a 52, padrão 12). |
GET /groups/{id}/regions | read | Membros por estado (pelo DDD), só totais. Filtro: view=members|joined|left. complete: false indica amostra. |
GET /groups/{id}/members/events | read + personal:read | Quem entrou e saiu, com nome. Filtro: since. |
Situações (alertas)
| Método e caminho | Permissão | O que faz |
GET /incidents | read | Lista, 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} | read | Detalhes, com os motivos do alerta (reasons), assuntos e a linha do tempo. |
GET /incidents/{id}/messages | read + personal:read | As mensagens da situação. |
PATCH /incidents/{id} | incidents:write | Envie 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 caminho | Permissão | O que faz |
GET /stats/overview | read | O resumo de agora: mensagens de hoje, situações abertas por criticidade, perguntas sem resposta, resolvidas hoje e tempo médio de resposta. |
GET /stats/daily | read | Sé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/terms | read | Termos monitorados com as menções dos últimos 7 dias e dos 7 anteriores. |
Distribuição de conteúdo
| Método e caminho | Permissão | O que faz |
GET /distribution/contents | read | Conteú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} | read | Um conteúdo com todos os envios. |
GET /distribution/sends | read | Envios 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/contents | distribution:write | Planeja um conteúdo em um ou mais grupos (veja abaixo). |
PATCH /distribution/sends/{id} | distribution:write | status: 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 caminho | Permissão | O que faz |
GET /messages | read + personal:read | Mensagens 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.
| Evento | Quando | Dados (data) |
incident.created | Uma situação nova foi encontrada | incident |
incident.severity_changed | A criticidade de uma situação mudou | incident, previous_severity |
incident.status_changed | O status de uma situação mudou (em atendimento, resolvido, ignorado…) | incident, previous_status |
content.send_due | Chegou a hora de um envio planejado | send, content |
content.sent | Um conteúdo foi enviado em um grupo | send, content |
content.review_approved | Um conteúdo foi aprovado na revisão | content, review |
content.review_changes_requested | O revisor pediu ajustes em um conteúdo | content, review |
ping | Botã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.
- Leia
t (horário, em segundos) e v1 do cabeçalho X-Sondar-Signature.
- 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).
- Compare com
v1 usando uma comparação em tempo constante.
- 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.