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

# Guia de Integração

> Como ligar um sistema académico de terceiros (ERP, SIS, LMS) ao DokStamp e manter as entidades em sincronização.

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

<CardGroup cols={2}>
  <Card title="Sincronização da Estrutura Académica" icon="arrows-rotate" href="/pt/integration-guide/syncing-academic-structure">
    Como sincronizar cursos, módulos, turmas e estudantes do seu sistema para o DokStamp.
  </Card>

  <Card title="Regras de Eliminação" icon="shield-halved" href="/pt/integration-guide/deletion-rules">
    O que pode e não pode ser eliminado após a emissão de certificados.
  </Card>

  <Card title="Ordem de Registo de Entidades" icon="list-ol" href="/pt/core-concepts/entity-registration-order">
    O grafo de dependências que todas as integrações devem seguir.
  </Card>
</CardGroup>

***

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

```text theme={null}
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[user][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.

```text theme={null}
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.

```text theme={null}
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.

```javascript theme={null}
// Before creating a student, check if they already exist
const existing = await api.get('/students', {
  params: { 'where[user][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`).