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). Las automatizaciones cubren el lado interno de los mismos eventos — vea la página de automatizaciones de flujo de trabajo.

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. Elija los permisos de la clave:
   • Leer credenciales (credentials:read) — listar y ver credenciales
   • Crear y actualizar credenciales (credentials:write) — crear, actualizar y revocar credenciales
   • Leer categorías (categories:read) — listar y ver categorías
   • Leer diseños (designs:read) — listar y ver diseños guardados
5. Si quiere, defina un Vencimiento
6. Haga clic en Crear clave de API

Importante: la clave completa se muestra solo una vez después de crearla. Cópiela de inmediato y guárdela en un lugar seguro — no podrá volver a verla. CertLister solo guarda 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 eliminar una clave: haga clic en el icono de papelera de su fila y confirme Eliminar clave de API. La clave deja de funcionar de inmediato — cualquier sistema que la use recibe respuestas 401 Unauthorized.

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.

Filas de tabla

Una categoría puede tener campos de tabla, como una lista de cursos con horas y fechas (consulte Categorías). Las filas de cada persona se guardan con la credencial, aparte de los atributos personalizados.

• Lectura: los puntos de acceso GET de una credencial y de la lista devuelven la credencial tal como está guardada. Cuando una credencial tiene filas, customizations.tables las contiene, por clave de tabla. Cada fila es un objeto indexado por clave de columna, y una celda en blanco se omite. Las fechas son YYYY-MM-DD.
• Escritura: POST y PATCH no pueden fijar filas. Un campo tables en el cuerpo se ignora. Un PATCH que cambia custom_attributes conserva las filas que la credencial ya tiene. Para agregar o cambiar filas, use la aplicación o una importación CSV.

"customizations": {
  "custom": { "course_hours": "40" },
  "tables": {
    "courses": [
      { "course": "Workplace safety", "hours": "8", "completed": "2026-09-14" },
      { "course": "First aid", "hours": "4", "completed": "2026-09-21" }
    ]
  }
}

Las filas se pueden leer con cualquier clave de API que tenga el alcance credentials:read. Nunca se muestran en su página de verificación.

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 punto de conexión
3. Complete los datos:
   • Nombre — una etiqueta descriptiva (p. ej., "Finalización de curso LMS")
   • Modo — Crear credencial (crea una credencial con los datos recibidos) o Activar automatización (ejecuta una de sus automatizaciones)
4. Para Crear credencial: elija la Categoría predeterminada y active Enviar correo electrónico al destinatario si las credenciales nuevas deben enviarse
5. Para Activar automatización: elija la automatización que se ejecutará
6. En Asignaciones de campos, asigne los campos del JSON recibido (p. ej., data.name) a los campos de la credencial — el nombre del destinatario es obligatorio
7. Haga clic en Crear punto de conexión

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

Las renovaciones no tienen un evento propio. Al renovar una credencial, el reemplazo dispara credential.issued, y la credencial que sustituye pasa a Reemplazada sin un evento propio.

Aun así puede actuar solo con el evento: el contenido de cada credencial incluye supersedes_id — la credencial que esta reemplazó, o null. Un evento credential.issued con un supersedes_id no nulo es la señal de renovación, y ese identificador le indica qué credencial marcar como ya no vigente.

Para conciliar en masa, GET /external/credentials?status=superseded lista las reemplazadas.

Crear una suscripción

1. Vaya a Integraciones → pestaña Suscripciones a eventos
2. Haga clic en Crear suscripción
3. Elija el Tipo de evento: Credencial emitida, Credencial revocada o Credencial vencida
4. Ingrese la URL de destino — el punto HTTPS que recibirá el evento
5. Haga clic en Crear suscripción

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",
    "supersedes_id": null,
    "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.

La pestaña Conectar reúne los mismos pasos de configuración, notas para Zapier y Make, y ejemplos de código en curl, Python y Node.js.

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. En Gratuito y Basic puede abrir la página de Integraciones y leer las cuatro pestañas — las listas quedan vacías y cada botón de creación le pide actualizar el plan.

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.