Pular para o conteúdo principal

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:

PassoPermissão
Descobrir categoriasreporting.channels.read
Listar e ler casos, ver transições e mensagens públicasrequests.demands.read
Ler notas internasrequests.messages.internal_read
Responder a quem relatourequests.messages.send
Registrar nota internarequests.messages.internal_write
Atribuir responsávelrequests.demands.assign
Mudar prioridaderequests.demands.triage
Mover de etapaa 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 / baixarrequests.demands.read / requests.attachments.read (anexos internos exigem também requests.messages.internal_read)
Enviar anexorequests.attachments.manage
Histórico protegidorequests.history.read

Nos exemplos, $TRUST_API_KEY contém o segredo da chave e API=https://api.trust.nearone.com.br.

Lembretes que valem para toda a receita
  • No caminho, use o código público do caso (522U); em corpos e filtros, use UUIDs.
  • Todo comando leva um request_nonce novo (UUID) e, se altera o caso, o expected_version atual. 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ãoFiltro 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>"
Caixa de denúncias do backoffice com a lista de casos, filtros por situação e atalhos de atenção.
A Caixa de denúncias usa esta mesma listagem com filtros. Repare nos casos marcados como Protegida: uma pessoa com acesso nominal os vê, mas uma chave de API não os recebe na listagem. Dados fictícios da organização de demonstração.

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.

Leituras deixam rastro

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": []
}
]
}
  • reason diz se a ação pede um motivo: none (não exige), internal (motivo obrigatório, visível só para a equipe) ou public (motivo obrigatório, que também aparece para quem relatou).
  • required_fields lista campos que precisam ser preenchidos na própria ação.
  • impediments explica 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.

Gestão completa de um caso no backoffice com a aba Conversa e notas aberta, mostrando uma nota registrada pela equipe.
Na aba Conversa e notas, a equipe responde a quem relatou e registra notas internas. A API faz a mesma distinção pelo campo visibility (public ou internal). Dados fictícios da organização de demonstração.

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.

Cuidado com o que você escreve

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:

  • body com 1 a 4.000 caracteres;
  • visibility public exige requests.messages.send; internal exige requests.messages.internal_write;
  • corrects_id (opcional) permite publicar uma correção de uma mensagem sua (da mesma chave), com a mesma visibilidade;
  • uma mensagem public só é aceita em casos que quem relatou acompanha (visible_to_beneficiary: true no detalhe); caso contrário, a resposta é 422 requests_validation_error;
  • a resposta é 201 e não traz version: mensagens não exigem expected_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": null retira 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 lista assignee-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-transitions devolve {"items": []} para uma chave de API;
  • POST …/transitions responde 409 requests_transition_invalid.
Por que a etapa fica com as pessoas

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.

RespostaSignificadoO que fazer
409 requests_version_conflictO caso mudou desde a sua leituraReleia, reavalie, repita com novo nonce
409 requests_transition_invalidA ação não existe na etapa atual, o caso está encerrado ou a ação não está liberada para chaves de APIConsulte available-transitions de novo
403 permission_deniedA credencial não tem a permissão exigida pela açãoAjuste as permissões da chave
409 requests_requirements_pendingHá dados, atividades ou decisões obrigatórias pendentesVeja impediments e required_fields
422 requests_validation_errorMotivo ausente ou campo inválidoCorrija conforme problems
Decisões que continuam humanas

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; exige requests.messages.internal_write) ou public (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_exceeded acima disso).
  • Caso encerrado não recebe anexos (409 requests_transition_invalid).
  • A listagem só mostra anexos internos para quem tem requests.messages.internal_read.
Gestão completa de um caso no backoffice com a aba Arquivos aberta, ainda sem anexos: mensagem Nenhum arquivo anexado.
A aba Arquivos do caso, aqui ainda vazia. Os anexos enviados pela API aparecem nela, com a mesma separação entre arquivos internos e visíveis a quem relatou. Dados fictícios da organização de demonstração.

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:

  1. Guarde o nonce antes de enviar cada comando; em caso de falha de rede, reenvie com o mesmo nonce.
  2. Trate 409 requests_version_conflict como sinal para reler, não como erro fatal.
  3. Respeite Retry-After em 429 e 503.
  4. Registre o request_id de cada erro nos seus logs.

Referência dos endpoints usados​

AçãoEndpointReferência
CategoriasGET /api/v1/reporting/categoriesList Categories
Listar casosGET /api/v1/requests/demandsList Demands
Ler casoGET /api/v1/requests/demands/{código}Get Demand
Ações disponíveisGET …/available-transitionsAvailable Transitions
MensagensGET e POST …/messagesList Messages · Post Message
CandidatosGET …/assignee-candidatesAssignee Candidates
AtribuirPOST …/assignmentsAssign Demand
PrioridadePOST …/triageTriage Demand
Mover etapaPOST …/transitionsTransition Demand
AnexosGET/POST …/attachments, GET …/download, POST …/removeList · Upload · Download · Remove
HistóricoGET …/historyHistory