Pular para o conteúdo principal

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çãoEndereçoQuem usa
Canal públicocanal.trust.nearone.com.brQuem faz um relato e depois acompanha o caso com protocolo e chave de acesso
Backofficebackoffice.trust.nearone.com.brA equipe da empresa que recebe, apura e encerra os casos, e quem administra a organização
Central de Ajudahelpdesk.trust.nearone.com.brGuias 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.
Por que isso importa para a sua integração

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:

TarefaExemplo
E-mails e notificaçõesAviso à equipe de que um relato chegou; código de verificação de segundo fator
WebhooksEntrega dos eventos assinados para a URL da sua integração, com novas tentativas
AntivírusOs 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çõesSugestões de triagem por IA (quando ligadas) e regras de automação disparadas por eventos ou por tempo
Limpeza de retençãoDescarte 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:

PlanoPrefixoQuem usaCredencial
Organização (equipe)/api/v1/Backoffice e integrações da empresaToken de acesso de pessoa ou chave de API sgk_
Público (canal)/api/audience/v1/public/reporting/Canal de denúnciasNenhuma para relatar; protocolo e chave de acesso para acompanhar
MCP/mcpClientes de IA compatíveis com MCPToken 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 exemplo 522U) 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​