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

# Emita o Seu Primeiro Certificado

> Um guia completo de ponta a ponta incluindo módulos, turmas e matrículas.

# Emita o Seu Primeiro Certificado

Este guia percorre o fluxo completo de emissão de certificados — da configuração da instituição até à emissão de uma credencial verificável com todas as entidades opcionais incluídas. No final, o utilizador terá um certificado ativo com uma URL de verificação pública.

***

## Antes de começar

Certifique-se de que dispõe de:

* Credenciais de API (e-mail + palavra-passe)
* O seu identificador `X-Tenant`
* Um PDF assinado do certificado

Defina estas variáveis de ambiente para os exemplos abaixo:

```bash theme={null}
export API=https://api.dokstamp.com
export TENANT=seu-dominio-tenant
export TOKEN=""  # Será definido após o Passo 1
```

***

## Passo 1 — Autenticar

```bash theme={null}
TOKEN=$(curl -s -X POST $API/auth/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@minhaescola.edu","password":"palavra-passe"}' \
  | jq -r '.access_token')

echo "Token: $TOKEN"
```

***

## Passo 2 — Criar a Instituição

```bash theme={null}
INSTITUTION=$(curl -s -X POST $API/institutions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d '{
    "name": "Federal University of Technology",
    "country": "Brazil",
    "status": "active"
  }')

INSTITUTION_UUID=$(echo $INSTITUTION | jq -r '.data.uuid')
echo "UUID da Instituição: $INSTITUTION_UUID"
```

***

## Passo 3 — Criar um Módulo

```bash theme={null}
MODULE=$(curl -s -X POST $API/modules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"name\": \"Engenharia de Software\",
    \"code\": \"SE301\",
    \"institution_uuid\": \"$INSTITUTION_UUID\",
    \"workload\": 60,
    \"credits\": 3,
    \"modality\": \"hybrid\",
    \"level\": \"undergraduate\"
  }")

MODULE_UUID=$(echo $MODULE | jq -r '.data.uuid')
```

***

## Passo 4 — Criar o Curso

```bash theme={null}
COURSE=$(curl -s -X POST $API/courses \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"name\": \"Bachelor of Computer Science\",
    \"code\": \"BCS-2024\",
    \"institution_uuid\": \"$INSTITUTION_UUID\",
    \"workload_hours\": 3200,
    \"status\": \"active\"
  }")

COURSE_UUID=$(echo $COURSE | jq -r '.data.uuid')
```

***

## Passo 5 — Vincular o Módulo ao Curso

```bash theme={null}
curl -X POST "$API/courses/$COURSE_UUID/attach/modules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"modules\": [
      { \"uuid\": \"$MODULE_UUID\", \"order\": 1, \"is_required\": true }
    ]
  }"
```

***

## Passo 6 — Criar uma Turma

```bash theme={null}
COHORT=$(curl -s -X POST $API/cohorts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"course_uuid\": \"$COURSE_UUID\",
    \"code\": \"BCS-2024-1\",
    \"modality\": \"hybrid\",
    \"start_date\": \"2024-02-01T00:00:00Z\",
    \"end_date\": \"2027-12-31T00:00:00Z\"
  }")

COHORT_UUID=$(echo $COHORT | jq -r '.data.uuid')
```

***

## Passo 7 — Criar o Estudante

```bash theme={null}
# Verificar se o estudante já existe
EXISTING=$(curl -s "$API/students?where[user][email]=maria@email.com" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "X-Tenant: $TENANT")

STUDENT_UUID=$(echo $EXISTING | jq -r '.data[0].uuid // empty')

if [ -z "$STUDENT_UUID" ]; then
  STUDENT=$(curl -s -X POST $API/students \
    -H "Authorization: Bearer $TOKEN" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Tenant: $TENANT" \
    -d '{
      "name": "Maria Fernanda Silva",
      "email": "maria@email.com",
      "date_of_birth": "1998-05-20",
      "gender": "female"
    }')
  STUDENT_UUID=$(echo $STUDENT | jq -r '.data.uuid')
fi

echo "UUID do Estudante: $STUDENT_UUID"
```

***

## Passo 8 — Criar uma Matrícula

```bash theme={null}
ENROLLMENT=$(curl -s -X POST $API/enrollments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"student_uuid\": \"$STUDENT_UUID\",
    \"course_uuid\": \"$COURSE_UUID\",
    \"cohort_uuid\": \"$COHORT_UUID\",
    \"enrolled_at\": \"2024-02-01\",
    \"completion_status\": \"completed\",
    \"grade\": 9.0,
    \"completed_at\": \"2027-12-20\"
  }")

ENROLLMENT_UUID=$(echo $ENROLLMENT | jq -r '.data.uuid')
```

***

## Passo 9 — Enviar o PDF

```bash theme={null}
FILE=$(curl -s -X POST $API/files \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "X-Tenant: $TENANT" \
  -F "files[]=@/caminho/para/diploma-maria.pdf")

FILE_UUID=$(echo $FILE | jq -r '.data[0].uuid')
echo "UUID do Ficheiro: $FILE_UUID"
```

***

## Passo 10 — Emitir o Certificado

```bash theme={null}
CERTIFICATE=$(curl -s -X POST $API/certificates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"institution_uuid\": \"$INSTITUTION_UUID\",
    \"course_uuid\": \"$COURSE_UUID\",
    \"student_uuid\": \"$STUDENT_UUID\",
    \"cohort_uuid\": \"$COHORT_UUID\",
    \"enrollment_uuid\": \"$ENROLLMENT_UUID\",
    \"file_uuid\": \"$FILE_UUID\",
    \"status\": \"issued\",
    \"issued_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"
  }")

echo "Certificado:"
echo $CERTIFICATE | jq '.data | {uuid, status, public_verification_url}'
```

**Saída:**

```json theme={null}
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "issued",
  "public_verification_url": "https://verificar.dokstamp.eu/a1b2c3d4"
}
```

A `public_verification_url` está pronta para ser partilhada — não é necessária qualquer autenticação para aceder-lhe.

***

## Próximos passos

* **Emissão em lote** — processe centenas de certificados de uma vez → [Operações em Lote](/pt/guides/bulk-operations)
* **Emblemas digitais** — emita Open Badges juntamente com certificados → [Open Badges](/pt/guides/openbadges)
* **Portfólio do estudante** — permita que o estudante publique o seu certificado → [Portfólio do Estudante](/pt/guides/student-portfolio)