Regras de Eliminação

O DokStamp foi concebido para preservar a integridade dos certificados emitidos. Após a emissão de um certificado, as entidades que ele referencia ficam protegidas contra eliminação. Esta página explica as regras e os padrões recomendados para integrações.

Eliminação lógica

Todas as entidades no DokStamp utilizam eliminação lógica: ao chamar DELETE /resource/{uuid}, o registo não é fisicamente removido da base de dados. Em vez disso, é definida uma marca temporal deleted_at. Os registos com eliminação lógica:

São excluídos de todas as respostas de listagem GET
Não podem ser referenciados por novos recursos
Mantêm todos os seus dados e relações intactos
Podem ser restaurados pelo administrador da plataforma, se necessário

Isto significa que nenhum dado é permanentemente perdido através da API de eliminação padrão.

Regras de proteção contra eliminação

Tentar eliminar uma entidade que possui certificados emitidos dependentes resultará num erro. A proteção é aplicada ao nível da base de dados através de restrições de chave estrangeira.

Entidade	Não pode ser eliminada quando…
Instituição	Tem cursos, módulos ou certificados que a referenciam
Curso	Tem turmas, matrículas ou certificados que o referenciam
Módulo	Está associado a algum curso (existe a relação `course_modules`)
Turma	Tem matrículas ou certificados que a referenciam
Estudante	Tem certificados, matrículas ou um snapshot do sujeito da credencial

Por que isto é relevante para integrações

Quando o sistema de terceiros elimina ou desativa uma entidade, não deve replicar essa eliminação cegamente no DokStamp se já foram emitidos certificados. A abordagem recomendada:

1. Verificar a existência de certificados antes de eliminar

async function canDelete(entityType, uuid) {
  const certs = await api.get('/certificates', {
    params: { [`where[${entityType}_uuid]`]: uuid, per_page: 1 }
  });
  return certs.data.meta.total === 0;
}

// Example for a course
if (await canDelete('course', courseUuid)) {
  await api.delete(`/courses/${courseUuid}`);
} else {
  // Archive instead of delete
  await api.patch(`/courses/${courseUuid}`, { status: 'archived' });
}

2. Arquivar em vez de eliminar

Para cursos e instituições, prefira atualizar o campo status para archived ou inactive em vez de eliminar:

// Instead of DELETE /courses/{uuid}
await api.patch(`/courses/${courseUuid}`, { status: 'archived' });

Isto preserva todas as relações e marca claramente a entidade como inativa.

3. Tratar o erro de forma elegante

Se uma tentativa de eliminação falhar por existir uma dependência, a API devolve um erro. Trate sempre esta situação na sua integração:

try {
  await api.delete(`/courses/${courseUuid}`);
} catch (err) {
  if (err.response?.status === 500) {
    // Likely a referential integrity error — log and archive instead
    logger.warn(`Cannot delete course ${courseUuid} — has dependent records. Archiving instead.`);
    await api.patch(`/courses/${courseUuid}`, { status: 'archived' });
  } else {
    throw err;
  }
}

Imutabilidade do certificado

Após a emissão de um certificado, todos os dados a ele associados são preservados:

Identidade do estudante (nome, email, número de documento, data de nascimento, país) — capturada num snapshot imutável no momento da emissão
Dados do curso, instituição, turma e matrícula — todos preservados através das regras de integridade referencial descritas acima

Isto garante que o URL de verificação pública de um certificado apresentará sempre informação precisa e completa, independentemente de quaisquer alterações futuras às entidades subjacentes.

Desassociação de módulos vs eliminação

Os módulos podem ser desassociados de um curso sem serem eliminados:

DELETE /courses/{course_uuid}/detach/modules

Isto remove a associação course_modules, mas mantém tanto o curso como o módulo intactos. Esta é a operação preferida quando se reorganiza um currículo, pois permite que o módulo seja re-associado a um curso diferente. Eliminar um módulo por completo (via DELETE /modules/{uuid}) só é possível após ter sido desassociado de todos os cursos.

Resumo: preferir arquivar em vez de eliminar

Cenário	Ação recomendada
Curso descontinuado	`PATCH /courses/{uuid}` → `{ "status": "archived" }`
Instituição inativa	`PATCH /institutions/{uuid}` → `{ "status": "inactive" }`
Registo de estudante a desativar	Não eliminar; manter o registo intacto
Módulo já não lecionado	Desassociar do curso; não eliminar o módulo
Turma encerrada	Nenhuma ação necessária; as turmas são registos históricos

Primeiros Passos

Conceitos Fundamentais

Autenticação

Instituições

Organizações

Cursos

Módulos

Estudantes

Matrículas

Certificados

Modelos de Certificado

Ficheiros

Guias

Guia de Integração

Regras de Eliminação

Regras de Eliminação

Eliminação lógica

Regras de proteção contra eliminação

Por que isto é relevante para integrações

1. Verificar a existência de certificados antes de eliminar

2. Arquivar em vez de eliminar

3. Tratar o erro de forma elegante

Imutabilidade do certificado

Desassociação de módulos vs eliminação

Resumo: preferir arquivar em vez de eliminar

​Regras de Eliminação

​Eliminação lógica

​Regras de proteção contra eliminação

​Por que isto é relevante para integrações

​1. Verificar a existência de certificados antes de eliminar

​2. Arquivar em vez de eliminar

​3. Tratar o erro de forma elegante

​Imutabilidade do certificado

​Desassociação de módulos vs eliminação

​Resumo: preferir arquivar em vez de eliminar

Regras de Eliminação

Eliminação lógica

Regras de proteção contra eliminação

Por que isto é relevante para integrações

1. Verificar a existência de certificados antes de eliminar

2. Arquivar em vez de eliminar

3. Tratar o erro de forma elegante

Imutabilidade do certificado

Desassociação de módulos vs eliminação

Resumo: preferir arquivar em vez de eliminar