Pular para o conteúdo principal

​
Ordem de Cadastro de Entidades

Os certificados no DokStamp vinculam múltiplas entidades — instituição, curso, estudante, arquivo. Cada entidade depende de outras que já existem. Esta página mostra a ordem exata que você deve seguir e quais etapas são opcionais.
Esta é a fonte mais comum de erros de validação 422 em novas integrações. Salve esta página nos favoritos.

​
Mapa de dependências

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

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

File (enviado 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

1

Autenticar

Endpoint: POST /auth/loginObtenha seu access_token e refresh_token. Todas as requisições subsequentes exigem o Bearer token no header Authorization.→ Referência de autenticação
2

Criar uma Instituição

Endpoint: POST /institutionsA 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
3

Criar uma Organização (opcional)

Endpoint: POST /organizationsOrganizações são subdivisões de uma instituição (faculdades, departamentos, campi). Cursos podem ser vinculados a uma organização, mas não é obrigatório.→ Referência de organizações
4

Criar Módulo(s)

Endpoint: POST /modulesMódulos são os blocos de construção dos cursos — disciplinas ou matérias individuais. Crie todos os módulos necessários antes de criar o curso.→ Referência de módulos
5

Criar um Curso

Endpoint: POST /coursesUm curso define o programa de estudos. Requer um institution_uuid. Opcionalmente vinculado a um organization_uuid.→ Referência de cursos
6

Vincular Módulos ao Curso

Endpoint: POST /courses/{course_uuid}/attach/modulesOs módulos não são automaticamente vinculados aos cursos. Você deve vinculá-los explicitamente. Você também pode atribuir módulos a grupos de módulos e definir a ordenação.→ Referência de módulos do curso
7

Criar uma Turma (opcional)

Endpoint: POST /cohortsUma turma é uma entrada ou classe específica (ex: “Turma 2024 — Noturno”). As turmas são vinculadas a um curso. Use turmas quando emitir certificados para classes formandas distintas.→ Referência de turmas
8

Fazer Upload do PDF do Certificado

Endpoint: POST /filesFaça o upload do arquivo PDF do certificado. A resposta retorna um uuid — este é seu file_uuid. Um arquivo só pode ser vinculado a um certificado; ele é marcado como utilizado no momento da vinculação.→ Referência de arquivos
9

Criar um Template de Certificado (opcional)

Endpoint: POST /certificate-templatesTemplates definem o design visual dos certificados (incluindo configuração Canva). São reutilizáveis em muitos certificados. Ignore se você estiver fornecendo PDFs pré-renderizados.→ Referência de templates de certificado
10

Criar um Estudante

Endpoint: POST /studentsEstudantes são independentes de instituições e cursos — eles existem no nível do tenant. Crie (ou localize) o estudante antes de emitir um certificado.→ Referência de estudantes
11

Criar uma Matrícula (opcional)

Endpoint: POST /enrollmentsUma matrícula vincula um estudante a um curso (e opcionalmente a uma turma). Registra a progressão acadêmica, nota e status de conclusão. Informe o enrollment_uuid no certificado para rastreabilidade completa.→ Referência de matrículas
12

Emitir o Certificado

Endpoint: POST /certificatesCombine todas as entidades acima em um certificado. Os campos mínimos obrigatórios são institution_uuid, course_uuid, student_uuid e file_uuid.→ Referência de certificados

​
Resumo rápido

EtapaEndpointObrigatório?Depende de
1POST /auth/loginSim—
2POST /institutionsSimTenant
3POST /organizationsNãoInstitution
4POST /modulesNão*Institution
5POST /coursesSimInstitution
6POST /courses/{id}/attach/modulesNão*Course + Modules
7POST /cohortsNãoCourse
8POST /filesSim—
9POST /certificate-templatesNãoInstitution
10POST /studentsSim—
11POST /enrollmentsNãoStudent + Course
12POST /certificatesSimTodos acima
*Opcional, a menos que você precise de históricos acadêmicos por módulo.

​
Reutilizando entidades existentes

Em produção, você não vai repetir cada etapa para cada certificado. A maioria das entidades é cadastrada uma vez e reutilizada:
  • Institution, Organization, Course, Modules — cadastrados uma vez por atualização do catálogo acadêmico.
  • Students — cadastrados uma vez por pessoa (pesquise antes de criar para evitar duplicatas).
  • Cohorts — cadastradas uma vez por turma formanda.
  • Files — cada certificado precisa de seu próprio upload de arquivo exclusivo.
  • Certificates — um por estudante por evento de credencial.
Use GET /students?where[email]=estudante@email.com para localizar estudantes existentes antes de criar novos.