Documentación de la API

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

Quickstart

1. En el panel, en API, crea una clave (planes Profesional, Escala y prueba gratis).
2. Crea una emisión en el panel o por la API y anota el id.
3. Emite:

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":"[email protected]","external_id":"aluno-1287","send_email":true}'

La respuesta incluye el code y la url pública de la credencial.

Autenticación

Envía la clave en el encabezado Authorization: Bearer <chave>. La clave pertenece a la organización, no a una persona, y solo se muestra al crearla. Revoca en el panel las que no uses.

Emisiones

Una emisión es el curso, evento o certificación: tipo, título, edición, duración, modelo, firma y correo de entrega.

Método	Ruta
GET	/issuances	Lista (paginada: page, per_page hasta 100)
GET	/issuances/{id}	Una emisión
POST	/issuances	Crea. Campos: title (obligatorio), 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 credenciales

POST /issuances/{id}/credentials

Campo
recipient_name	Obligatorio
recipient_email	Para entrega por correo y búsqueda
external_id	El ID en tu sistema. Idempotencia: repetir el mismo valor devuelve la credencial existente (200) en vez de crear otra
title	Título del documento (predeterminado: según el tipo, ej.: "Certificado de Finalización")
extra_info	Texto adicional (nota, módulo, observación)
issued_on, expires_on	Fechas (emisión predeterminada: hoy; sin vencimiento)
send_email	true envía el correo de entrega al instante

Sin external_id, el mismo correo en la misma emisión no genera otra credencial. Respuesta: 201 (creada) o 200 (ya existía), con el objeto credencial.

Por lotes (hasta 500 por llamada): envía {"credentials": [ {...}, {...} ], "send_email": false}. La respuesta separa created, existing y over_quota.

Consultar

Método	Ruta
GET	/credentials	Filtros: issuance_id, email, external_id; paginada
GET	/credentials/{code}	Una credencial de tu organización

Revocar

POST /credentials/{code}/revoke con {"reason": "..."} (opcional). La página pública muestra "revocada" y el motivo.

Verificar (pública)

GET /verify/{code}, sin clave: devuelve lo que muestra la página pública, sin el correo del destinatario. Útil para verificar certificados desde otro sistema.

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

Certificação (programas e provas)

Para quem usa o SmartCerts como prova: estes caminhos deixam o seu sistema de ensino mandar o aluno fazer a prova aqui e saber depois se ele passou. Inscrever é ato do candidato, com a conta dele, pelo invite_url.

Método	Ruta
GET	/programs	Os programas da sua organização, com as regras da prova
GET	/programs/{id|slug}	Um programa
GET	/programs/{id|slug}/results?email=	Situação do candidato: tentativas, melhor nota, aprovação e credencial

curl -H "Authorization: Bearer $TOKEN" \
  "https://smartcerts.co/api/v1/programs/open-banking/[email protected]"

{
  "candidate": {"email": "[email protected]", "registered": true, "name": "Ana Souza"},
  "enrolled": true,
  "attempts": 2,
  "attempts_left": 1,
  "best_score": 85,
  "passed": true,
  "passed_at": "2026-10-08T14:02:11-03:00",
  "by_skill": {"Fundamentos": 100, "Regulação": 75},
  "credential": {"code": "k7m2p9x4w3qa", "state": "valid", "url": "https://smartcerts.co/certificate/k7m2p9x4w3qa"}
}

E-mail que ainda não tem conta aqui responde no mesmo formato, com passed: false: quem chama não precisa tratar 404.

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": "[email protected]" },
  "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
}

Errores y límites

Los errores siempre tienen el formato {"error": {"code": "...", "message": "...", "fields": {...}}}.

HTTP	code
401	unauthorized	Clave ausente o inválida
402	quota_exceeded	Límite de prueba gratis alcanzado
403	plan_required	Plan sin API
404	not_found	No existe o pertenece a otra organización
422	invalid	Campos inválidos (detalles en fields)
429		Más de 120 llamadas por minuto por clave (verificación pública: 60 por minuto por IP)

Todavía no hay webhooks de credenciales ni entorno de pruebas. Usa la prueba gratis o una emisión de prueba y revócala después.