> ## 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 conectar um sistema acadêmico de terceiros (ERP, SIS, LMS) ao DokStamp e manter as entidades sincronizadas.

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

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

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

  <Card title="Ordem de Registro de Entidades" icon="list-ol" href="/pt-BR/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 formanda)           │
        │ ────────────────────────►│ POST /cohorts
        │                                         │
        │  Estudante torna-se elegível            │
        │ ────────────────────────►│ GET /students?where[user][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.

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

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

```javascript theme={null}
// Antes de criar um estudante, verifique se ele já existe
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`).