> ## 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.

# Ordem de Registo de Entidades

> A sequência correta para registar entidades antes de emitir certificados. Saltar etapas causa erros de validação.

# Ordem de Registo de Entidades

Os certificados no DokStamp associam múltiplas entidades — instituição, curso, estudante, ficheiro. Cada entidade depende de outras que já existem. Esta página mostra a ordem exata a seguir e quais as etapas opcionais.

<Info>
  Esta é a fonte mais comum de erros de validação `422` em novas integrações. Guarde esta página nos favoritos.
</Info>

***

## Mapa de dependências

```
Tenant (raiz — configurado para si)
└── Institution
    ├── Organization (opcional)
    ├── Module(s)
    └── Course
        ├── Course ← Modules (etapa de associação)
        ├── Module Groups (opcional)
        └── Cohort (opcional)

Student (independente da institution)
└── Enrollment → Course + Cohort (opcional)

File (carregado independentemente)

Certificate Template → Institution (opcional)

Certificate
  ├── institution_uuid  ← da Institution
  ├── course_uuid       ← do Course
  ├── student_uuid      ← do Student
  ├── file_uuid         ← do File (não utilizado)
  ├── cohort_uuid       ← do Cohort (opcional)
  ├── enrollment_uuid   ← do Enrollment (opcional)
  └── template_uuid     ← do Certificate Template (opcional)
```

***

## Ordem passo a passo

<Steps>
  <Step title="Autenticar">
    **Endpoint:** `POST /auth/login`

    Obtenha o seu `access_token` e `refresh_token`. Todos os pedidos subsequentes exigem o Bearer token no header `Authorization`.

    → [Referência de autenticação](/pt/api-reference/authentication/login)
  </Step>

  <Step title="Criar uma Instituição">
    **Endpoint:** `POST /institutions`

    A instituição é o órgão emissor. É obrigatória para cursos, módulos, templates de certificado e certificados. Crie-a primeiro.

    → [Referência de instituições](/pt/api-reference/institutions)
  </Step>

  <Step title="Criar uma Organização (opcional)">
    **Endpoint:** `POST /organizations`

    Organizações são subdivisões de uma instituição (faculdades, departamentos, campi). Os cursos podem ser associados a uma organização, mas não é obrigatório.

    → [Referência de organizações](/pt/api-reference/organizations)
  </Step>

  <Step title="Criar Módulo(s)">
    **Endpoint:** `POST /modules`

    Módulos são os blocos de construção dos cursos — disciplinas ou unidades curriculares individuais. Crie todos os módulos necessários antes de criar o curso.

    → [Referência de módulos](/pt/api-reference/modules)
  </Step>

  <Step title="Criar um Curso">
    **Endpoint:** `POST /courses`

    Um curso define o programa de estudos. Requer um `institution_uuid`. Opcionalmente associado a um `organization_uuid`.

    → [Referência de cursos](/pt/api-reference/courses/overview)
  </Step>

  <Step title="Associar Módulos ao Curso">
    **Endpoint:** `POST /courses/{course_uuid}/attach/modules`

    Os módulos não são automaticamente associados aos cursos. É necessário associá-los explicitamente. Também é possível atribuir módulos a grupos de módulos e definir a ordenação.

    → [Referência de módulos do curso](/pt/api-reference/courses/modules)
  </Step>

  <Step title="Criar uma Turma (opcional)">
    **Endpoint:** `POST /cohorts`

    Uma turma é uma entrada ou classe específica (ex: "Turma 2024 — Noturno"). As turmas são associadas a um curso. Utilize turmas quando emitir certificados para classes formandas distintas.

    → [Referência de turmas](/pt/api-reference/courses/cohorts)
  </Step>

  <Step title="Carregar o PDF do Certificado">
    **Endpoint:** `POST /files`

    Carregue o ficheiro PDF do certificado. A resposta devolve um `uuid` — este é o seu `file_uuid`. Um ficheiro só pode ser associado a **um** certificado; é marcado como utilizado no momento da associação.

    → [Referência de ficheiros](/pt/api-reference/files)
  </Step>

  <Step title="Criar um Template de Certificado (opcional)">
    **Endpoint:** `POST /certificate-templates`

    Templates definem o design visual dos certificados (incluindo configuração Canva). São reutilizáveis em muitos certificados. Ignore se estiver a fornecer PDFs pré-renderizados.

    → [Referência de templates de certificado](/pt/api-reference/certificate-templates)
  </Step>

  <Step title="Criar um Estudante">
    **Endpoint:** `POST /students`

    Estudantes são independentes de instituições e cursos — existem ao nível do tenant. Crie (ou localize) o estudante antes de emitir um certificado.

    → [Referência de estudantes](/pt/api-reference/students/overview)
  </Step>

  <Step title="Criar uma Matrícula (opcional)">
    **Endpoint:** `POST /enrollments`

    Uma matrícula associa um estudante a um curso (e opcionalmente a uma turma). Regista a progressão académica, nota e estado de conclusão. Indique o `enrollment_uuid` no certificado para rastreabilidade completa.

    → [Referência de matrículas](/pt/api-reference/enrollments)
  </Step>

  <Step title="Emitir o Certificado">
    **Endpoint:** `POST /certificates`

    Combine todas as entidades acima num certificado. Os campos mínimos obrigatórios são `institution_uuid`, `course_uuid`, `student_uuid` e `file_uuid`.

    → [Referência de certificados](/pt/api-reference/certificates/overview)
  </Step>
</Steps>

***

## Resumo rápido

| Etapa | Endpoint                            | Obrigatório? | Depende de       |
| ----- | ----------------------------------- | ------------ | ---------------- |
| 1     | `POST /auth/login`                  | Sim          | —                |
| 2     | `POST /institutions`                | Sim          | Tenant           |
| 3     | `POST /organizations`               | Não          | Institution      |
| 4     | `POST /modules`                     | Não\*        | Institution      |
| 5     | `POST /courses`                     | Sim          | Institution      |
| 6     | `POST /courses/{id}/attach/modules` | Não\*        | Course + Modules |
| 7     | `POST /cohorts`                     | Não          | Course           |
| 8     | `POST /files`                       | Sim          | —                |
| 9     | `POST /certificate-templates`       | Não          | Institution      |
| 10    | `POST /students`                    | Sim          | —                |
| 11    | `POST /enrollments`                 | Não          | Student + Course |
| 12    | `POST /certificates`                | Sim          | Todos acima      |

<sub>\*Opcional, a menos que necessite de históricos académicos por módulo.</sub>

***

## Reutilizando entidades existentes

Em produção, não será necessário repetir cada etapa para cada certificado. A maioria das entidades é registada uma vez e reutilizada:

* **Institution, Organization, Course, Modules** — registados uma vez por atualização do catálogo académico.
* **Students** — registados uma vez por pessoa (procure antes de criar para evitar duplicados).
* **Cohorts** — registadas uma vez por turma formanda.
* **Files** — cada certificado necessita do seu próprio carregamento de ficheiro exclusivo.
* **Certificates** — um por estudante por evento de credencial.

Utilize `GET /students?where[email]=estudante@email.com` para localizar estudantes existentes antes de criar novos.