> ## 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 Exclusão

> O que pode e o que não pode ser excluído após a emissão de certificados. Entendendo a exclusão lógica e a integridade referencial.

# Regras de Exclusão

O DokStamp é projetado para preservar a integridade dos certificados emitidos. Uma vez que um certificado tenha sido emitido, as entidades que ele referencia são protegidas contra exclusão. Esta página explica as regras e os padrões recomendados para integrações.

***

## Exclusão lógica

Todas as entidades no DokStamp usam **exclusão lógica**: quando você chama `DELETE /resource/{uuid}`, o registro não é removido fisicamente do banco de dados. Em vez disso, um timestamp `deleted_at` é definido. Registros com exclusão lógica:

* São excluídos de todas as respostas de listagem via `GET`
* Não podem ser referenciados por novos recursos
* Retêm todos os seus dados e relacionamentos intactos
* Podem ser restaurados pelo administrador da plataforma, se necessário

Isso significa que **nenhum dado é perdido permanentemente** através da API de exclusão padrão.

***

## Regras de proteção contra exclusão

Tentar excluir uma entidade que possua certificados emitidos dependentes resultará em erro. A proteção é aplicada no nível do banco de dados via restrições de chave estrangeira.

| Entidade        | Não pode ser excluída quando...                                       |
| --------------- | --------------------------------------------------------------------- |
| **Instituição** | Possui cursos, módulos ou certificados que a referenciam              |
| **Curso**       | Possui turmas, matrículas ou certificados que o referenciam           |
| **Módulo**      | Está vinculado a algum curso (relacionamento `course_modules` existe) |
| **Turma**       | Possui matrículas ou certificados que a referenciam                   |
| **Estudante**   | Possui certificados, matrículas ou um snapshot de dados cadastrais    |

***

## Por que isso importa para integrações

Quando o seu sistema de terceiros exclui ou desativa uma entidade, você **não deve espelhar essa exclusão cegamente** no DokStamp se certificados já foram emitidos. A abordagem recomendada:

### 1. Verifique se há certificados antes de excluir

```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;
}

// Exemplo para um curso
if (await canDelete('course', courseUuid)) {
  await api.delete(`/courses/${courseUuid}`);
} else {
  // Arquive em vez de excluir
  await api.patch(`/courses/${courseUuid}`, { status: 'archived' });
}
```

### 2. Arquive em vez de excluir

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

```javascript theme={null}
// Em vez de DELETE /courses/{uuid}
await api.patch(`/courses/${courseUuid}`, { status: 'archived' });
```

Isso preserva todos os relacionamentos enquanto marca claramente a entidade como não mais ativa.

### 3. Trate o erro adequadamente

Se uma tentativa de exclusão falhar devido a uma dependência existente, a API retorna um erro. Sempre trate isso na sua integração:

```javascript theme={null}
try {
  await api.delete(`/courses/${courseUuid}`);
} catch (err) {
  if (err.response?.status === 500) {
    // Provavelmente um erro de integridade referencial — registre e arquive
    logger.warn(`Não é possível excluir o curso ${courseUuid} — possui registros dependentes. Arquivando.`);
    await api.patch(`/courses/${courseUuid}`, { status: 'archived' });
  } else {
    throw err;
  }
}
```

***

## Imutabilidade do certificado

Uma vez que um certificado é emitido, todos os dados associados a ele são preservados:

* Identidade do estudante (nome, email, documento de identificação, data de nascimento, país) — capturada em um snapshot imutável no momento da emissão
* Dados do curso, da instituição, da turma e da matrícula — todos preservados pelas regras de integridade referencial acima

Isso garante que a URL de verificação pública de um certificado sempre exiba informações precisas e completas, independentemente de quaisquer alterações futuras nas entidades subjacentes.

***

## Desvinculação de módulos vs exclusão

Módulos podem ser **desvinculados** de um curso sem serem excluídos:

```http theme={null}
DELETE /courses/{course_uuid}/detach/modules
```

Isso remove a associação `course_modules`, mas deixa tanto o curso quanto o módulo intactos. Esta é a operação preferida ao reorganizar um currículo, pois permite que o módulo seja vinculado novamente a um curso diferente.

A exclusão definitiva de um módulo (via `DELETE /modules/{uuid}`) só é possível após ele ter sido desvinculado de todos os cursos.

***

## Resumo: prefira arquivar em vez de excluir

| Cenário                                | Ação recomendada                                          |
| -------------------------------------- | --------------------------------------------------------- |
| Curso descontinuado                    | `PATCH /courses/{uuid}` → `{ "status": "archived" }`      |
| Instituição inativa                    | `PATCH /institutions/{uuid}` → `{ "status": "inactive" }` |
| Registro de estudante a ser desativado | Não exclua; mantenha o registro intacto                   |
| Módulo que não é mais ministrado       | Desvincule do curso; não exclua o módulo                  |
| Turma encerrada                        | Nenhuma ação necessária; turmas são registros históricos  |