Pular para o conteúdo principal

Convenções da API

A API do NearOne Trust segue um conjunto pequeno de convenções. Conhecê-las evita a maioria dos problemas de integração: páginas puladas, comandos duplicados, alterações que sobrescrevem o trabalho de outra pessoa.

TemaResumo
FormatoJSON em UTF-8, datas ISO 8601 em UTC, mensagens em português
Listagenslimit, cursor, sort, q, filter → {items, page}
Erros{code, message, request_id} com status HTTP coerente
Idempotênciarequest_nonce nos comandos de casos; Idempotency-Key nas demais rotas
Concorrênciaexpected_version + 409 em caso de conflito
IdentificadoresCódigo público de 4 caracteres no caminho, UUID no corpo e nos filtros
LimitesLimite de taxa por chave, tamanho de corpo e de arquivos

Formato geral​

  • Envie e receba JSON (Content-Type: application/json), exceto em uploads de arquivo (multipart/form-data) e downloads (bytes do arquivo).
  • Datas e horas estão em ISO 8601 com fuso (por exemplo 2026-11-10T14:02:11.418+00:00). Campos só de data usam AAAA-MM-DD.
  • Campos desconhecidos são recusados nos corpos dos comandos de casos. Isso protege você de erros de digitação silenciosos: um asignee_id errado gera erro, em vez de ser ignorado.
  • Valores de domínio (fases, prioridades, chaves de transição) são identificadores estáveis em inglês e minúsculas (in_progress, urgent, to_investigation). Os rótulos para pessoas vêm em campos próprios (stage_label, label).
  • As mensagens de erro (message) são escritas em português do Brasil, prontas para exibir. Programe sempre em cima do code, que nunca muda de idioma.

Rastreando uma chamada: X-Request-ID​

Toda resposta traz o cabeçalho X-Request-ID, repetido no campo request_id dos erros. Você pode enviar o seu próprio identificador (até 64 caracteres, letras, números e hífen) no cabeçalho X-Request-ID da requisição para correlacionar com os seus logs; se o valor não seguir esse formato, a API gera outro.

Listagens​

As rotas de listagem (por exemplo GET /api/v1/requests/demands, GET /api/v1/api-keys, GET /api/v1/webhooks, GET /api/v1/audit/events) aceitam os mesmos parâmetros de consulta:

ParâmetroPadrãoDescrição
limit50Itens por página, de 1 a 100.
cursor—Valor de page.next_cursor da página anterior. Omita na primeira página.
sortdepende do recurso (casos: -created_at)Campos de ordenação separados por vírgula; - na frente = decrescente. Até 8 campos.
q—Busca textual (até 200 caracteres) nos campos pesquisáveis do recurso.
filter—Objeto JSON com condições sobre campos permitidos (veja abaixo).

Envelope de resposta​

{
"items": [ { "id": "…", "code": "522U" } ],
"page": {
"limit": 50,
"total": 132,
"next_cursor": "eyJ2IjpbIjIwMjYtMTEtMTBUMTQ6MDI6MTEuNDE4KzAwOjAwIiwiMGI5ZTZm…"
}
}
  • page.total é o total de itens que atendem ao filtro dentro do que a credencial pode ver.
  • page.next_cursor é null na última página.
Nem toda coleção é paginada

Coleções pequenas e ligadas a um único recurso — mensagens, histórico, anexos e transições disponíveis de um caso, por exemplo — respondem só {"items": [...]}, completas, sem page nem parâmetros de listagem.

Paginação por cursor​

A paginação é por cursor (keyset), não por número de página. Isso garante que nenhum item seja pulado ou repetido quando casos novos chegam enquanto você percorre a lista.

import json, os, requests

API = "https://api.trust.nearone.com.br"
HEADERS = {"Authorization": f"Bearer {os.environ['TRUST_API_KEY']}"}

def todos_os_casos_abertos():
params = {
"limit": 100,
"sort": "-created_at",
"filter": json.dumps({"phase": {"neq": "closed"}}),
}
while True:
r = requests.get(f"{API}/api/v1/requests/demands", headers=HEADERS, params=params, timeout=30)
r.raise_for_status()
body = r.json()
yield from body["items"]
cursor = body["page"]["next_cursor"]
if not cursor:
break
params["cursor"] = cursor # mantenha sort, filter e q iguais
O cursor está preso à ordenação

Um cursor só vale para a mesma ordenação que o gerou. Se você mudar sort e reaproveitar um cursor antigo, a API responde 400 listing_invalid. Mude filter ou q só recomeçando da primeira página. Cursores são temporários: não os guarde para usar dias depois.

Ordenação​

sort=-priority,created_at ordena por prioridade decrescente e, no empate, pela data de criação crescente. A API sempre acrescenta o id como critério final de desempate, para a ordem ser estável. Valores nulos ficam por último nos dois sentidos.

Só campos marcados como ordenáveis no recurso são aceitos; os demais respondem 400 listing_invalid.

Filtros​

filter é um objeto JSON (lembre de codificá-lo na URL). Cada chave é um campo permitido do recurso:

{ "phase": "closed" }

equivale a {"phase": {"eq": "closed"}}. Para outros operadores, use um objeto com um operador:

OperadorSignificadoTipos
eq / neqigual / diferentetodos
inestá na lista (até 50 valores)texto, UUID, inteiro (não vale para datas nem booleanos)
containscontém o texto (sem diferenciar maiúsculas)campos de texto livre, como code, subject_name e request_type_name (não vale para campos de valores fixos, como phase ou priority)
gt gte lt ltemaior / maior ou igual / menor / menor ou igualdata e hora, inteiro
is_nulltrue = vazio, false = preenchidocampos que podem ser nulos

Campos booleanos (unassigned, awaiting_reply…) aceitam só eq e neq. Cada campo declara os operadores que aceita; um operador fora da lista do campo responde 400 listing_invalid.

Várias chaves no mesmo objeto são combinadas com E. Para combinações mais complexas, use and e or:

{
"and": [
{ "phase": { "neq": "closed" } },
{ "or": [ { "priority": "urgent" }, { "unassigned": true } ] },
{ "created_at": { "gte": "2026-11-01T00:00:00Z" } }
]
}

Limites do filtro: profundidade máxima 3, até 20 condições no total, até 10 itens em cada or, textos de até 500 caracteres. Fora disso, ou com um campo/operador não permitido, a resposta é 400 listing_invalid.

Lista de campos permitidos

O filtro não é SQL livre: cada recurso declara quais campos podem ser filtrados e ordenados. Isso protege o desempenho e o sigilo (não há como filtrar por um dado que você não pode ver).

Campos da listagem de casos​

Para GET /api/v1/requests/demands:

CampoTipoFiltrarOrdenarObservações
idUUIDsimsim
codetextosimsimtambém pesquisado por q
subject_nametextosimsimtambém pesquisado por q
subject_kindtextosim—
subject_idUUIDsim—
company_idUUIDsim—empresa do caso
category_idUUIDsim—grupo de categorias (ex.: denúncias)
request_type_idUUIDsim—categoria/tipo do caso
request_type_nametextosimsim
workflow_id, workflow_version_idUUIDsim—
stage_keytextosim—etapa atual (ex.: triage)
stage_positioninteirosimsimposição da etapa no fluxo
phasetextosimsimpending, in_progress, waiting, closed
outcometextosimsimdesfecho de um caso encerrado; nulo enquanto aberto
queuetextosim—fila do caso
prioritytextosimsimnormal, high, urgent
assignee_idUUIDsim—responsável
unassignedbooleanosim—sem responsável
awaiting_replybooleanosim—há mensagem de quem relatou sem resposta da equipe
reassignment_pendingbooleanosim—
waiting_reasontextosim—
channel, origin, clienttextosim—como o caso foi aberto (client = api para casos abertos por chave)
requested_byUUIDsim—quem abriu
checklist_total, checklist_doneinteirosim—
reminder_pendingbooleanosim—
created_at, updated_at, closed_atdata e horasimsim
tag_idUUIDsim (eq ou in, só no nível de cima)—casos com a etiqueta

Envelope de erro​

Todo erro de regra de negócio, autenticação ou permissão responde com o mesmo formato:

{
"code": "requests_version_conflict",
"message": "A configuração foi alterada por outra pessoa. Atualize a tela e tente de novo.",
"request_id": "9a7c3e1f0b2d4c6e8f1a2b3c4d5e6f70"
}
CampoPara que serve
codeIdentificador estável do erro. É nele que o seu código deve se basear.
messageTexto em português para exibir a uma pessoa. Pode ser melhorado com o tempo; não compare strings.
request_idIdentificador da chamada. Informe ao suporte.

Alguns erros trazem campos extras no mesmo nível, por exemplo a lista problems em requests_validation_error:

{
"code": "requests_validation_error",
"message": "Alguns dados informados não são válidos. Revise os campos e tente de novo.",
"request_id": "…",
"problems": [ { "field": "parecer", "code": "required" } ]
}

Nos comandos sobre casos, cada item de problems aponta o campo (field) e o motivo (code). Na publicação de fluxos e tipos de solicitação, os itens trazem path e, quando houver, detail.

Erros de formato do corpo (422)​

Quando o corpo não corresponde ao formato da rota (tipo errado, campo obrigatório ausente, campo desconhecido), as rotas da organização (/api/v1/...) respondem 422 com uma lista de problemas por campo:

{
"detail": [
{
"type": "missing",
"loc": ["body", "expected_version"],
"msg": "Field required"
}
]
}

As rotas do canal público usam o envelope padrão (code: "validation_error") com a mesma lista no campo errors. Em nenhum dos casos a API devolve o valor que você enviou — assim um segredo digitado no campo errado não volta na resposta nem vai para logs.

Erros temporários​

StatuscodeO que fazer
409concurrency_conflictDuas operações disputaram os mesmos dados. Tente de novo após Retry-After (1 s).
503unavailableServiço temporariamente indisponível. Tente de novo após Retry-After.
429rate_limitedLimite de taxa. Aguarde Retry-After quando vier; no limite por chave de API o cabeçalho não é enviado, então espere alguns segundos.
500internal_errorErro inesperado. Tente de novo com recuo; se persistir, informe o request_id.

Veja a tabela completa em Erros da API.

Idempotência​

Redes falham. Se a sua requisição de "responder ao relato" expirar sem resposta, você não sabe se a mensagem foi gravada. A API oferece dois mecanismos para repetir com segurança.

Comandos de casos: request_nonce​

Os comandos sob /api/v1/requests/ que alteram um caso (responder, registrar nota, atribuir, mudar prioridade, mover etapa, anexar, retirar anexo, cancelar…) exigem um campo request_nonce (UUID) no corpo — no upload de anexo, ele vai como campo do formulário multipart:

{
"request_nonce": "5f0c8a52-7f1e-4f61-9a43-0d9d3b0f2e11",
"visibility": "internal",
"body": "Documentos solicitados ao financeiro."
}

Regras:

  1. Gere um UUID novo para cada intenção (cada mensagem, cada atribuição) e guarde-o junto com a intenção antes de enviar.
  2. Se precisar repetir (timeout, queda de conexão), reenvie o mesmo nonce com o mesmo conteúdo. A API devolve o resultado original com "replayed": true e não executa de novo.
  3. O mesmo nonce com outro conteúdo responde 409 requests_nonce_conflict.
  4. O recibo vale por 7 dias. Depois disso, repetir o nonce responde 409 requests_nonce_expired: consulte o estado atual do caso.
  5. A permissão é verificada antes de devolver uma repetição: se o acesso foi revogado nesse meio-tempo, a repetição também é recusada.
{ "id": "3e9d…", "demand_id": "0b9e…", "result": "created", "replayed": true }
Não use Idempotency-Key nas rotas de casos

Nas rotas /api/v1/requests/... o cabeçalho Idempotency-Key é recusado com 400 requests_idempotency_header_not_supported. Use apenas o request_nonce.

Demais rotas: cabeçalho Idempotency-Key​

Nas outras rotas POST, PATCH e DELETE da organização, você pode enviar o cabeçalho Idempotency-Key com um valor único por intenção:

curl -sS -X POST https://api.trust.nearone.com.br/api/v1/companies \
-H "Authorization: Bearer $TRUST_API_KEY" \
-H "Idempotency-Key: 2c1d1b0e-cadastro-filial-sp" \
-H "Content-Type: application/json" \
-d '{ … }'
  • Uma repetição com a mesma chave e o mesmo pedido em até 24 horas devolve a resposta original (mesmo status e corpo) com o cabeçalho X-Idempotency-Replay: 1.
  • A mesma chave com outro pedido responde 409 idempotency_conflict.
  • Respostas que contêm credenciais nunca são guardadas. Por isso o cabeçalho é ignorado em login, conta pessoal, chaves de API, webhooks e MCP, e é recusado (400) em operações do canal de denúncias cuja resposta é sensível, como revelar identidade, exportar o caso e gerar pacote de evidências.

Concorrência otimista: expected_version​

Várias pessoas (e integrações) podem trabalhar no mesmo caso ao mesmo tempo. Para que ninguém sobrescreva a decisão de outra pessoa sem saber, cada caso tem um número version que aumenta a cada alteração.

Como usar:

  1. Leia o caso (GET /api/v1/requests/demands/{código}) e guarde version.
  2. Envie expected_version com esse número nos comandos que alteram o caso.
  3. Se receber 409 requests_version_conflict, releia o caso, reavalie se a ação ainda faz sentido e só então tente de novo — com um novo request_nonce, já que a intenção foi refeita.
  4. Os comandos que mudam a versão (atribuir, mudar prioridade, mover etapa, anexar) devolvem o novo version; use-o no próximo comando sem precisar reler. Enviar mensagem ou nota não exige expected_version e não devolve version.

Não trate o 409 como erro fatal nem repita cegamente: ele significa "alguém mudou o caso, confira antes".

Códigos públicos e UUIDs​

A maioria dos recursos tem dois identificadores:

Código públicoUUID
Exemplo522U0b9e6f0a-3c1d-4a7e-9f43-1d2c5b6a7e80
Onde apareceTelas, e-mails, campo codeCampo id
Onde usarNo caminho das rotas (/demands/522U)Em filtros e corpos (assignee_id, company_id…)
  • O código tem 4 caracteres de um alfabeto sem ambiguidade: letras maiúsculas sem I e O, e dígitos de 2 a 9 (sem 0 e 1). Isso evita confusões ao ditar ou digitar.
  • Nas rotas que usam código no caminho (casos, empresas, membros, papéis, grupos, chaves, webhooks, arquivos, notificações, fluxos, tipos de solicitação), enviar um valor fora desse formato — inclusive um UUID — responde 400 validation_error. Um código que não existe na sua organização responde 404 not_found.
  • Alguns identificadores secundários no caminho são UUIDs, como o attachment_id de um anexo.
O protocolo do canal é outra coisa

O protocolo que quem relata recebe para acompanhar o caso no canal público não é o código público interno. A equipe e as integrações trabalham com o código; quem relata, com protocolo e chave de acesso.

Limites​

LimiteValorAo ultrapassar
Requisições por chave de API600 por minuto (padrão)429 rate_limited (sem Retry-After)
Tentativas de login8 a cada 15 minutos por e-mail e IP (padrão)429 rate_limited + Retry-After
Itens por página100422 (parâmetro limit inválido)
Busca q200 caracteres422
Mensagem em um caso1 a 4.000 caracteres422
Arquivo anexado a um caso10 MiB; PDF, PNG ou JPEG (detectados pelo conteúdo, não pela extensão)413 requests_upload_too_large / 422 requests_file_type_invalid
Anexos por caso100409 requests_limit_exceeded
Corpo da requisição4 MiB por padrão; algumas rotas têm limite próprio (o upload de anexo aceita até 12 MiB no total)413 request_body_too_large
Corpo comprimido (Content-Encoding)recusado nas rotas com limite próprio, como o upload de anexos415 request_body_encoding_unsupported

Cache​

As rotas de casos respondem com Cache-Control: no-store. Não guarde o conteúdo de casos em caches intermediários, CDNs ou no disco sem necessidade: trate-o como dado sensível e mantenha cópias apenas onde a sua política de privacidade permitir.