Integraciones de API y webhooks

Tiempo de lectura: 12 minutos

Plan requerido: Pro

Las integraciones de API y webhooks de CertLister le permiten conectar sistemas externos — su LMS, su plataforma de RR. HH., Zapier, Make o cualquier aplicación propia — para automatizar los flujos de credenciales. Puede enviar datos hacia adentro (crear credenciales mediante la API REST o webhooks entrantes) y recibir notificaciones cuando algo sucede dentro de CertLister (mediante suscripciones a eventos).

Todo vive en la página de Integraciones en la barra lateral izquierda (icono de enchufe).

Qué incluye

Claves de API

Las claves de API permiten a las aplicaciones externas autenticarse con la API REST de CertLister. Cada clave tiene permisos específicos (alcances) que controlan lo que puede hacer.

Crear una clave de API

1. Vaya a Integraciones → pestaña Claves de API
2. Haga clic en Crear clave de API
3. Ingrese un nombre (p. ej., "Producción", "Zapier", "Integración LMS")
4. Seleccione los alcances — los permisos que la clave debe tener:
   • credentials:read — listar y ver credenciales
   • credentials:write — crear, actualizar y revocar credenciales
   • categories:read — listar y ver categorías
   • designs:read — listar y ver diseños guardados
5. Opcionalmente configure una expiración (Nunca, 30 días, 90 días o 1 año)
6. Haga clic en Crear

Importante: la clave completa se muestra una sola vez tras la creación. Cópiela de inmediato y guárdela de forma segura — no podrá verla de nuevo. CertLister almacena solo un hash de la clave.

Formato de la clave

Las claves de API siguen el formato cl_live_ seguido de 48 caracteres aleatorios. El prefijo cl_live_ facilita identificarlas si aparecen en registros o código.

Gestionar las claves

La tabla de claves de API muestra:

Para revocar una clave: haga clic en el botón de revocar en la fila y confirme. Las claves revocadas dejan de funcionar de inmediato. Cualquier sistema externo que la use recibirá respuestas 401 Unauthorized.

Para eliminar una clave: después de revocarla, puede eliminarla permanentemente de la lista.

API REST

La API REST le permite gestionar credenciales de forma programática. Todas las solicitudes se autentican con una clave de API.

Autenticación

Incluya su clave de API en el encabezado Authorization:

Authorization: Bearer cl_live_su_clave_de_api

URL base

Todos los puntos de acceso de la API están bajo:

https://app.certlister.com/api/v1/external/

Puntos de acceso disponibles

Crear una credencial mediante la API

Envíe una solicitud POST a /external/credentials:

{
  "recipient_name": "Jane Smith",
  "recipient_email": "jane@example.com",
  "title": "AWS Solutions Architect",
  "category_id": "uuid-de-su-categoria",
  "design_id": "uuid-de-su-diseno",
  "issue_date": "2026-06-18",
  "expiry_date": "2027-06-18",
  "status": "active",
  "custom_attributes": {
    "course_hours": "40",
    "instructor": "John Doe"
  },
  "send_email": true
}

Solo recipient_name es obligatorio. Los demás campos son opcionales. Si category_id se omite, la credencial va a la categoría predeterminada "Sin categoría".

Establezca send_email: true para enviar automáticamente el correo de emisión al destinatario.

Formato de respuesta

Éxito:

{
  "data": { ... },
  "meta": { "page": 1, "per_page": 25, "total": 142 }
}

Error:

{
  "error": {
    "code": "INVALID_SCOPE",
    "message": "This API key does not have the credentials:write scope"
  }
}

Códigos de error

Límites de solicitudes

La API externa permite 100 solicitudes por minuto por clave de API. Si excede este límite, recibirá una respuesta 429. Espere y reintente cuando el límite se restablezca.

Ejemplo de código — curl

curl -X POST https://app.certlister.com/api/v1/external/credentials \
  -H "Authorization: Bearer cl_live_su_clave_de_api" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "Jane Smith",
    "recipient_email": "jane@example.com",
    "title": "Safety Training Certificate",
    "category_id": "uuid-de-su-categoria",
    "send_email": true
  }'

Ejemplo de código — Node.js

const response = await fetch(
  "https://app.certlister.com/api/v1/external/credentials",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer cl_live_su_clave_de_api",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      recipient_name: "Jane Smith",
      recipient_email: "jane@example.com",
      title: "Safety Training Certificate",
      category_id: "uuid-de-su-categoria",
      send_email: true,
    }),
  }
);

const result = await response.json();
console.log(result.data);

Ejemplo de código — Python

import requests

response = requests.post(
    "https://app.certlister.com/api/v1/external/credentials",
    headers={
        "Authorization": "Bearer cl_live_su_clave_de_api",
        "Content-Type": "application/json",
    },
    json={
        "recipient_name": "Jane Smith",
        "recipient_email": "jane@example.com",
        "title": "Safety Training Certificate",
        "category_id": "uuid-de-su-categoria",
        "send_email": True,
    },
)

result = response.json()
print(result["data"])

Webhooks entrantes

Los webhooks entrantes permiten a los sistemas externos enviar datos a CertLister. Cuando CertLister recibe una carga de webhook, puede crear automáticamente una credencial o disparar una automatización de flujo de trabajo.

Crear un punto de acceso de webhook

1. Vaya a Integraciones → pestaña Webhooks
2. Haga clic en Crear webhook
3. Complete los detalles:
   • Nombre — una etiqueta descriptiva (p. ej., "Finalización de curso del LMS")
   • Modo — elija cómo se comporta el webhook:
     • Crear — crea automáticamente una credencial a partir de los datos entrantes
     • Disparar — activa una automatización de flujo de trabajo vinculada
4. Si es modo Crear:
   • Seleccione una categoría para las credenciales nuevas
   • Opcionalmente seleccione una plantilla de diseño
   • Active Enviar correo para notificar automáticamente a los destinatarios
5. Si es modo Disparar:
   • Seleccione la automatización a disparar
6. Configure los mapeos de campos (modo Crear) — asocie los campos del JSON entrante con los campos de la credencial
7. Haga clic en Crear

URL del webhook

Cada punto de acceso recibe una URL única:

https://app.certlister.com/api/v1/hooks/su-token-de-endpoint

Envíe una solicitud POST a esta URL con una carga JSON. CertLister la procesará según sus mapeos de campos y su modo.

Mapeos de campos

Los mapeos de campos indican a CertLister cómo extraer datos de la carga JSON entrante. Asocie las rutas JSON de la izquierda con los campos de credencial de la derecha:

Firma y verificación

Cada punto de acceso de webhook tiene un secreto de firma. Al enviar una carga, puede incluir una firma HMAC-SHA256 en el encabezado X-CertLister-Signature para que CertLister verifique que la solicitud es auténtica:

X-CertLister-Signature: <HMAC-SHA256 del cuerpo crudo de la solicitud usando el secreto de firma>

La firma es opcional — las solicitudes sin firma también se procesan, pero los registros mostrarán una advertencia de "Sin firmar". Para producción, firme siempre sus solicitudes.

Puede revelar, copiar o regenerar el secreto de firma desde la tarjeta del punto de acceso.

Probar un webhook

Haga clic en el botón de Probar en cualquier tarjeta de punto de acceso. CertLister se envía una carga de muestra a sí mismo y le muestra el resultado — si los mapeos de campos funcionan correctamente y si se crearía una credencial.

Registros del webhook

Haga clic en Ver registros en cualquier tarjeta para ver las invocaciones recientes:

Los registros se retienen para las 1,000 invocaciones más recientes por punto de acceso. Los cuerpos de solicitud se truncan a 10 KB.

Límites de solicitudes

Los webhooks entrantes están limitados a 30 solicitudes por minuto por punto de acceso. Esto previene inundaciones accidentales desde sistemas externos mal configurados.

Suscripciones a eventos

Las suscripciones a eventos le permiten recibir notificaciones cuando algo sucede dentro de CertLister. Usted se suscribe a un tipo de evento y proporciona una URL — CertLister enviará un POST con una carga firmada a su URL cada vez que ese evento se dispare.

Eventos admitidos

Crear una suscripción

1. Vaya a Integraciones → pestaña Suscripciones a eventos
2. Haga clic en Crear suscripción
3. Seleccione el tipo de evento que quiere escuchar
4. Ingrese la URL de destino — el punto de acceso HTTPS que recibirá la carga del evento
5. Haga clic en Crear

Un secreto de firma se genera automáticamente y se muestra en la pantalla de éxito. Guárdelo de forma segura — lo necesitará para verificar las cargas entrantes.

Carga del evento

Cuando un evento se dispara, CertLister envía una solicitud POST a su URL de destino con esta carga:

{
  "event": "credential.issued",
  "occurred_at": "2026-06-19T13:00:00.000Z",
  "organization_id": "uuid-de-su-org",
  "credential": {
    "id": "uuid-de-la-credencial",
    "certificate_number": "CERT-20260619-ABC123",
    "recipient_name": "Jane Smith",
    "recipient_email": "jane@example.com",
    "title": "AWS Solutions Architect",
    "issue_date": "2026-06-19",
    "expiry_date": "2027-06-19",
    "status": "active",
    "category_id": "uuid-de-la-categoria",
    "revocation_reason": null
  }
}

Encabezados

Cada entrega incluye estos encabezados:

Verificar las firmas

Para verificar que una entrega es auténtica, calcule el HMAC-SHA256 del cuerpo crudo de la solicitud con el secreto de firma de su suscripción y compárelo con el encabezado X-CertLister-Signature:

const crypto = require("crypto");

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Entrega y reintentos

CertLister reintenta las entregas fallidas hasta 3 veces con retrasos crecientes (2 segundos, 4 segundos, 8 segundos). Si todos los reintentos fallan, la entrega se registra como fallida.

Probar una suscripción

Haga clic en el botón de Probar en cualquier tarjeta de suscripción. CertLister envía un evento de prueba con datos de credencial ficticios a su URL de destino. El resultado de la entrega se registra para que verifique que su punto de acceso funciona.

Registros de entrega

Haga clic en Ver registros en cualquier tarjeta de suscripción para ver el historial:

Los registros siguen la misma política de retención que los de webhooks — las 1,000 entregas más recientes por suscripción.

Límites

Cada organización puede tener hasta 10 suscripciones a eventos. Las URL de destino deben usar HTTPS.

Conectar Zapier

Puede conectar CertLister con Zapier usando el módulo genérico "Webhooks by Zapier". No se necesita una aplicación nativa de Zapier.

Enviar datos de Zapier a CertLister

1. En Zapier, cree un nuevo Zap
2. Configure su activador (p. ej., "New Row in Google Sheets", "New Form Submission in Typeform")
3. Agregue una acción: elija Webhooks by Zapier → POST
4. Establezca la URL en su punto de acceso de webhook entrante de CertLister
5. Establezca el Payload Type en JSON
6. Mapee los campos del activador del Zap a los campos de credencial que su webhook espera
7. Pruebe y habilite

Recibir eventos de CertLister en Zapier

1. En Zapier, cree un nuevo Zap con el activador: Webhooks by Zapier → Catch Hook
2. Copie la URL del webhook de Zapier
3. En CertLister, cree una suscripción a eventos con la URL de Zapier como destino
4. Haga clic en Probar en la suscripción para enviar un evento de muestra a Zapier
5. En Zapier, pruebe el activador — debería captar el evento de muestra
6. Agregue las acciones de Zapier que desee (mensaje de Slack, actualizar hoja de cálculo, etc.)

Conectar Make (Integromat)

Enviar datos de Make a CertLister

1. En Make, cree un nuevo escenario
2. Agregue su módulo activador (p. ej., Google Sheets — Watch New Rows)
3. Agregue un módulo HTTP — Make a Request
4. Establezca la URL en su punto de acceso de webhook entrante de CertLister
5. Establezca el Method en POST
6. Establezca el Body Type en JSON
7. Mapee sus datos del activador a la estructura JSON esperada
8. Ejecute y active el escenario

Recibir eventos de CertLister en Make

1. En Make, cree un nuevo escenario con un módulo activador de Custom Webhook
2. Copie la URL del webhook de Make
3. En CertLister, cree una suscripción a eventos con la URL de Make como destino
4. Haga clic en Probar en la suscripción para enviar un evento de muestra
5. En Make, haga clic en Run once para capturar el evento de prueba
6. Agregue los módulos de acción que desee

Buenas prácticas de seguridad

• Rote las claves de API si sospecha que se comprometieron. Cree una clave nueva, actualice sus integraciones y luego revoque la anterior.
• Use los alcances mínimos necesarios. No le dé a una clave credentials:write si solo necesita leer datos.
• Configure la expiración de claves para integraciones temporales o herramientas de terceros.
• Verifique siempre las firmas de webhooks en producción para garantizar que las cargas provienen genuinamente de CertLister (o de su fuente de confianza).
• Use HTTPS en todas las URL de destino de las suscripciones a eventos.
• Guarde los secretos de forma segura — nunca suba claves de API ni secretos de firma al control de versiones.

Preguntas frecuentes

P: ¿Necesito el plan Pro para usar la API?

R: Sí. Las claves de API, los webhooks entrantes y las suscripciones a eventos son funciones exclusivas de Pro. Los usuarios de Gratuito y Basic pueden ver la página de Integraciones pero verán una invitación a actualizar a Pro.

P: ¿Puedo tener varias claves de API?

R: Sí. Puede crear tantas claves como necesite — por ejemplo, claves separadas para producción y staging, o claves distintas por integración.

P: ¿Qué pasa si mi clave de API expira?

R: Las solicitudes con una clave expirada recibirán una respuesta 401 Unauthorized. Cree una clave nueva y actualice su integración con las nuevas credenciales de acceso.

P: ¿Puedo usar el mismo punto de acceso de webhook para varios sistemas externos?

R: Técnicamente sí, pero es mejor crear puntos de acceso separados por sistema. Esto le da registros aislados, secretos de firma separados y la posibilidad de deshabilitar uno sin afectar a los demás.

P: ¿Qué pasa si el punto de acceso de mi suscripción a eventos está caído?

R: CertLister reintenta la entrega 3 veces con retrasos crecientes (2 s, 4 s, 8 s). Si todos los reintentos fallan, la entrega se registra como fallida. Puede revisar los registros de entrega para ver qué se perdió y reprocesarlo si es necesario.

P: ¿Hay un límite de credenciales que puedo crear vía API?

R: La API hace cumplir el límite de credenciales de su plan. Si alcanzó el máximo de su plan, la API devuelve una respuesta 402. Actualice su plan o elimine credenciales sin uso para continuar.

P: ¿Puedo usar los webhooks entrantes sin firma HMAC?

R: Sí — la firma es opcional. Las solicitudes sin firmar también se procesan. Sin embargo, para producción recomendamos encarecidamente firmar las solicitudes para verificar su autenticidad. Las solicitudes sin firma muestran una advertencia en los registros.

P: ¿Las suscripciones a eventos pueden disparar automatizaciones de flujo de trabajo?

R: Las suscripciones a eventos y las automatizaciones son sistemas separados. Las suscripciones notifican a sistemas externos, mientras que las automatizaciones ejecutan acciones internas (generar PDF, enviar correo, etc.). Ambas pueden responder a los mismos eventos de forma independiente.