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

# Integration Guide

> How to connect a third-party academic system (ERP, SIS, LMS) to DokStamp and keep entities in sync.

# Integration Guide

This guide is for developers integrating an existing academic system — an ERP, Student Information System (SIS), or LMS — with the DokStamp API. It covers the full integration lifecycle: initial setup, ongoing entity sync, deletion rules, and the audit trail.

<CardGroup cols={2}>
  <Card title="Syncing Academic Structure" icon="arrows-rotate" href="/en/integration-guide/syncing-academic-structure">
    How to sync courses, modules, cohorts, and students from your system to DokStamp.
  </Card>

  <Card title="Deletion Rules" icon="shield-halved" href="/en/integration-guide/deletion-rules">
    What can and cannot be deleted once certificates have been issued.
  </Card>

  <Card title="Entity Registration Order" icon="list-ol" href="/en/core-concepts/entity-registration-order">
    The dependency graph all integrations must follow.
  </Card>
</CardGroup>

***

## Typical integration scenario

```text theme={null}
Third-party system (ERP/SIS)          DokStamp API
        │                                   │
        │  New course created               │
        │ ────────────────────►│ POST /courses
        │                                   │
        │  Module added to course           │
        │ ────────────────────►│ POST /modules
        │                                   │  POST /courses/{id}/attach/modules
        │                                   │
        │  New cohort (graduating class)    │
        │ ────────────────────►│ POST /cohorts
        │                                   │
        │  Student becomes eligible         │
        │ ────────────────────►│ GET /students?where[user][email]=...
        │                                   │  POST /students (if not found)
        │                                   │  POST /enrollments
        │                                   │
        │  Certificate issuance triggered   │
        │ ────────────────────►│ POST /files
        │                                   │  POST /certificates
```

***

## Before you start

**Institution setup is required first.** The institution is the root entity — all courses, modules, and certificates depend on it. It can be created via:

* The DokStamp dashboard (manual, one-time setup)
* The API: `POST /institutions`

Once the institution exists, all subsequent entity sync can be done programmatically.

***

## Integration modes

### Synchronous (real-time)

Your system calls DokStamp's API directly when an entity changes. Simple to implement, works well for low-volume scenarios.

```text theme={null}
User action in ERP → API call to DokStamp → Response handled immediately
```

### Asynchronous (queue-based)

Your system enqueues a job whenever an entity changes. A background worker processes the queue and calls DokStamp's API. Recommended for high-volume integrations or when DokStamp availability should not affect your system's performance.

```text theme={null}
User action in ERP → Job enqueued → Worker calls DokStamp API → Retry on failure
```

**Retry strategy:** Use exponential backoff. Retry on HTTP `429` (rate limit) and `5xx` (server errors). Do not retry on `4xx` (client errors — these indicate a data or auth problem that needs investigation).

***

## Idempotency: search before create

DokStamp does not expose idempotency keys. The recommended pattern is to **look up an entity before creating it** to avoid duplicates.

```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;
```

Apply the same pattern for courses (by `code`), cohorts (by `code`), and modules (by `code` + `institution_uuid`).