Auditoria e rastreabilidade

A auditoria registra ações relevantes no contexto da organização. Ela ajuda a identificar o tipo de ator, o recurso envolvido e a requisição que originou o evento.

Consultar eventos

No backoffice, a trilha fica em Operação › Auditoria. Pela API, GET /api/v1/audit/events exige audit.events.read e usa o padrão de paginação e filtros. A listagem está limitada à organização do contexto.

Os campos incluem actor_type, actor_identity_id, actor_api_key_id, action, resource_type, resource_id, metadata, request_id e created_at.

curl --get "$COBRES_API_URL/api/v1/audit/events" \
  -H "Authorization: Bearer $COBRES_API_KEY" \
  --data-urlencode 'limit=50' \
  --data-urlencode 'sort=-created_at' \
  --data-urlencode 'filter={"actor_type":"api_key"}'

A chave usada no exemplo precisa possuir a permissão de leitura de auditoria. Conceda-a apenas a consumidores que necessitam dessa trilha.

Correlacionar uma falha

Guarde o horário, o método, o caminho sem dados sensíveis, o status e o X-Request-ID. Quando a API retorna um erro de aplicação, o corpo também traz request_id.

O identificador permite correlacionar o erro com a aplicação e com eventos de auditoria. Se houve uma falha antes da escrita ou antes da emissão de um evento, pode não existir uma linha de auditoria para aquela tentativa. Ausência de evento não deve ser interpretada isoladamente como falha de segurança.

Trilhas diferentes

A auditoria registra a ação de aplicação. A linha do tempo da dívida mostra fatos operacionais de cobrança. O histórico de entregas mostra tentativas de um webhook. O financeiro mantém seus estados, aprovações e evidências. Combine as fontes conforme a pergunta investigada.

Uma alteração de negócio pode produzir mais de um registro, e não existe a promessa de uma linha de auditoria por clique de interface.

Cuidados com exportação

Os metadados podem conter informações do recurso. Trate uma exportação de auditoria como dado da organização: limite quem recebe, preserve a finalidade e evite copiar registros completos para canais públicos de suporte.

O produto não declara aqui cadeia criptográfica de auditoria nem retenção universal. Prazos de guarda, evidências e procedimentos internos devem ser confirmados com os responsáveis pela operação.