Pular para o conteúdo principal

​
Guia de Integração

Este guia é voltado para desenvolvedores que estão integrando um sistema acadêmico existente — um ERP, Sistema de Informações do Estudante (SIS) ou LMS — com a API do DokStamp. Ele cobre o ciclo de vida completo da integração: configuração inicial, sincronização contínua de entidades, regras de exclusão e a trilha de auditoria.

Sincronizando a Estrutura Acadêmica

Como sincronizar cursos, módulos, turmas e estudantes do seu sistema para o DokStamp.

Regras de Exclusão

O que pode e o que não pode ser excluído após a emissão de certificados.

Log de Auditoria

Toda alteração é registrada — quem mudou o quê, quando e de onde.

Ordem de Registro de Entidades

O grafo de dependências que todas as integrações devem seguir.

​
Cenário típico de integração

Sistema de terceiros (ERP/SIS)               DokStamp API
        │                                         │
        │  Novo curso criado                      │
        │ ────────────────────────►│ POST /courses
        │                                         │
        │  Módulo adicionado ao curso             │
        │ ────────────────────────►│ POST /modules
        │                                         │  POST /courses/{id}/attach/modules
        │                                         │
        │  Nova turma (classe formanda)           │
        │ ────────────────────────►│ POST /cohorts
        │                                         │
        │  Estudante torna-se elegível            │
        │ ────────────────────────►│ GET /students?where[email]=...
        │                                         │  POST /students (se não encontrado)
        │                                         │  POST /enrollments
        │                                         │
        │  Emissão de certificado acionada        │
        │ ────────────────────────►│ POST /files
        │                                         │  POST /certificates

​
Antes de começar

A configuração da instituição é obrigatória primeiro. A instituição é a entidade raiz — todos os cursos, módulos e certificados dependem dela. Ela pode ser criada via:
  • O painel do DokStamp (configuração manual, feita uma única vez)
  • A API: POST /institutions
Uma vez que a instituição exista, toda a sincronização subsequente de entidades pode ser feita de forma programática.

​
Modos de integração

​
Síncrono (em tempo real)

Seu sistema chama a API do DokStamp diretamente quando uma entidade muda. Simples de implementar, funciona bem para cenários de baixo volume. 
Ação do usuário no ERP → Chamada de API ao DokStamp → Resposta tratada imediatamente

​
Assíncrono (baseado em queue)

Seu sistema enfileira um job sempre que uma entidade muda. Um worker em background processa a queue e chama a API do DokStamp. Recomendado para integrações de alto volume ou quando a disponibilidade do DokStamp não deve afetar o desempenho do seu sistema. 
Ação do usuário no ERP → Job enfileirado → Worker chama a API do DokStamp → Retry em caso de falha
Estratégia de retry: Use backoff exponencial. Faça retry em HTTP 429 (rate limit) e 5xx (erros de servidor). Não faça retry em 4xx (erros do cliente — estes indicam um problema de dados ou autenticação que precisa ser investigado).

​
Idempotência: buscar antes de criar

O DokStamp não expõe chaves de idempotência. O padrão recomendado é buscar uma entidade antes de criá-la para evitar duplicatas. 
// Antes de criar um estudante, verifique se ele já existe
const existing = await api.get('/students', {
  params: { 'where[email]': student.email }
});

const studentUuid = existing.data.length > 0
  ? existing.data[0].uuid
  : (await api.post('/students', student)).data.uuid;
Aplique o mesmo padrão para cursos (por code), turmas (por code) e módulos (por code + institution_uuid).