> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dokstamp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Regras de Eliminação

> O que pode e não pode ser eliminado após a emissão de certificados. Compreender a eliminação lógica e a integridade referencial.

# 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

```javascript theme={null}
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:

```javascript theme={null}
// 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:

```javascript theme={null}
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:

```http theme={null}
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 |