Arquitetura em alto nível
Esta página explica, sem entrar em detalhes de infraestrutura, como o NearOne Trust está organizado e por que isso importa para quem integra. Entender as peças ajuda a prever o comportamento da API: por que alguns efeitos chegam alguns segundos depois, por que um caso some de uma listagem quando o acesso muda e por que a mesma regra vale na tela, na API e no MCP.
Visão geral
As peças
Aplicações web
São aplicações de página única (SPA) que conversam apenas com a API — não há atalho para o banco de dados:
| Aplicação | Endereço | Quem usa |
|---|---|---|
| Canal público | canal.trust.nearone.com.br | Quem faz um relato e depois acompanha o caso com protocolo e chave de acesso |
| Backoffice | backoffice.trust.nearone.com.br | A equipe da empresa que recebe, apura e encerra os casos, e quem administra a organização |
| Central de Ajuda | helpdesk.trust.nearone.com.br | Guias de uso e suporte |
Como o backoffice usa a mesma API que você, cada ação da tela tem uma rota correspondente, com as mesmas permissões. A diferença está em quem chama: algumas decisões (por exemplo, revelar a identidade de quem relatou, exportar um caso ou mudar a etapa nos fluxos de denúncia padrão) são reservadas a pessoas e recusadas para chaves de API.
API REST
A API (https://api.trust.nearone.com.br) recebe todas as chamadas, identifica quem está chamando (pessoa, chave de API ou cliente MCP), aplica limites de taxa e de tamanho de corpo e repassa a operação para o banco. As respostas de erro seguem um envelope único com code, message em português e request_id (veja Convenções).
Banco de dados com isolamento por organização
O coração das regras está no banco de dados, e não só no código da API:
- Isolamento por organização. Cada linha pertence a uma organização, e políticas de segurança em nível de linha garantem que uma consulta só enxergue dados da organização da credencial. Não existe parâmetro que permita "olhar" outra organização.
- Permissões e escopo verificados a cada chamada. Permissão, escopo de empresas, acesso nominal a casos protegidos e impedimentos por conflito de interesse são reavaliados em toda leitura e em todo comando. Um caso que você não pode ver responde
404, exatamente como um caso que não existe — assim a API não revela nem a existência de um caso protegido. - Comandos atômicos. Cada comando sobre um caso (mover etapa, atribuir, responder) confere a versão do caso, aplica o efeito, grava o histórico e a auditoria e emite o evento na mesma transação. Ou tudo acontece, ou nada.
Se a equipe protegida revogar o acesso de alguém, ou se um caso for movido para a fila restrita, a próxima chamada já reflete a mudança. Não há cache de permissão que possa vazar um caso por alguns minutos.
Processamento assíncrono
Algumas tarefas não precisam (ou não devem) acontecer durante a requisição. Um processo de trabalho separado cuida delas, lendo filas gravadas pelo banco na mesma transação do comando:
| Tarefa | Exemplo |
|---|---|
| E-mails e notificações | Aviso à equipe de que um relato chegou; código de verificação de segundo fator |
| Webhooks | Entrega dos eventos assinados para a URL da sua integração, com novas tentativas |
| Antivírus | Os arquivos enviados pelo canal público ficam em quarentena até a verificação; um arquivo ainda não verificado responde 409 requests_attachment_quarantined ao ser aberto |
| Prazos (SLA) | Verificação periódica dos prazos para marcar casos perto do fim ou vencidos |
| Triagem assistida e automações | Sugestões de triagem por IA (quando ligadas) e regras de automação disparadas por eventos ou por tempo |
| Limpeza de retenção | Descarte de objetos de casos expurgados conforme a política de retenção |
Por isso, efeitos colaterais (o e-mail, o webhook, o alerta de prazo) chegam alguns segundos depois do 200 da API. A resposta do comando já é definitiva; o restante é consequência.
Armazenamento de arquivos
Anexos de casos ficam em um armazenamento de objetos, cifrados individualmente e vinculados à organização e ao anexo. O download nunca é um link público: a API reautoriza quem pede, decifra o arquivo, confere a integridade e devolve os bytes com Content-Disposition: attachment e Cache-Control: no-store.
Os três planos de acesso
A API atende três "planos", cada um com sua forma de autenticação e suas rotas:
| Plano | Prefixo | Quem usa | Credencial |
|---|---|---|---|
| Organização (equipe) | /api/v1/ | Backoffice e integrações da empresa | Token de acesso de pessoa ou chave de API sgk_ |
| Público (canal) | /api/audience/v1/public/reporting/ | Canal de denúncias | Nenhuma para relatar; protocolo e chave de acesso para acompanhar |
| MCP | /mcp | Clientes de IA compatíveis com MCP | Token OAuth emitido após o consentimento de uma pessoa |
Os planos são separados de propósito: uma chave de API não é aceita nas rotas do canal público, e o token de quem relata não serve nas rotas da equipe. Assim, nenhuma integração pode se passar por quem relatou nem descobrir quem é essa pessoa.
Identificadores
- Recursos têm um UUID interno (
id) e, na maioria dos casos, um código público curto (code, por exemplo522U) mostrado nas telas. - Rotas que apontam para um recurso usam o código no caminho (
/api/v1/requests/demands/522U). Filtros e corpos usam o UUID.
Detalhes em Convenções da API.
Leia também
- Autenticação — como cada credencial funciona.
- Segurança e privacidade — a visão de produto das proteções.
- Webhooks e MCP.