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
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ção2
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ções3
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ções4
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ódulos5
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 cursos6
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 curso7
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 turmas8
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 arquivos9
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 certificado10
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 estudantes11
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ículas12
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 certificadosResumo rápido
*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.
GET /students?where[email]=estudante@email.com para localizar estudantes existentes antes de criar novos.