Saltar para o conteúdo principal

​
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: 
export API=https://api.dokstamp.eu
export TENANT=seu-dominio-tenant
export TOKEN=""  # Será definido após o Passo 1

​
Passo 1 — Autenticar

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

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

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

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

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

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

# Verificar se o estudante já existe
EXISTING=$(curl -s "$API/students?where[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

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

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

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: 
{
  "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
  • Emblemas digitais — emita Open Badges juntamente com certificados → Open Badges
  • Portfólio do estudante — permita que o estudante publique o seu certificado → Portfólio do Estudante