Casos via API: receita completa
Esta receita mostra, passo a passo, como uma integração acompanha e opera casos do canal de denúncias com uma chave de API — as mesmas ações que a equipe faz no backoffice em Caixa de denúncias e Abrir gestão completa.
Antes de começar
Emita uma chave de API (veja Primeiros passos) com as permissões de cada passo que você vai usar:
| Passo | Permissão |
|---|---|
| Descobrir categorias | reporting.channels.read |
| Listar e ler casos, ver transições e mensagens públicas | requests.demands.read |
| Ler notas internas | requests.messages.internal_read |
| Responder a quem relatou | requests.messages.send |
| Registrar nota interna | requests.messages.internal_write |
| Atribuir responsável | requests.demands.assign |
| Mudar prioridade | requests.demands.triage |
| Mover de etapa | a permissão exigida pela ação no fluxo (normalmente requests.demands.transition) — e a ação precisa estar liberada para integrações (veja o passo 6) |
| Listar anexos / baixar | requests.demands.read / requests.attachments.read (anexos internos exigem também requests.messages.internal_read) |
| Enviar anexo | requests.attachments.manage |
| Histórico protegido | requests.history.read |
Nos exemplos, $TRUST_API_KEY contém o segredo da chave e API=https://api.trust.nearone.com.br.
- No caminho, use o código público do caso (
522U); em corpos e filtros, use UUIDs. - Todo comando leva um
request_noncenovo (UUID) e, se altera o caso, oexpected_versionatual. Veja Convenções. - Casos da fila restrita (protegidos) não são visíveis para chaves de API. Eles só aparecem para as pessoas com acesso nominal. No catálogo padrão, isso vale para a maioria das categorias de denúncia (assédio, discriminação, violência ou ameaça, retaliação, assédio eleitoral, fraude, conflito de interesses e "Outro assunto").
- A chave enxerga todas as empresas da organização (não há recorte por empresa para chaves).
1. Descubra a categoria "Denúncias"
O catálogo separa os casos em grupos — por exemplo, denúncias e ouvidoria. Para filtrar só denúncias, pegue o group_id do grupo cuja group_key é denuncias:
curl -sS "$API/api/v1/reporting/categories" \
-H "Authorization: Bearer $TRUST_API_KEY"
{
"items": [
{
"group_key": "denuncias",
"group_name": "Denúncias",
"group_id": "7d1f2c3b-0a9e-4b8d-8c6f-5e4d3c2b1a00",
"request_type_id": "c0ffee00-1111-4a2b-9c3d-222233334444",
"key": "conduta_antietica",
"name": "Violação do código de conduta",
"description": "…",
"protection": "sensitive",
"workflow_key": "denuncia_geral",
"workflow_name": "…",
"enabled": true,
"version": 2,
"ordinal": 9,
"channels": 1
}
]
}
Cada item é uma categoria; todas as do mesmo grupo compartilham o group_id. O campo protection indica o tratamento: categorias restricted geram casos protegidos (fila restrita).
2. Liste os casos abertos
Use o group_id como category_id no filtro:
curl -sS -G "$API/api/v1/requests/demands" \
-H "Authorization: Bearer $TRUST_API_KEY" \
--data-urlencode 'sort=-created_at' \
--data-urlencode 'limit=50' \
--data-urlencode 'filter={"category_id":"7d1f2c3b-0a9e-4b8d-8c6f-5e4d3c2b1a00","phase":{"neq":"closed"}}'
Filtros úteis. As quatro primeiras linhas correspondem aos cartões do topo da Caixa de denúncias (Em andamento, Novas mensagens, Sem responsável e Encerradas); as demais são recortes que você monta à vontade:
| Visão | Filtro adicional |
|---|---|
| Em andamento | "phase": {"neq": "closed"} |
| Encerradas | "phase": "closed" |
| Novas mensagens de quem relatou | "awaiting_reply": true |
| Sem responsável | "unassigned": true |
| Urgentes | "priority": "urgent" |
| De uma empresa | "company_id": "<UUID da empresa>" |
| De uma categoria específica | "request_type_id": "<UUID>" |

Para percorrer todas as páginas, siga page.next_cursor (exemplo em Paginação por cursor).
3. Leia um caso
curl -sS "$API/api/v1/requests/demands/522U" \
-H "Authorization: Bearer $TRUST_API_KEY"
Resposta (trecho):
{
"id": "0b9e6f0a-3c1d-4a7e-9f43-1d2c5b6a7e80",
"code": "522U",
"request_type": { "id": "c0ffee00-…", "key": "conduta_antietica", "name": "Violação do código de conduta" },
"stage": {
"key": "triage",
"label": "Triagem",
"phase": "in_progress",
"outcome": null
},
"queue": "general",
"priority": "normal",
"assignee": null,
"visible_to_beneficiary": true,
"version": 7,
"public_version": 4,
"created_at": "2026-11-10T14:02:11.418+00:00",
"values": [ "…" ],
"activities": [ "…" ],
"tags": []
}
Guarde o version (aqui, 7): ele será o expected_version dos próximos comandos.
Cada leitura do detalhe de um caso do canal de denúncias grava uma linha no log de acesso do caso, identificando a chave. Evite ler o detalhe em laço: use a listagem para monitorar e leia o detalhe só quando precisar.
O que fazer em seguida?
Pergunte à API quais ações de etapa estão disponíveis para esta credencial, nesta etapa. A lista já vem filtrada: só aparecem ações cuja permissão a credencial tem e que estão liberadas para ela (veja o passo 6 — para chaves de API, a lista costuma vir vazia nos fluxos de denúncia padrão):
curl -sS "$API/api/v1/requests/demands/522U/available-transitions" \
-H "Authorization: Bearer $TRUST_API_KEY"
Exemplo de resposta para uma credencial que pode agir na etapa Triagem do fluxo geral de denúncias:
{
"items": [
{
"transition_key": "to_investigation",
"action": "analyze",
"label": "Abrir apuração",
"to_stage": "investigation",
"to_stage_label": "Apuração",
"to_phase": "in_progress",
"outcome": null,
"reason": "none",
"required_fields": [],
"consequences": [],
"impediments": []
},
{
"transition_key": "ask_triage",
"action": "ask_requester",
"label": "Pedir complemento",
"to_stage": "waiting_manifestant",
"to_stage_label": "Aguardando complemento",
"to_phase": "waiting",
"reason": "public",
"required_fields": [],
"impediments": []
}
]
}
reasondiz se a ação pede um motivo:none(não exige),internal(motivo obrigatório, visível só para a equipe) oupublic(motivo obrigatório, que também aparece para quem relatou).required_fieldslista campos que precisam ser preenchidos na própria ação.impedimentsexplica por que a ação ainda não pode ser feita (por exemplo, dados obrigatórios pendentes).
4. Conversa e notas internas
Ler a conversa
curl -sS "$API/api/v1/requests/demands/522U/messages" \
-H "Authorization: Bearer $TRUST_API_KEY"
{
"items": [
{
"id": "aa11…",
"seq": 1,
"public_seq": 1,
"visibility": "public",
"kind": "…",
"body": "Gostaria de complementar o relato…",
"author_type": "manifestant",
"author_name": null,
"created_at": "2026-11-11T09:15:00+00:00"
}
]
}
author_type indica quem escreveu: manifestant (quem relatou — sem identificador, para preservar o anonimato), identity (uma pessoa da equipe, com author_id e author_name), api_key (uma integração, com author_id e sem nome) ou system (mensagens automáticas). Mensagens internal (notas da equipe) só aparecem se a chave tiver requests.messages.internal_read. Quem relatou nunca vê notas internas.

Responder a quem relatou
curl -sS -X POST "$API/api/v1/requests/demands/522U/messages" \
-H "Authorization: Bearer $TRUST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_nonce": "5f0c8a52-7f1e-4f61-9a43-0d9d3b0f2e11",
"visibility": "public",
"body": "Recebemos seu relato e iniciamos a análise. Se puder, informe a data aproximada do ocorrido."
}'
{ "id": "3e9d7c1a-…", "demand_id": "0b9e6f0a-…", "result": "created", "replayed": false }
A mensagem aparece para quem relatou quando essa pessoa acompanhar o caso no canal, com protocolo e chave de acesso.
Mensagens públicas são lidas por quem relatou. Nunca inclua nomes de pessoas envolvidas, dados de outras denúncias ou conclusões preliminares. Em caso de dúvida, registre uma nota interna.
Registrar uma nota interna
Mesma rota, com "visibility": "internal":
{
"request_nonce": "a8c3e2b1-6d4f-4e5a-9b7c-1d2e3f4a5b6c",
"visibility": "internal",
"body": "Solicitados os registros de acesso ao sistema financeiro do período."
}
Regras da mensagem:
bodycom 1 a 4.000 caracteres;visibilitypublicexigerequests.messages.send;internalexigerequests.messages.internal_write;corrects_id(opcional) permite publicar uma correção de uma mensagem sua (da mesma chave), com a mesma visibilidade;- uma mensagem
publicsó é aceita em casos que quem relatou acompanha (visible_to_beneficiary: trueno detalhe); caso contrário, a resposta é422 requests_validation_error; - a resposta é
201e não trazversion: mensagens não exigemexpected_version.
5. Atribua um responsável
Veja quem pode assumir o caso:
curl -sS "$API/api/v1/requests/demands/522U/assignee-candidates" \
-H "Authorization: Bearer $TRUST_API_KEY"
{
"items": [
{ "identity_id": "4f5e6d7c-…", "name": "Ana Souza", "is_current": false },
{ "identity_id": "9a8b7c6d-…", "name": "Bruno Lima", "is_current": false }
]
}
Atribua usando o identity_id e a version lida no passo 3:
curl -sS -X POST "$API/api/v1/requests/demands/522U/assignments" \
-H "Authorization: Bearer $TRUST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_nonce": "0e1d2c3b-4a59-4687-9a0b-1c2d3e4f5a6b",
"expected_version": 7,
"assignee_id": "4f5e6d7c-…",
"reason": "Distribuição automática pelo sistema de RH"
}'
{ "id": "0b9e6f0a-…", "version": 8, "result": "assigned", "replayed": false }
"assignee_id": nullretira o responsável.reasoné opcional (até 500 caracteres) e fica no histórico.- Uma pessoa que não pode assumir o caso — por exemplo, por estar impedida por conflito de interesse — gera
422 requests_assignee_ineligible. Prefira sempre alguém da listaassignee-candidates. - Caso já encerrado não recebe atribuição (
422 requests_validation_error).
Mudar a prioridade
Com requests.demands.triage, use POST /api/v1/requests/demands/{código}/triage:
{
"request_nonce": "7c6b5a49-3827-4165-9a0b-c1d2e3f4a5b6",
"expected_version": 8,
"priority": "urgent",
"priority_reason": "Relato menciona risco imediato à integridade física."
}
priority aceita normal, high ou urgent; priority_reason é opcional (até 500 caracteres). A resposta traz o novo version. Se você fizer a triagem depois da atribuição, use no passo seguinte o version que ela devolveu.
6. Mova o caso de etapa
Mudar a etapa de uma denúncia (abrir apuração, pedir complemento, encerrar) é a decisão mais sensível do tratamento. Por isso, além da permissão da ação, cada ação do fluxo precisa estar liberada para integrações na definição do fluxo (allow_api_key). Essa opção não aparece no editor visual de fluxos e vem desligada em todas as ações dos fluxos de denúncia e de ouvidoria que acompanham o NearOne Trust.
Na prática, com os fluxos padrão:
GET …/available-transitionsdevolve{"items": []}para uma chave de API;POST …/transitionsresponde409 requests_transition_invalid.
Encerrar uma denúncia como procedente ou improcedente depende de uma análise registrada por uma pessoa, e pedir complemento envia uma mensagem a quem relatou. Manter essas decisões no backoffice garante que cada mudança de etapa tenha um responsável identificado no histórico do caso. A integração acelera o resto: lê, conversa, atribui, prioriza e anexa.
Quando a ação está liberada
Se a sua organização publicar um fluxo em que uma ação está liberada para integrações, a chamada é esta. Escolha uma transition_key da lista available-transitions e envie a version mais recente:
curl -sS -X POST "$API/api/v1/requests/demands/522U/transitions" \
-H "Authorization: Bearer $TRUST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_nonce": "6b5a4f3e-2d1c-40b9-8a7f-6e5d4c3b2a19",
"expected_version": 8,
"transition_key": "to_investigation",
"inputs": {}
}'
{ "id": "0b9e6f0a-…", "version": 9, "result": "transitioned", "replayed": false }
Quando a ação exige motivo (reason igual a public ou internal na lista de ações), envie-o em inputs.reason (até 2.000 caracteres). Campos exigidos pela ação vão em inputs.fields.
| Resposta | Significado | O que fazer |
|---|---|---|
409 requests_version_conflict | O caso mudou desde a sua leitura | Releia, reavalie, repita com novo nonce |
409 requests_transition_invalid | A ação não existe na etapa atual, o caso está encerrado ou a ação não está liberada para chaves de API | Consulte available-transitions de novo |
403 permission_denied | A credencial não tem a permissão exigida pela ação | Ajuste as permissões da chave |
409 requests_requirements_pending | Há dados, atividades ou decisões obrigatórias pendentes | Veja impediments e required_fields |
422 requests_validation_error | Motivo ausente ou campo inválido | Corrija conforme problems |
Além da mudança de etapa nos fluxos padrão, algumas ações são sempre reservadas a pessoas e respondem 403 para chaves de API: revelar a identidade de quem relatou, exportar o caso, salvar a análise, prorrogar prazo, expurgar por retenção, proteger um caso e conceder acesso nominal a casos protegidos.
7. Anexos
Listar
curl -sS "$API/api/v1/requests/demands/522U/attachments" \
-H "Authorization: Bearer $TRUST_API_KEY"
{
"items": [
{
"id": "e7d6c5b4-…",
"file_name": "comprovante.pdf",
"mime": "application/pdf",
"size_bytes": 184233,
"target": "demand",
"visibility": "public",
"state": "attached",
"uploaded_by_type": "manifestant",
"uploaded_by_name": null,
"created_at": "2026-11-10T14:02:30+00:00",
"removed_at": null,
"removal_reason": null
}
]
}
Baixar
curl -sS -OJ "$API/api/v1/requests/demands/522U/attachments/e7d6c5b4-…/download" \
-H "Authorization: Bearer $TRUST_API_KEY"
A resposta são os bytes do arquivo, com Content-Disposition: attachment e Cache-Control: no-store. Arquivos enviados pelo canal público passam por verificação antivírus; enquanto a verificação não termina (ou se o arquivo foi recusado), o download responde 409 requests_attachment_quarantined. Tente de novo mais tarde.
Enviar
Envie multipart/form-data com um arquivo no campo file e o request_nonce:
curl -sS -X POST "$API/api/v1/requests/demands/522U/attachments" \
-H "Authorization: Bearer $TRUST_API_KEY" \
-F "file=@relatorio-auditoria.pdf" \
--form-string "request_nonce=1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" \
--form-string "visibility=internal"
{
"id": "f0e1d2c3-…",
"demand_id": "0b9e6f0a-…",
"version": 10,
"result": "stored",
"replayed": false
}
visibility:internal(padrão, só a equipe; exigerequests.messages.internal_write) oupublic(quem relatou também vê; só em casos que quem relatou acompanha).- Formatos aceitos: PDF, PNG e JPEG, até 10 MiB. O tipo é detectado pelo conteúdo, não pela extensão nem pelo cabeçalho.
- Até 100 anexos por caso (
409 requests_limit_exceededacima disso). - Caso encerrado não recebe anexos (
409 requests_transition_invalid). - A listagem só mostra anexos internos para quem tem
requests.messages.internal_read.

Para retirar um anexo, use POST /api/v1/requests/demands/{código}/attachments/{attachment_id}/remove com request_nonce, expected_version e reason. O arquivo sai da conversa, mas a retirada fica registrada.
8. Histórico
Com requests.history.read, a integração lê a linha do tempo protegida do caso (mudanças de etapa, atribuições, campos, anexos):
curl -sS "$API/api/v1/requests/demands/522U/history" \
-H "Authorization: Bearer $TRUST_API_KEY"
Juntando tudo: reagir a novos casos
Em vez de consultar a listagem a cada minuto, assine um webhook. Um fluxo típico:
Boas práticas para esse fluxo:
- Guarde o nonce antes de enviar cada comando; em caso de falha de rede, reenvie com o mesmo nonce.
- Trate
409 requests_version_conflictcomo sinal para reler, não como erro fatal. - Respeite
Retry-Afterem429e503. - Registre o
request_idde cada erro nos seus logs.
Referência dos endpoints usados
| Ação | Endpoint | Referência |
|---|---|---|
| Categorias | GET /api/v1/reporting/categories | List Categories |
| Listar casos | GET /api/v1/requests/demands | List Demands |
| Ler caso | GET /api/v1/requests/demands/{código} | Get Demand |
| Ações disponíveis | GET …/available-transitions | Available Transitions |
| Mensagens | GET e POST …/messages | List Messages · Post Message |
| Candidatos | GET …/assignee-candidates | Assignee Candidates |
| Atribuir | POST …/assignments | Assign Demand |
| Prioridade | POST …/triage | Triage Demand |
| Mover etapa | POST …/transitions | Transition Demand |
| Anexos | GET/POST …/attachments, GET …/download, POST …/remove | List · Upload · Download · Remove |
| Histórico | GET …/history | History |