Registo de Auditoria
O DokStamp regista automaticamente todas as operações de escrita em todas as entidades. O registo de auditoria fornece um histórico completo e à prova de adulteração das alterações: quem as efetuou, quando, a partir de que endereço IP e URL, e exatamente o que mudou (diferenças ao nível do campo com os valores antigos e novos).
O que é registado
Cada operação POST, PATCH, PUT, DELETE e de restauro desencadeia uma entrada de auditoria. Os seguintes eventos são registados:
| Evento | Desencadeado por |
|---|
created | Uma nova entidade é criada |
updated | Qualquer campo de uma entidade é alterado |
deleted | Uma entidade é eliminada logicamente |
restored | Uma entidade com eliminação lógica é restaurada |
Estrutura de um registo 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 registo alterado |
user_type + user_id | O utilizador autenticado que efetuou a alteração |
tenant_id | O tenant em que a alteração ocorreu |
old_values | Objeto JSON com os valores anteriores dos campos alterados |
new_values | Objeto JSON 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 | Marca temporal da alteração |
As marcas temporais (created_at, updated_at) são intencionalmente excluídas das diferenças de auditoria. Apenas alterações de campos com significado 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 registos de auditoria estão limitados ao tenant. Os administradores de cada tenant só podem consultar as entradas de auditoria dos seus próprios dados. Não existe acesso cruzado entre tenants.
Casos de uso para integrações
Depuração de problemas de sincronização: Se o sistema enviou uma atualização mas o DokStamp apresenta um valor diferente, o registo de auditoria mostrará exatamente quando o valor foi alterado e qual o utilizador/IP responsável.
Conformidade: Em ambientes regulados, o registo de auditoria fornece evidência de que a emissão e revogação de certificados seguiram um fluxo de trabalho autorizado.
Deteção de conflitos: Se dois sistemas estiverem a escrever no DokStamp em simultâneo e a sobrescrever as alterações um do outro, o registo de auditoria revelará o padrão de conflito através da sequência de old_values / new_values.
Rastreio do historial de um certificado: Cada transição de estado de um certificado (draft → issued → revoked) é registada como uma entrada de auditoria separada, fornecendo um historial completo.
Aceder ao registo de auditoria
O registo de auditoria está atualmente acessível através do painel de administração do DokStamp (painel Nova). Não está disponível como endpoint público da API.
Para consultar o historial de auditoria de uma entidade específica, aceda ao painel e navegue até à vista de detalhe da entidade — um separador Auditoria apresenta o histórico completo de alterações para esse registo.
O que NÃO é registado
- Campos de marca temporal (
created_at, updated_at) — são campos de sistema excluídos por definição
- Os campos de array/JSON não são individualmente comparados — o valor JSON completo é capturado
- Operações de leitura (pedidos
GET) — apenas as escritas são auditadas
- Trabalhos internos do sistema em segundo plano (ex.: atualização de tokens, operações internas de cache)
