Primeiros passos com a API
A API REST do NearOne Trust é a mesma que o backoffice usa. O que a sua equipe faz na tela — consultar a caixa de casos, responder, atribuir, priorizar, anexar arquivos — tem um endpoint correspondente, protegido pelas mesmas regras de permissão e de sigilo. Algumas decisões sensíveis ficam reservadas a pessoas e são recusadas para chaves de API; elas estão sinalizadas ao longo desta seção.
Este guia leva você do zero até a primeira consulta de casos:
- criar uma chave de API com as permissões certas;
- testar a chave com
curl; - listar casos e abrir um deles;
- escolher o próximo passo da sua integração.
Todas as rotas ficam sob https://api.trust.nearone.com.br. Os exemplos abaixo usam a variável de ambiente TRUST_API_KEY para não expor o segredo no histórico do terminal.
Antes de começar
Você precisa de:
- uma conta de membro na organização com a permissão de gerenciar chaves de API (normalmente o titular ou um administrador);
- um ambiente de servidor para guardar o segredo (um cofre de segredos, uma variável de ambiente do seu serviço, um gerenciador de credenciais do CI);
curlou qualquer cliente HTTP.
Uma chave de API não funciona a partir de um navegador. Se a requisição traz o cabeçalho Origin (o que todo navegador envia em chamadas fetch/XHR entre domínios), a API responde 401 com o código origin_not_allowed. Isso evita que o segredo acabe embutido em um site ou aplicativo e seja copiado por qualquer visitante. Chame a API sempre a partir do seu backend.
1. Crie a chave no backoffice
-
Entre no backoffice e abra o menu Integração › Chaves de API.
-
Clique em Nova chave.
-
Em Nome, use algo que identifique o sistema que vai usar a chave (por exemplo,
ERP de produçãoouBI de compliance). O nome aparece no histórico de auditoria. -
Escolha uma das duas formas de definir as permissões:
- em Clonar de um papel, selecione um papel existente e deixe a lista Permissões desmarcada: a chave recebe uma cópia das permissões desse papel (as que nunca podem ir para uma chave são descartadas);
- ou deixe Não clonar e, em Permissões, marque apenas o que a integração realmente precisa (veja a tabela abaixo).
Se você escolher um papel e marcar permissões, valem só as permissões marcadas.
-
Confira a seleção. A lista só mostra permissões que você mesmo tem.
-
Clique em Emitir chave.
-
A janela Segredo da chave mostra o valor completo, que começa com
sgk_live_. Copie e guarde agora: ele é exibido uma única vez e nenhuma consulta posterior devolve o segredo.

Ao fechar a janela do segredo, você vai para a ficha da chave, que mostra Código, Prefixo (os primeiros caracteres do segredo, seguros para exibir), Uso, Criada, Último uso, Validade e as Permissões. Na lista Chaves de API, cada chave aparece com Nome, Prefixo, Uso, Estado (Ativa ou Revogada) e Criada.

Quais permissões marcar
A chave recebe um retrato (snapshot) das permissões escolhidas no momento da criação. Mudar um papel depois não altera a chave. E uma chave só pode receber permissões que a pessoa que a emite também tem.
| Objetivo da integração | Permissões mínimas |
|---|---|
| Ler a caixa de casos e o detalhe de cada caso | requests.demands.read |
| Ler categorias e canais de denúncia | reporting.channels.read |
| Responder a quem relatou (mensagem pública) | requests.demands.read + requests.messages.send |
| Registrar notas internas da equipe | requests.demands.read + requests.messages.internal_write |
| Ler notas internas | requests.messages.internal_read |
| Atribuir ou trocar o responsável | requests.demands.assign |
| Mudar prioridade e fazer a triagem | requests.demands.triage |
| Mover o caso de etapa | requests.demands.read + a permissão exigida pela ação (por exemplo requests.demands.transition), e a ação precisa estar liberada para integrações no fluxo (veja Casos via API) |
| Listar e baixar anexos | requests.demands.read + requests.attachments.read |
| Enviar anexos | requests.attachments.manage |
| Ler o histórico protegido do caso | requests.history.read |
| Indicadores do canal | reporting.reports.read |
Algumas permissões nunca podem ser dadas a uma chave, mesmo que você as tenha: as de gestão de chaves de API (identity.api_keys.manage), as de configuração de inteligência artificial e de público, e qualquer permissão de plataforma. A tentativa responde 400 api_key_forbidden_permission.
Crie uma chave para cada sistema integrado, mesmo que eles precisem das mesmas permissões. Assim, se um sistema for desativado ou comprometido, você revoga só a chave dele, e o Último uso de cada chave conta uma história clara.
2. Faça a primeira chamada
Guarde a chave em uma variável de ambiente e chame GET /api/v1/requests/demand-counters, que devolve contadores leves e é um bom teste de ponta a ponta:
export TRUST_API_KEY='sgk_live_xxxxxxxx_...' # cole o segredo completo
curl -sS https://api.trust.nearone.com.br/api/v1/requests/demand-counters \
-H "Authorization: Bearer $TRUST_API_KEY"
A resposta tem o formato {"items": [...]}. Se algo der errado, a API responde com um envelope de erro padronizado:
{
"code": "unauthenticated",
"message": "Não autenticado.",
"request_id": "6f1c2d0e9b8a4c7e8d2f1a3b5c7d9e0f"
}
| Você recebeu | Provável causa | O que fazer |
|---|---|---|
401 unauthenticated | Segredo incompleto, chave revogada, expirada ou IP fora das redes permitidas | Confira se copiou o segredo inteiro e se a chave está Ativa |
401 origin_not_allowed | A chamada saiu de um navegador | Mova a chamada para o seu backend |
403 permission_denied | A chave não tem a permissão da rota | Emita uma nova chave com a permissão (ou ajuste a existente) |
403 actor_not_allowed | A rota é exclusiva de pessoas (login, MFA, sessões, chaves) | Use outra rota ou faça a ação no backoffice |
429 rate_limited | Muitas chamadas em pouco tempo | Reduza o ritmo e tente de novo depois de alguns segundos (a janela do limite por chave é de 1 minuto) |
Detalhes de cada código em Erros da API.
3. Liste os casos
A caixa de casos é a listagem GET /api/v1/requests/demands. Ela segue as convenções de listagem: limit, cursor, sort, q e filter (JSON).
curl -sS -G https://api.trust.nearone.com.br/api/v1/requests/demands \
-H "Authorization: Bearer $TRUST_API_KEY" \
--data-urlencode 'limit=20' \
--data-urlencode 'sort=-created_at' \
--data-urlencode 'filter={"phase":{"neq":"closed"}}'
Resposta (resumida):
{
"items": [
{
"id": "0b9e6f0a-3c1d-4a7e-9f43-1d2c5b6a7e80",
"code": "522U",
"request_type_name": "Violação do código de conduta",
"stage_key": "triage",
"stage_label": "Triagem",
"phase": "in_progress",
"priority": "normal",
"queue": "general",
"assignee_id": null,
"unassigned": true,
"awaiting_reply": false,
"version": 3,
"created_at": "2026-11-10T14:02:11.418+00:00"
}
],
"page": { "limit": 20, "total": 1, "next_cursor": null }
}
Repare em dois identificadores:
code(522U): o código público de 4 caracteres que aparece nas telas. É ele que vai no caminho das rotas de um caso.id: o UUID interno. É o que você usa dentro de filtros e corpos de requisição.
Casos da fila restrita (os casos protegidos, como os de assédio, discriminação, violência, retaliação ou fraude, conforme a configuração da sua organização) só são visíveis para pessoas com acesso nominal concedido pela equipe protegida. Uma chave de API nunca os enxerga: eles não aparecem na listagem e, se você pedir o código diretamente, a resposta é 404. Isso é proposital — a proteção de quem relata não depende de quem configurou a integração.
Nos demais casos, a chave enxerga todas as empresas da organização: ela não tem o recorte de empresas que um membro pode ter. Por isso, dê a chave só a sistemas que podem ver a operação inteira.
4. Abra um caso
Use o código público no caminho:
curl -sS https://api.trust.nearone.com.br/api/v1/requests/demands/522U \
-H "Authorization: Bearer $TRUST_API_KEY"
O detalhe traz a etapa atual (stage, com key, label, phase e outcome), o tipo do caso (request_type), o responsável (assignee), a prioridade, os campos do formulário (values), as atividades, os lembretes e o número de version — que você vai precisar para qualquer alteração (veja concorrência otimista).
Cada leitura de um caso do canal de denúncias fica registrada no log de acesso do caso. A integração aparece ali como a chave que fez a consulta.
Integrações típicas
| Integração | Como fazer |
|---|---|
| Painel de BI com volume de casos por etapa, categoria ou empresa | Leia GET /api/v1/requests/demands com filtros e GET /api/v1/reporting/reports/summary; agende a coleta |
| Abrir ticket interno quando chega um caso | Assine um webhook e, ao receber o evento, consulte o caso pela API |
| Sincronizar responsáveis com o seu sistema de RH | POST /api/v1/requests/demands/{código}/assignments (receita em Casos via API) |
| Assistente de IA que consulta e opera casos em nome de uma pessoa | Use o servidor MCP em vez de uma chave de API |
| Arquivar evidências em um repositório da empresa | Liste e baixe os anexos do caso (requests.attachments.read) |
Próximos passos
- Entenda os tipos de credencial em Autenticação.
- Leia as Convenções da API antes de escrever código de produção: paginação, idempotência e concorrência evitam a maioria dos bugs de integração.
- Siga a receita completa em Casos via API.
- Consulte todos os endpoints na Referência da API.