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

# Ciclo de Vida do Certificado

> Como os certificados transitam pelos estados de rascunho, emitido, revogado e expirado.

# Ciclo de Vida do Certificado

Cada certificado no DokStamp possui um campo `status` que determina quais as ações que podem ser realizadas e como aparece ao público. As transições de estado são geridas internamente pela plataforma.

***

## Valores de estado

| Estado    | Descrição                                                                                  |
| --------- | ------------------------------------------------------------------------------------------ |
| `draft`   | Certificado em preparação. Ainda não verificável publicamente.                             |
| `issued`  | Certificado emitido oficialmente. O URL de verificação está ativo.                         |
| `revoked` | Certificado revogado após a emissão. O URL de verificação apresenta um aviso de revogação. |
| `expired` | Certificado ultrapassou a data de validade (se uma foi definida).                          |

***

## Transições de estado

```
[draft] ──── finish: true ────► [issued]
                                    │
                                    ▼
                               [revoked]

[issued] ──► [expired]   (automático, baseado no período de validade)
```

<Warning>
  As transições de estado são **irreversíveis**. Um certificado revogado não pode ser reativado. Se um certificado foi revogado por engano, é necessário emitir um novo.
</Warning>

***

## Emitir um certificado

Para fazer a transição de um certificado de `draft` para `issued`, passe `finish: true` ao criá-lo. Isto desencadeia o fluxo de emissão completo: assinatura do ficheiro, geração do historial académico e notificação do estudante.

```bash 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": "...",
    "course_uuid": "...",
    "student_uuid": "...",
    "file_uuid": "...",
    "finish": true
  }'
```

Omitir `finish` (ou passar `false`) cria o certificado como `draft`, permitindo revisão antes da publicação oficial.

***

## Revogar um certificado

Chame `PUT /certificates/{uuid}/revoke` com um motivo opcional:

```bash theme={null}
curl -X PUT https://api.dokstamp.com/certificates/{uuid}/revoke \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: {TENANT}" \
  -d '{ "revocation_reason": "Issued in error — student did not complete requirements." }'
```

Após a revogação, o URL de verificação pública permanece acessível, mas apresenta um aviso claro de revogação com o motivo e o timestamp.

→ [Referência completa de revogação](/pt/api-reference/certificates/revocation)

***

## Verificação pública

Quando um certificado se encontra no estado `issued`, o campo `public_verification_url` é preenchido:

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

Este URL pode ser partilhado com empregadores, outras instituições ou incluído no certificado impresso como QR code. Não é necessária autenticação para aceder ao mesmo.

***

## Snapshot do Sujeito da Credencial

No momento em que um certificado é emitido, o DokStamp captura um **snapshot** dos dados de identidade do estudante (nome, email, documento de identificação, data de nascimento, país). Esse snapshot é armazenado de forma imutável juntamente com o certificado, de modo que a credencial permaneça verificável mesmo que o perfil do estudante seja atualizado posteriormente.

***

## Ancoragem em blockchain

Os certificados incluem campos opcionais `blockchain_tx_hash` e `blockchain_tx_url` para ancoragem em blockchain. Quando definidos, fornecem uma prova resistente a adulterações de que o certificado foi registado num ledger público num momento específico no tempo.