Saltar para o conteúdo principal

​
Guia de Integração

Este guia destina-se a programadores que integram um sistema académico existente — um ERP, Sistema de Informação de Estudantes (SIS) ou LMS — com a API do DokStamp. Abrange o ciclo de vida completo da integração: configuração inicial, sincronização contínua de entidades, regras de eliminação e o registo de auditoria.

Sincronização da Estrutura Académica

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

Regras de Eliminação

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

Registo de Auditoria

Todas as alterações são registadas — quem alterou o quê, quando e a partir de onde.

Ordem de Registo 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 de conclusão) │
        │ ────────────────────►│ POST /cohorts
        │                                   │
        │  Estudante torna-se elegível      │
        │ ────────────────────►│ GET /students?where[email]=...
        │                                   │  POST /students (se não existir)
        │                                   │  POST /enrollments
        │                                   │
        │  Emissão de certificado ativada   │
        │ ────────────────────►│ 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. Pode ser criada através de:
  • O painel do DokStamp (configuração manual, uma única vez)
  • A API: POST /institutions
Assim que a instituição existir, toda a sincronização subsequente de entidades pode ser feita de forma programática.

​
Modos de integração

​
Síncrono (em tempo real)

O sistema chama diretamente a API do DokStamp quando uma entidade é alterada. Simples de implementar, funciona bem em cenários de baixo volume. 
Ação do utilizador no ERP → Chamada à API do DokStamp → Resposta tratada imediatamente

​
Assíncrono (baseado em fila)

O sistema coloca um trabalho em fila sempre que uma entidade é alterada. Um processo em segundo plano processa a fila 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 sistema. 
Ação do utilizador no ERP → Trabalho em fila → Worker chama a API do DokStamp → Retry em caso de falha
Estratégia de retry: Use exponential backoff. Repita o pedido em caso de HTTP 429 (limite de taxa) e 5xx (erros do servidor). Não repita em caso de 4xx (erros do cliente — indicam um problema de dados ou autenticação que requer investigação).

​
Idempotência: pesquisar antes de criar

O DokStamp não expõe chaves de idempotência. O padrão recomendado é pesquisar uma entidade antes de a criar para evitar duplicados. 
// Before creating a student, check if they already exist
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).