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

Todo certificado no DokStamp possui um campo `status` que governa quais ações podem ser realizadas nele e como ele aparece ao público. As transições de status são gerenciadas internamente pela plataforma.

***

## Valores de status

| Status    | Descrição                                                                              |
| --------- | -------------------------------------------------------------------------------------- |
| `draft`   | Certificado em preparação. Ainda não verificável publicamente.                         |
| `issued`  | Certificado emitido oficialmente. A URL de verificação está ativa.                     |
| `revoked` | Certificado revogado após a emissão. A URL de verificação exibe um aviso de revogação. |
| `expired` | Certificado passou da 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, você deve emitir um novo.
</Warning>

***

## Emitindo um certificado

Para fazer a transição de um certificado de `draft` para `issued`, passe `finish: true` ao criá-lo. Isso aciona o pipeline completo de emissão: assinatura do arquivo, geração do histórico 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.

***

## Revogando 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, a URL de verificação pública permanece acessível, mas exibe um aviso claro de revogação com o motivo e o timestamp.

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

***

## Verificação pública

Quando um certificado está no status `issued`, o campo `public_verification_url` é preenchido:

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

Esta URL pode ser compartilhada com empregadores, outras instituições ou incluída no certificado impresso como QR code. Não é necessária autenticação para acessá-la.

***

## 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 junto ao 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 registrado em um ledger público em um momento específico no tempo.