Documentação da API

Base: https://smartcerts.co/api/v1 · Formato: JSON (UTF-8) · Datas: AAAA-MM-DD

Quickstart

1. No painel, em API, crie uma chave (planos Profissional, Escala e o teste grátis).
2. Crie uma emissão no painel ou pela API e anote o id.
3. Emita:

curl -X POST https://smartcerts.co/api/v1/issuances/42/credentials \
  -H "Authorization: Bearer $SMARTCERTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recipient_name":"Ana Beatriz Souza","recipient_email":"ana@exemplo.com","external_id":"aluno-1287","send_email":true}'

A resposta traz o code e a url pública da credencial.

Autenticação

Envie a chave no cabeçalho Authorization: Bearer <chave>. A chave é da organização (não de uma pessoa) e aparece uma única vez ao ser criada. Revogue no painel as que não usar.

Emissões

Uma emissão é o curso, evento ou certificação: tipo, título, edição, carga horária, modelo, assinatura e e-mail de entrega.

Método	Caminho
GET	/issuances	Lista (paginada: page, per_page até 100)
GET	/issuances/{id}	Uma emissão
POST	/issuances	Cria. Campos: title (obrigatório), type, template (classico, moderno, minimal), edition, hours, location, title_url, description, signer, signer_role, email_subject, email_body

Tipos: participation, completion, professional, training, workshop, event, recognition, other.

Emitir credenciais

POST /issuances/{id}/credentials

Campo
recipient_name	Obrigatório
recipient_email	Para entrega por e-mail e busca
external_id	O ID no seu sistema. Idempotência: repetir com o mesmo valor devolve a credencial existente (200) em vez de criar outra
title	Título do documento (padrão: pelo tipo, ex.: "Certificado de Conclusão")
extra_info	Texto adicional (nota, módulo, observação)
issued_on, expires_on	Datas (padrão de emissão: hoje; sem validade)
send_email	true envia o e-mail de entrega na hora

Sem external_id, o mesmo e-mail na mesma emissão não gera uma segunda credencial. Resposta: 201 (criada) ou 200 (já existia), com o objeto credencial.

Em lote (até 500 por chamada): envie {"credentials": [ {...}, {...} ], "send_email": false}. A resposta separa created, existing e over_quota.

Consultar

Método	Caminho
GET	/credentials	Filtros: issuance_id, email, external_id; paginada
GET	/credentials/{code}	Uma credencial da sua organização

Revogar

POST /credentials/{code}/revoke com {"reason": "..."} (opcional). A página pública passa a mostrar "revogada" e o motivo.

Verificar (pública)

GET /verify/{code}, sem chave: devolve o que a página pública mostra (sem o e-mail do destinatário). Útil para quem recebe um certificado e quer conferir por sistema.

curl https://smartcerts.co/api/v1/verify/k7m2p9x4w3qa

Objeto credencial

{
  "code": "k7m2p9x4w3qa",
  "state": "valid",               // valid | expired | revoked
  "url": "https://smartcerts.co/certificate/k7m2p9x4w3qa",
  "pdf_url": "https://smartcerts.co/certificate/k7m2p9x4w3qa/pdf",
  "title": "Certificado de Conclusão",
  "recipient": { "name": "Ana Beatriz Souza", "email": "ana@exemplo.com" },
  "issuer": { "name": "Instituto Exemplo", "website": "https://..." },
  "issuance": { "id": 42, "type": "completion", "title": "Gestão de Projetos na Prática", "edition": "Turma de setembro", "hours": "40 horas" },
  "extra_info": null,
  "external_id": "aluno-1287",
  "issued_on": "2026-09-15",
  "expires_on": null,
  "revoked_at": null,
  "revocation_reason": null,
  "sent_at": "2026-09-15T14:02:11-03:00",
  "views": 3,
  "downloads": 1
}

Erros e limites

Erros vêm sempre como {"error": {"code": "...", "message": "...", "fields": {...}}}.

HTTP	code
401	unauthorized	Chave ausente ou inválida
402	quota_exceeded	Limite do teste grátis atingido
403	plan_required	Plano sem API
404	not_found	Não existe ou é de outra organização
422	invalid	Campos inválidos (detalhes em fields)
429		Mais de 120 chamadas por minuto por chave (a verificação pública: 60 por minuto por IP)

Ainda não há webhooks nem sandbox. Para testar, use o teste grátis ou uma emissão de teste e revogue depois.