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

# Certificados

> Emita, gira e verifique certificados digitais — o principal resultado da plataforma DokStamp.

# Certificados

Um certificado é a credencial digital que vincula um estudante a um curso, emitida por uma instituição. Inclui um ficheiro PDF assinado, uma URL de verificação pública e um snapshot imutável da identidade do estudante no momento da emissão.

***

## O objeto certificado

```json theme={null}
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "issued",
  "issued_at": "2024-12-01T00:00:00.000000Z",
  "revoked_at": null,
  "revocation_reason": null,
  "public_verification_url": "https://verificar.dokstamp.eu/a1b2c3d4",
  "blockchain_tx_hash": null,
  "blockchain_tx_url": null,
  "institution": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Federal University of Technology"
  },
  "course": {
    "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "Bachelor of Computer Science"
  },
  "student": {
    "uuid": "f6a7b8c9-d0e1-2345-fghi-456789012345",
    "name": "Maria Fernanda Silva"
  },
  "cohort": null,
  "enrollment": null,
  "template": null,
  "files": [
    {
      "type": "certificate",
      "uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567"
    }
  ]
}
```

| Campo                     | Tipo           | Descrição                                      |
| ------------------------- | -------------- | ---------------------------------------------- |
| `uuid`                    | string         | Identificador único                            |
| `status`                  | enum           | `draft`, `issued`, `revoked`, `expired`        |
| `issued_at`               | datetime       | Data oficial de emissão                        |
| `revoked_at`              | datetime\|null | Timestamp de revogação                         |
| `revocation_reason`       | string\|null   | Motivo da revogação                            |
| `public_verification_url` | string\|null   | URL partilhável para verificação por terceiros |
| `blockchain_tx_hash`      | string\|null   | Hash da transação blockchain (se ancorado)     |
| `files`                   | array          | Ficheiros PDF anexados                         |

***

## Listar certificados

```http theme={null}
GET /certificates
```

<CodeGroup>
  ```bash cURL theme={null}
  # Listar todos os certificados emitidos de um curso
  curl "https://api.dokstamp.com/certificates?where[status]=issued&where[course_uuid]=c3d4e5f6-a7b8-9012-cdef-123456789012&sort[column]=issued_at&sort[order]=desc" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Tenant: {TENANT}"
  ```
</CodeGroup>

***

## Emitir um certificado

```http theme={null}
POST /certificates
```

| Parâmetro                 | Tipo     | Obrigatório | Descrição                                                            |
| ------------------------- | -------- | ----------- | -------------------------------------------------------------------- |
| `institution_uuid`        | string   | Sim         | UUID da instituição emissora                                         |
| `course_uuid`             | string   | Sim         | UUID do curso                                                        |
| `student_uuid`            | string   | Sim         | UUID do estudante destinatário                                       |
| `file_uuid`               | string   | Sim         | UUID do ficheiro PDF enviado (deve estar sem uso)                    |
| `status`                  | enum     | Não         | `draft` (padrão) ou `issued`                                         |
| `issued_at`               | datetime | Não         | Data oficial de emissão (obrigatória se `status=issued`)             |
| `cohort_uuid`             | string   | Não         | UUID da turma                                                        |
| `enrollment_uuid`         | string   | Não         | UUID da matrícula                                                    |
| `template_uuid`           | string   | Não         | UUID do modelo de certificado                                        |
| `public_verification_url` | string   | Não         | URL de verificação personalizada (gerada automaticamente se omitida) |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.dokstamp.com/certificates \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Tenant: {TENANT}" \
    -d '{
      "institution_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "course_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "student_uuid": "f6a7b8c9-d0e1-2345-fghi-456789012345",
      "file_uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567",
      "status": "issued",
      "issued_at": "2024-12-01T00:00:00Z",
      "cohort_uuid": "e5f6a7b8-c9d0-1234-efgh-345678901234",
      "enrollment_uuid": "g7h8i9j0-k1l2-3456-mnop-567890123456"
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://api.dokstamp.com/certificates', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'X-Tenant': TENANT,
    },
    body: JSON.stringify({
      institution_uuid: INSTITUTION_UUID,
      course_uuid: COURSE_UUID,
      student_uuid: STUDENT_UUID,
      file_uuid: FILE_UUID,
      status: 'issued',
      issued_at: new Date().toISOString(),
    }),
  });
  const { data: certificate } = await res.json();
  console.log('URL de verificação:', certificate.public_verification_url);
  ```

  ```php PHP theme={null}
  $response = Http::withToken($token)
      ->withHeaders(['X-Tenant' => $tenant, 'Accept' => 'application/json'])
      ->post('https://api.dokstamp.com/certificates', [
          'institution_uuid' => $institutionUuid,
          'course_uuid'      => $courseUuid,
          'student_uuid'     => $studentUuid,
          'file_uuid'        => $fileUuid,
          'status'           => 'issued',
          'issued_at'        => now()->toIso8601String(),
      ]);

  $certificate = $response->json('data');
  ```
</CodeGroup>

**Resposta `201`:**

```json theme={null}
{
  "data": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "issued",
    "issued_at": "2024-12-01T00:00:00.000000Z",
    "public_verification_url": "https://verificar.dokstamp.eu/a1b2c3d4",
    "institution": { "name": "Federal University of Technology" },
    "course": { "name": "Bachelor of Computer Science" },
    "student": { "name": "Maria Fernanda Silva" }
  }
}
```

<Warning>
  Um UUID de ficheiro só pode ser utilizado uma vez. Ao tentar criar um segundo certificado com o mesmo `file_uuid`, será devolvido um erro `422`. Faça o envio de um novo ficheiro para cada certificado.
</Warning>

***

## Obter um certificado

```http theme={null}
GET /certificates/{uuid}
```

```bash theme={null}
GET /certificates/{uuid}?includes[student]=1&includes[course]=1&includes[institution]=1&includes[files]=1
```

***

## Atualizar um certificado

```http theme={null}
PATCH /certificates/{uuid}
PUT   /certificates/{uuid}
```

É possível atualizar certificados com o estado `draft`. A atualização de um certificado com o estado `issued` é restrita.

***

## Eliminar um certificado

```http theme={null}
DELETE /certificates/{uuid}
DELETE /certificates/batch/destroy
```

***

## Assertion de emblema (Open Badges)

```http theme={null}
GET /certificates/{uuid}/badges/assertions
```

Devolve a assertion W3C Open Badges 2.0 para o certificado. Este endpoint é utilizado por serviços de verificação de emblemas e badge backpacks (ex.: Badgr, Credly).

***

## Relacionados

* [Revogar um Certificado](/pt/api-reference/certificates/revocation)
* [Ciclo de Vida do Certificado](/pt/core-concepts/certificate-lifecycle)
* [Ficheiros](/pt/api-reference/files) — envie PDFs antes de criar certificados