Pular para o conteúdo principal

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:

  1. criar uma chave de API com as permissões certas;
  2. testar a chave com curl;
  3. listar casos e abrir um deles;
  4. escolher o próximo passo da sua integração.
Endereço base

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);
  • curl ou qualquer cliente HTTP.
Chaves de API são para servidores

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​

  1. Entre no backoffice e abra o menu Integração › Chaves de API.

  2. Clique em Nova chave.

  3. Em Nome, use algo que identifique o sistema que vai usar a chave (por exemplo, ERP de produção ou BI de compliance). O nome aparece no histórico de auditoria.

  4. 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.

  5. Confira a seleção. A lista só mostra permissões que você mesmo tem.

  6. Clique em Emitir chave.

  7. 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.

Formulário Nova chave de integração no backoffice, com os campos Nome, Clonar de um papel e a lista de Permissões.
Tela de emissão de uma chave de integração. Escolha só as permissões que o sistema vai usar. Dados fictícios da organização de demonstração.

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.

Página Chaves de API do backoffice, no menu Integração, ainda sem chaves: mensagem Nenhuma chave e o botão Nova chave.
Ponto de partida: em Integração › Chaves de API, o botão Nova chave abre o formulário de emissão. Depois de emitidas, as chaves aparecem nesta lista com o prefixo, nunca com o segredo. Dados fictícios da organização de demonstração.

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çãoPermissões mínimas
Ler a caixa de casos e o detalhe de cada casorequests.demands.read
Ler categorias e canais de denúnciareporting.channels.read
Responder a quem relatou (mensagem pública)requests.demands.read + requests.messages.send
Registrar notas internas da equiperequests.demands.read + requests.messages.internal_write
Ler notas internasrequests.messages.internal_read
Atribuir ou trocar o responsávelrequests.demands.assign
Mudar prioridade e fazer a triagemrequests.demands.triage
Mover o caso de etaparequests.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 anexosrequests.demands.read + requests.attachments.read
Enviar anexosrequests.attachments.manage
Ler o histórico protegido do casorequests.history.read
Indicadores do canalreporting.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.

Uma chave por sistema

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ê recebeuProvável causaO que fazer
401 unauthenticatedSegredo incompleto, chave revogada, expirada ou IP fora das redes permitidasConfira se copiou o segredo inteiro e se a chave está Ativa
401 origin_not_allowedA chamada saiu de um navegadorMova a chamada para o seu backend
403 permission_deniedA chave não tem a permissão da rotaEmita uma nova chave com a permissão (ou ajuste a existente)
403 actor_not_allowedA rota é exclusiva de pessoas (login, MFA, sessões, chaves)Use outra rota ou faça a ação no backoffice
429 rate_limitedMuitas chamadas em pouco tempoReduza 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.
O que uma chave de API não vê

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çãoComo fazer
Painel de BI com volume de casos por etapa, categoria ou empresaLeia GET /api/v1/requests/demands com filtros e GET /api/v1/reporting/reports/summary; agende a coleta
Abrir ticket interno quando chega um casoAssine um webhook e, ao receber o evento, consulte o caso pela API
Sincronizar responsáveis com o seu sistema de RHPOST /api/v1/requests/demands/{código}/assignments (receita em Casos via API)
Assistente de IA que consulta e opera casos em nome de uma pessoaUse o servidor MCP em vez de uma chave de API
Arquivar evidências em um repositório da empresaListe e baixe os anexos do caso (requests.attachments.read)

Próximos passos​