Ciclo de Vida do Certificado
Todo certificado no DokStamp possui um campo status que determina quais as ações que podem ser realizadas e como aparece ao público.
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] ──────────────────────────────> [issued]
│
▼
[revoked]
[issued] ──> [expired] (automático, se a expiração estiver configurada)
As transições de estado são irreversíveis. Um certificado revogado não pode ser reativado. Um certificado revogado ou expirado não pode regressar ao estado issued. Se um certificado foi revogado por engano, é necessário emitir um novo.
Criar em rascunho vs. emitido
Ao chamar POST /certificates, defina status para controlar o estado inicial:
// Cria um rascunho — ainda não visível no URL de verificação
{ "status": "draft", ... }
// Cria e emite imediatamente — URL de verificação ativo
{ "status": "issued", "issued_at": "2024-12-01T00:00:00Z", ... }
draft quando quiser preparar certificados para revisão em lote antes da publicação oficial.
Revogar um certificado
Chame PUT /certificates/{uuid}/revoke com um motivo opcional:
curl -X PUT https://api.dokstamp.eu/certificates/{uuid}/revoke \
-H "Authorization: Bearer {TOKEN}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Tenant: {TENANT}" \
-d '{ "revocation_reason": "Emitido por engano — estudante não concluiu os requisitos." }'
Verificação pública
Quando um certificado se encontra no estado issued, o campo public_verification_url é preenchido:
{
"uuid": "a1b2c3d4-...",
"status": "issued",
"public_verification_url": "https://verificar.dokstamp.eu/a1b2c3d4",
"issued_at": "2024-12-01T00:00:00.000000Z"
}
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.
Isto é consistente com os padrões de Credenciais Verificáveis (VC), onde os dados do sujeito da credencial devem refletir o que era verdadeiro no momento da emissão.
Ancoragem em blockchain
Os certificados incluem campos opcionais blockchain_tx_hash e blockchain_tx_url para ancoragem futura em blockchain. Quando definidos, fornecem uma prova resistente a adulterações de que o hash do certificado foi registado num ledger público num momento específico no tempo.
