Log de Auditoria
O DokStamp registra automaticamente toda operação de escrita em todas as entidades. O log de auditoria fornece um histórico completo e à prova de adulteração de alterações: quem as realizou, quando, de qual IP e URL, e exatamente o que mudou (diffs por campo com valores antigos e novos).
O que é registrado
Cada operação POST, PATCH, PUT, DELETE e de restauração gera uma entrada de auditoria. Os seguintes eventos são registrados:
| Evento | Acionado por |
|---|
created | Uma nova entidade é criada |
updated | Qualquer campo de uma entidade é alterado |
deleted | Uma entidade sofre exclusão lógica |
restored | Uma entidade com exclusão lógica é restaurada |
Estrutura do registro de auditoria
Cada entrada de auditoria captura:
| Campo | Descrição |
|---|
event | created, updated, deleted ou restored |
auditable_type | O modelo que foi alterado (ex: App\Models\Certificate) |
auditable_id | O ID do registro alterado |
user_type + user_id | O usuário autenticado que realizou a alteração |
tenant_id | O tenant no qual a alteração ocorreu |
old_values | JSON object com os valores anteriores dos campos alterados |
new_values | JSON object com os novos valores dos campos alterados |
url | O endpoint da API que foi chamado |
ip_address | Endereço IP do cliente |
user_agent | Identificador do cliente HTTP |
created_at | Timestamp da alteração |
Timestamps (created_at, updated_at) são excluídos intencionalmente dos diffs de auditoria. Apenas alterações de campos significativos aparecem em old_values / new_values.
Exemplos de entradas de auditoria
Certificado emitido
{
"event": "created",
"auditable_type": "App\\Models\\Certificate",
"auditable_id": 142,
"user_id": 3,
"tenant_id": 1,
"old_values": {},
"new_values": {
"status": "issued",
"student_id": 88,
"course_id": 12,
"institution_id": 1,
"issued_at": "2024-12-01 00:00:00"
},
"url": "https://api.dokstamp.eu/certificates",
"ip_address": "203.0.113.42",
"created_at": "2024-12-01T10:15:30Z"
}
Nome do curso alterado
{
"event": "updated",
"auditable_type": "App\\Models\\Course",
"auditable_id": 12,
"user_id": 2,
"tenant_id": 1,
"old_values": {
"name": "Bachelor of Computer Science"
},
"new_values": {
"name": "Bachelor of Computer Science and Engineering"
},
"url": "https://api.dokstamp.eu/courses/c3d4e5f6-a7b8-9012-cdef-123456789012",
"ip_address": "203.0.113.10",
"created_at": "2025-03-15T09:05:00Z"
}
Certificado revogado
{
"event": "updated",
"auditable_type": "App\\Models\\Certificate",
"auditable_id": 142,
"user_id": 1,
"tenant_id": 1,
"old_values": {
"status": "issued",
"revoked_at": null,
"revocation_reason": null
},
"new_values": {
"status": "revoked",
"revoked_at": "2025-06-01 14:22:00",
"revocation_reason": "Issued in error"
},
"url": "https://api.dokstamp.eu/certificates/a1b2c3d4-.../revoke",
"ip_address": "203.0.113.10",
"created_at": "2025-06-01T14:22:05Z"
}
Isolamento por tenant
Os registros de auditoria têm escopo definido por tenant. Os administradores de cada tenant só podem ver as entradas de auditoria dos seus próprios dados. Não há acesso de auditoria entre tenants.
Casos de uso para integrações
Depuração de problemas de sincronização: Se o seu sistema acredita ter enviado uma atualização mas o DokStamp exibe um valor diferente, o log de auditoria mostrará exatamente quando o valor foi alterado e qual usuário/IP causou a mudança.
Conformidade: Para ambientes regulamentados, o log de auditoria fornece evidência de que a emissão e a revogação de certificados seguiram um fluxo de trabalho autorizado.
Detecção de conflitos: Se dois sistemas estiverem gravando no DokStamp simultaneamente e sobrescrevendo as alterações um do outro, o log de auditoria revelará o padrão de conflito por meio da sequência de old_values / new_values.
Rastreamento do histórico do certificado: Cada transição de status pela qual um certificado passa (draft → issued → revoked) é registrada como uma entrada de auditoria separada, fornecendo um histórico completo.
Acessando o log de auditoria
O log de auditoria está atualmente acessível pelo painel administrativo do DokStamp (painel Nova). Ele não está disponível como endpoint público da API.
Para consultar o histórico de auditoria de uma entidade específica, acesse o painel e navegue até a visualização de detalhe da entidade — uma aba Auditoria exibe o histórico completo de alterações daquele registro.
O que NÃO é registrado
- Campos de timestamp (
created_at, updated_at) — estes são campos de sistema excluídos por design
- Campos array/JSON não são comparados individualmente — o valor JSON inteiro é capturado
- Operações de leitura (requisições
GET) — apenas escritas são auditadas
- Jobs de sistema em background (ex: renovação de token, operações internas de cache)
