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.
| Tema | Resumo |
|---|---|
| Formato | JSON em UTF-8, datas ISO 8601 em UTC, mensagens em português |
| Listagens | limit, cursor, sort, q, filter → {items, page} |
| Erros | {code, message, request_id} com status HTTP coerente |
| Idempotência | request_nonce nos comandos de casos; Idempotency-Key nas demais rotas |
| Concorrência | expected_version + 409 em caso de conflito |
| Identificadores | Código público de 4 caracteres no caminho, UUID no corpo e nos filtros |
| Limites | Limite 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 usamAAAA-MM-DD. - Campos desconhecidos são recusados nos corpos dos comandos de casos. Isso protege você de erros de digitação silenciosos: um
asignee_iderrado 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 docode, 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âmetro | Padrão | Descrição |
|---|---|---|
limit | 50 | Itens por página, de 1 a 100. |
cursor | — | Valor de page.next_cursor da página anterior. Omita na primeira página. |
sort | depende 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énullna última página.
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
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:
| Operador | Significado | Tipos |
|---|---|---|
eq / neq | igual / diferente | todos |
in | está na lista (até 50 valores) | texto, UUID, inteiro (não vale para datas nem booleanos) |
contains | conté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 lte | maior / maior ou igual / menor / menor ou igual | data e hora, inteiro |
is_null | true = vazio, false = preenchido | campos 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.
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:
| Campo | Tipo | Filtrar | Ordenar | Observações |
|---|---|---|---|---|
id | UUID | sim | sim | |
code | texto | sim | sim | também pesquisado por q |
subject_name | texto | sim | sim | também pesquisado por q |
subject_kind | texto | sim | — | |
subject_id | UUID | sim | — | |
company_id | UUID | sim | — | empresa do caso |
category_id | UUID | sim | — | grupo de categorias (ex.: denúncias) |
request_type_id | UUID | sim | — | categoria/tipo do caso |
request_type_name | texto | sim | sim | |
workflow_id, workflow_version_id | UUID | sim | — | |
stage_key | texto | sim | — | etapa atual (ex.: triage) |
stage_position | inteiro | sim | sim | posição da etapa no fluxo |
phase | texto | sim | sim | pending, in_progress, waiting, closed |
outcome | texto | sim | sim | desfecho de um caso encerrado; nulo enquanto aberto |
queue | texto | sim | — | fila do caso |
priority | texto | sim | sim | normal, high, urgent |
assignee_id | UUID | sim | — | responsável |
unassigned | booleano | sim | — | sem responsável |
awaiting_reply | booleano | sim | — | há mensagem de quem relatou sem resposta da equipe |
reassignment_pending | booleano | sim | — | |
waiting_reason | texto | sim | — | |
channel, origin, client | texto | sim | — | como o caso foi aberto (client = api para casos abertos por chave) |
requested_by | UUID | sim | — | quem abriu |
checklist_total, checklist_done | inteiro | sim | — | |
reminder_pending | booleano | sim | — | |
created_at, updated_at, closed_at | data e hora | sim | sim | |
tag_id | UUID | sim (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"
}
| Campo | Para que serve |
|---|---|
code | Identificador estável do erro. É nele que o seu código deve se basear. |
message | Texto em português para exibir a uma pessoa. Pode ser melhorado com o tempo; não compare strings. |
request_id | Identificador 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
| Status | code | O que fazer |
|---|---|---|
409 | concurrency_conflict | Duas operações disputaram os mesmos dados. Tente de novo após Retry-After (1 s). |
503 | unavailable | Serviço temporariamente indisponível. Tente de novo após Retry-After. |
429 | rate_limited | Limite de taxa. Aguarde Retry-After quando vier; no limite por chave de API o cabeçalho não é enviado, então espere alguns segundos. |
500 | internal_error | Erro 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:
- Gere um UUID novo para cada intenção (cada mensagem, cada atribuição) e guarde-o junto com a intenção antes de enviar.
- 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": truee não executa de novo. - O mesmo nonce com outro conteúdo responde
409 requests_nonce_conflict. - O recibo vale por 7 dias. Depois disso, repetir o nonce responde
409 requests_nonce_expired: consulte o estado atual do caso. - 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 }
Idempotency-Key nas rotas de casosNas 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:
- Leia o caso (
GET /api/v1/requests/demands/{código}) e guardeversion. - Envie
expected_versioncom esse número nos comandos que alteram o caso. - 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 novorequest_nonce, já que a intenção foi refeita. - 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 exigeexpected_versione não devolveversion.
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úblico | UUID | |
|---|---|---|
| Exemplo | 522U | 0b9e6f0a-3c1d-4a7e-9f43-1d2c5b6a7e80 |
| Onde aparece | Telas, e-mails, campo code | Campo id |
| Onde usar | No 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
IeO, e dígitos de2a9(sem0e1). 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 responde404 not_found. - Alguns identificadores secundários no caminho são UUIDs, como o
attachment_idde um anexo.
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
| Limite | Valor | Ao ultrapassar |
|---|---|---|
| Requisições por chave de API | 600 por minuto (padrão) | 429 rate_limited (sem Retry-After) |
| Tentativas de login | 8 a cada 15 minutos por e-mail e IP (padrão) | 429 rate_limited + Retry-After |
| Itens por página | 100 | 422 (parâmetro limit inválido) |
Busca q | 200 caracteres | 422 |
| Mensagem em um caso | 1 a 4.000 caracteres | 422 |
| Arquivo anexado a um caso | 10 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 caso | 100 | 409 requests_limit_exceeded |
| Corpo da requisição | 4 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 anexos | 415 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.