Saltar al contenido
Cómo Funciona Soluciones Casos de Uso Plantillas Precios Clientes FAQ Alternativas Verificar
Iniciar Sesión Comenzar Gratis
Desarrolladores

Emita y verifique desde sus propios sistemas

Una API REST con JSON y claves API con permisos limitados, además de webhooks firmados que informan a sus sistemas lo que ocurre con cada certificado. El acceso a la API está incluido en todos los planes, incluido el plan gratuito Starter.

Autenticación

Cree una clave API en la aplicación, en Configuración y luego Claves API. Elija los permisos que necesita y, si lo desea, una caducidad en días. La clave completa (empieza con crtfd_live_) se muestra una sola vez, así que guárdela en un lugar seguro. Envíela como token bearer:

Authorization: Bearer crtfd_live_your_key_here

Todos los endpoints están bajo https://certifyd.cloud/api/v1 y usan JSON. Las respuestas correctas envuelven el contenido como { "data": ... }. Los errores llegan como { "error": { "code", "message" } }. Los códigos comunes son INVALID_API_KEY, INSUFFICIENT_SCOPE (la respuesta indica el permiso que falta) y CREDIT_LIMIT (HTTP 402, ya usó sus créditos mensuales). Las solicitudes tienen límite de frecuencia. Espere antes de reintentar si recibe HTTP 429.

Permisos

PermisoPermite
events:read, events:writeLeer, o crear / actualizar / eliminar, eventos y su configuración de registro
attendees:read, attendees:writeLeer, o crear / actualizar / eliminar / importar, asistentes
templates:read, templates:writeLeer, o administrar, plantillas de certificados
certificates:generateEmitir, regenerar y generar certificados de forma masiva
certificates:read, certificates:writeLeer y descargar certificados, o revocarlos, eliminarlos y enviarlos
badges:read, badges:writeLeer, o crear / actualizar / eliminar / emitir, insignias
analytics:readAnalítica del panel y por evento
issuer:read, issuer:writeConsultar, o cambiar, el perfil de emisor de tu organización (nombre, sitio web, correo de contacto, imagen)
webhooks:manageAdministrar suscripciones de webhooks y consultar sus entregas
Las claves API no pueden crear ni revocar otras claves API: eso solo es posible desde una sesión iniciada en la aplicación, de modo que una clave filtrada no pueda generarse un reemplazo.

Ejemplo: emitir un certificado y verificarlo

La clave necesita los permisos templates:read, events:write, attendees:write y certificates:generate. Cada certificado emitido usa un crédito. Los ejemplos usan jq para extraer valores del JSON.

# 0. Your key and the API address
export CERTIFYD_KEY="crtfd_live_your_key_here"
export API="https://certifyd.cloud/api/v1"

# 1. Pick one of your templates (take the "id" of any entry in data)
curl -s "$API/templates?active=true" \
  -H "Authorization: Bearer $CERTIFYD_KEY" | jq '.data[] | {id, name}'
export TEMPLATE_ID="paste-a-template-id-here"

# 2. Create an event
export EVENT_ID=$(curl -s -X POST "$API/events" \
  -H "Authorization: Bearer $CERTIFYD_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Safety Training\",\"eventDate\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"templateId\":\"$TEMPLATE_ID\"}" \
  | jq -r '.data.id')

# 3. Add an attendee
export ATTENDEE_ID=$(curl -s -X POST "$API/attendees" \
  -H "Authorization: Bearer $CERTIFYD_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"eventId\":\"$EVENT_ID\",\"firstName\":\"Ana\",\"lastName\":\"Rivera\",\"email\":\"ana@example.com\"}" \
  | jq -r '.data.id')

# 4. Issue the certificate ("sendEmail": false holds back the delivery email).
#    The Idempotency-Key makes a retry of this exact request safe (see below).
export CODE=$(curl -s -X POST "$API/certificates/generate" \
  -H "Authorization: Bearer $CERTIFYD_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"templateId\":\"$TEMPLATE_ID\",\"eventId\":\"$EVENT_ID\",\"attendeeId\":\"$ATTENDEE_ID\",\"sendEmail\":false}" \
  | jq -r '.data.verificationCode')
echo "Verification code: $CODE"

# 5. Verify it. This endpoint is public: no API key needed.
curl -s "$API/verify/$CODE"

La respuesta de verificación incluye status (valid, expired o revoked), el destinatario, la credencial, el emisor y las fechas. El mismo código abre la página legible en https://certifyd.cloud/verify/<code>. Cuando la firma está activada para el emisor, la respuesta incluye además un bloque signature (vea Credenciales firmadas y claves). Consulte cómo verificar una credencial.

Los reintentos nunca emiten dos veces

Un asistente tiene como máximo un certificado válido por evento y plantilla. Si POST /certificates/generate indica un asistente que ya tiene uno, la API responde HTTP 409 con el código ALREADY_ISSUED y un encabezado Location que apunta al certificado existente; el miembro existing del cuerpo del error incluye su id, certificateNumber y verificationCode. No se emite, envía ni cobra nada. Un certificado revocado o vencido no cuenta, por lo que puede emitir uno nuevo después.

POST /badges/{id}/issue funciona igual para cada asistente. Un asistente que ya tiene la insignia aparece en la respuesta con "alreadyIssued": true, y solo las insignias nuevas usan créditos.

Ambos endpoints aceptan además un encabezado opcional Idempotency-Key: de 1 a 255 caracteres imprimibles, idealmente un UUID que usted genera para cada solicitud. Si la misma clave llega de nuevo con el mismo cuerpo dentro de 24 horas, la API responde HTTP 200 con la respuesta original y el encabezado Idempotent-Replayed: true. La misma clave con un cuerpo distinto se rechaza con HTTP 422 IDEMPOTENCY_KEY_REUSED. Una repetición que llega mientras la primera solicitud aún se procesa recibe HTTP 409 IDEMPOTENCY_IN_PROGRESS; reinténtela un momento después. Una solicitud que falló no se recuerda, por lo que puede reintentarla con la misma clave.

Eliminar una credencial emitida

DELETE /certificates/{id} sobre un certificado ya emitido lo revoca con el motivo "Deleted by issuer" (la respuesta pública de verificación incluye además revocationReasonCode: "deleted_by_issuer") en lugar de borrarlo, de modo que quien escanee su código QR vea "revocado" y nunca "no encontrado". Solo se elimina un borrador que nunca se emitió. DELETE /badges/{id} sobre una insignia ya emitida la retira: deja de aparecer en su lista y las insignias ya emitidas a partir de ella quedan revocadas. Un asistente que aún tiene certificados no se puede eliminar (HTTP 409 ATTENDEE_HAS_CERTIFICATES), ni tampoco uno al que se le han emitido insignias (HTTP 409 ATTENDEE_HAS_BADGES).

Endpoints

Todas las rutas siguientes son relativas a /api/v1. La referencia de la API (en inglés) lista cada operación con sus parámetros, respuestas y el permiso que necesita, y permite probar una llamada.

ÁreaEndpoints
EventosGET/POST /events GET/PUT/DELETE /events/{id} GET /events/{id}/attendees GET /events/{id}/certificates GET/PUT /events/{id}/registration
Emisión masivaPOST /events/{id}/certificates/generate POST /events/{id}/certificates/generate/jobs GET /events/{id}/certificates/generate/jobs/{jobId}
AsistentesGET/POST /attendees GET/PUT/DELETE /attendees/{id} GET /attendees/count POST /attendees/import GET /events/{id}/attendees/export
PlantillasGET/POST /templates GET/PUT/DELETE /templates/{id} POST /templates/{id}/duplicate POST /templates/{id}/preview GET /system-templates
CertificadosPOST /certificates/generate GET/DELETE /certificates/{id} GET /certificates/{id}/download POST /certificates/{id}/regenerate POST /certificates/{id}/revoke POST /certificates/{id}/send
InsigniasGET/POST /badges GET/PUT/DELETE /badges/{id} POST /badges/{id}/issue GET /badges/{id}/assertions
Perfil de emisorGET/PUT /issuer-profile
Firma de credencialesPOST /credential-signing/backfill GET /credential-signing/backfill/status
CorreoPOST /email/send-bulk GET /email/deliveries
AnalíticaGET /analytics/dashboard GET /analytics/events/{id}
CréditosGET /credits (créditos usados, límite y restantes este mes)
WebhooksGET/POST /webhooks PUT/DELETE /webhooks/{id} GET /webhooks/{id}/deliveries POST /webhooks/{id}/test
Verificación (pública)GET /verify/{code} GET /verify/{code}/qr GET /verify/{code}/preview.png GET /verify/{code}/badge.png GET /verify/{code}/badge.svg GET /verify/{code}/credential GET /verify/{code}/certificate.pdf

Credenciales firmadas y claves

Cuando la firma está activada para un emisor, cada certificado nuevo recibe también una credencial firmada (un VC-JWT): los datos de la credencial, con campos al estilo Open Badges, firmados con una clave de Certifyd. Cualquiera puede comprobarla, sin clave API y sin depender de una copia del archivo. Las direcciones siguientes son públicas y no necesitan clave. Las credenciales emitidas antes de activar la firma se quedan como están hasta que se firmen de nuevo; mientras tanto no tienen archivo firmado.

DirecciónQué obtiene
GET /issuers/{slug}El perfil público del emisor: nombre, sitio web, correo de contacto e imagen. La dirección es un código opaco, nunca el identificador de su cuenta.
GET /.well-known/jwks.jsonLas claves públicas con las que se firman las credenciales (la actual, la siguiente y las retiradas). Las claves retiradas siguen publicadas, así que las credenciales anteriores se siguen verificando.
GET /keys/{keyId}Una de esas claves. El kid del encabezado de cada credencial firmada es exactamente esta dirección.
GET /status-lists/{slug}/revocationLa lista de revocación firmada del emisor: un bit por credencial, y un bit activado significa revocada. Su tamaño es fijo, por lo que no revela cuántas credenciales existen.
GET /api/v1/verify/{code}/credentialLa credencial firmada como texto plano (un JWS compacto). Responde 404 cuando el certificado aún no tiene credencial firmada, está revocado o no existe. No necesita clave API.
GET /v/{code} + Accept: application/vc+jwtLa misma credencial firmada desde la dirección corta de verificación. Solo ese encabezado Accept exacto lo activa; los navegadores siguen recibiendo la página de verificación.

Comprobar una credencial por su cuenta

  1. Divida el archivo en los dos puntos: encabezado, contenido y firma (cada uno en base64url).
  2. El encabezado debe tener exactamente dos miembros: alg = RS256 y kid. Rechace cualquier otra cosa.
  3. Obtenga la clave de la dirección del kid y verifique la firma sobre las dos primeras partes.
  4. Compare los datos con la credencial: iss = issuer.id, jti = id, sub = credentialSubject.id, nbf = validFrom y exp = validUntil si lo hay. Rechácela cuando exp haya pasado.
  5. Obtenga la lista de credentialStatus.statusListCredential, verifíquela del mismo modo, decodifique encodedList y mire el bit en statusListIndex. Un bit activado significa que la credencial fue revocada.
Una copia de un archivo firmado no se puede retirar. Si el emisor revoca una credencial, solo la lista de revocación se lo dice al verificador, así que compruebe siempre el paso 5.

La respuesta de verificación y la API del perfil de emisor

GET /verify/{code} incluye un bloque signature mientras la firma está activa: state (signed, unsigned o failed), valid, kid, signedAt, issuerName y, solo para una credencial válida que no esté revocada, credentialUrl. Certifyd comprueba la firma en su servidor; failed significa que no se pudo demostrar la firma, nunca "verificada". El bloque no aparece cuando la firma está desactivada.

Con los permisos issuer:read e issuer:write sus propios sistemas pueden consultar y cambiar el perfil de emisor (GET/PUT /issuer-profile) y firmar credenciales emitidas antes de activar la firma. POST /credential-signing/backfill es por defecto una prueba sin cambios: solo cuenta lo que se firmaría. Envíe { "dryRun": false } para firmar de verdad y siga GET /credential-signing/backfill/status hasta que el estado sea completed. Solo alcanza su propia cuenta, nunca revoca ni modifica un certificado y no envía correos.

Webhooks

Suscriba un endpoint HTTPS con POST /webhooks (o en la aplicación, en Configuración y luego Webhooks) y elija los eventos que recibirá. Los endpoints deben usar HTTPS y resolver a una dirección pública. El secreto de firma se devuelve una sola vez, al crear la suscripción.

EventoSe envía cuando
certificate.issuedSe genera un certificado, individualmente o de forma masiva
certificate.sentSe envía un certificado por correo a su destinatario
certificate.viewedEl destinatario abre su enlace del portal por primera vez
certificate.downloadedEl destinatario descarga el PDF del certificado desde el portal
certificate.revokedUsted revoca un certificado

También puede enviarse una muestra con POST /webhooks/{id}/test, que entrega un evento webhook.test.

Qué recibe

POST https://your-server.example/certifyd-hook
Content-Type: application/json
X-Certifyd-Event: certificate.issued
X-Certifyd-Delivery: 7c0e5b0e-0000-0000-0000-000000000000
X-Certifyd-Timestamp: 1790000000
X-Certifyd-Signature: sha256=3f1c...e9

{ "eventType": "certificate.issued", "timestamp": "...", "data": { "certificateId": "...", "certificateNumber": "...", "eventId": "...", "attendeeId": "...", "status": "...", "verificationCode": "CFD-7X4K-92QM" } }

La firma es un HMAC-SHA256 en hexadecimal de "{timestamp}.{cuerpo sin modificar}" con el secreto de su suscripción como clave. Verifíquela, rechace marcas de tiempo con más de unos minutos de antigüedad y use X-Certifyd-Delivery para ignorar duplicados. No cambia entre reintentos.

# Recompute the signature on your side (bash + openssl)
printf '%s.%s' "$TIMESTAMP" "$RAW_BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"

Cada entrega tiene un tiempo límite de 10 segundos. Una entrega fallida se intenta hasta 5 veces en total, tras 1 minuto, 5 minutos, 30 minutos y 2 horas. Una suscripción que sigue fallando se desactiva tras 10 intentos fallidos seguidos.

Lo que no está disponible

Todavía no hay bibliotecas cliente oficiales. El documento OpenAPI está publicado en /openapi/v1.json, para que pueda generar un cliente en su propio lenguaje. Tampoco hay un conector nativo de Zapier o Make: cualquier herramienta que pueda enviar solicitudes HTTPS y recibir webhooks puede integrarse con los endpoints anteriores.

§En fe de lo cual

Emita su primer certificado hoy

La configuración toma unos diez minutos. Gratis para 12 credenciales al mes, sin tarjeta.