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
| Función | Qué hace |
|---|---|
| Claves de API | Autentican las solicitudes externas a la API REST de CertLister |
| API REST | Cree, liste, actualice y revoque credenciales de forma programática |
| Webhooks entrantes | Reciba datos de sistemas externos y cree credenciales automáticamente |
| Suscripciones a eventos | Reciba notificaciones (por HTTP POST) cuando las credenciales se emiten, revocan o vencen |
| Conectar | Guías paso a paso para Zapier, Make y ejemplos de código |
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
Vaya a Integraciones → pestaña Claves de API
Haga clic en Crear clave de API
Ingrese un nombre (p. ej., "Producción", "Zapier", "Integración LMS")
Elija los permisos de la clave:
- Leer credenciales (
credentials:read) — listar y ver credenciales - Crear y actualizar credenciales (
credentials:write) — crear y editar credenciales, revocarlas y reactivarlas, los cambios en lote, los archivos y los trabajos - Eliminar y anular la emisión de credenciales (
credentials:delete) — eliminar credenciales y devolverlas a borrador - Leer categorías (
categories:read) — listar y ver categorías - Crear, editar y eliminar categorías (
categories:write) — también los cambios en lote y la generación de insignias - Leer diseños (
designs:read) — listar y ver diseños guardados, con su contenido - Definir el diseño predeterminado y eliminar diseños (
designs:write) — hacer de un diseño el predeterminado, o eliminar uno - Leer la configuración y el plan (
organization:read) — leer la configuración, el plan, el uso y el estado del dominio personalizado de la organización, y qué afectaría desactivar una función - Editar perfil, logotipo y marca (
organization:profile:write) — nombre, datos de contacto, datos y estadísticas del emisor, «Powered by», logotipo, favicon, color de marca, días y calendario de recordatorios - Editar la configuración de la página de verificación (
organization:verify:write) — slug, opciones, campos de búsqueda, diseños, etiquetas de campos, descarga de Open Badge 3.0 activada o no, nueva comprobación del dominio personalizado - Editar la numeración y los títulos predefinidos (
organization:numbering:write) - Editar la configuración de correo (
organization:email:write) — respuesta a, asunto, introducción, pie y la vista previa del correo - Activar o desactivar funciones (
organization:features:write) — tarjetas de bolsillo, insignias digitales, fila de emisión rápida - Leer borradores (
drafts:read) — listar y ver los borradores guardados - Crear, editar y eliminar borradores (
drafts:write) - Leer informes y el registro de verificación (
reports:read) — la página de Informes como datos, y el registro de cada comprobación en su página de verificación - Leer suscripciones a eventos y sus registros de entrega (
event_subscriptions:read) - Crear, editar y eliminar suscripciones a eventos (
event_subscriptions:write) — también los envíos de prueba y los nuevos secretos de firma
El diálogo agrupa los permisos bajo siete títulos. Dos botones llenan la lista por usted: Solo lectura elige todos los permisos
:ready Todo los elige todos.- Leer credenciales (
Si quiere, defina un Vencimiento
Si quiere, defina un Límite diario de emisión: el máximo de credenciales que esta clave puede emitir al día, contado desde la medianoche UTC. El valor por defecto es 1000; puede introducir de 1 a 100 000. Se define ahora y no se puede cambiar después; para cambiarlo, cree una clave nueva. La lista de claves muestra el límite de cada una.
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:
| Columna | Descripción |
|---|---|
| Nombre | La etiqueta que le dio a la clave |
| Clave | Prefijo enmascarado (primeros 16 caracteres) |
| Alcances | Etiquetas de permisos mostrando lo que la clave puede hacer |
| Último uso | Cuándo se usó por última vez |
| Creada | Cuándo se creó |
| Estado | Activa o Revocada |
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.

Como quién actúa la clave: una clave actúa como el administrador que la creó. Si esa persona ya no es administradora de la organización, cada llamada con la clave responde 401 API_KEY_OWNER_INACTIVE, y los administradores de la organización reciben un correo al respecto. Otro administrador puede asumir la clave: en la página Integraciones, abra la pestaña Claves de API y haga clic en Asumir. La pestaña Equipo le avisa antes de que quite o degrade a un administrador que creó claves.
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
Una clave solo funciona en /api/v1/external/. Enviada a las rutas de la aplicación que requieren iniciar sesión, responde 401 API_KEY_NOT_ACCEPTED_HERE con un enlace al documento OpenAPI. Una ruta desconocida bajo /api/v1/external/ responde 404 NOT_FOUND con el mismo enlace.
URL base
Todos los puntos de acceso de la API están bajo:
https://app.certlister.com/api/v1/external/
Puntos de acceso disponibles
La lista completa y siempre actualizada de puntos de acceso es el documento OpenAPI: https://app.certlister.com/api/v1/external/openapi.json. No necesita una clave para leerlo. Describe cada punto de acceso, campo, alcance y código de error.
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",
"issue_date": "2026-06-18",
"expiry_date": "2027-06-18",
"custom_attributes": {
"course_hours": "40",
"instructor": "John Doe"
},
"send_email": true
}
recipient_name es obligatorio. issue_date es la fecha de hoy si la omite. title es obligatorio, salvo que la categoría tenga un título predeterminado. category_id debe ser una de sus categorías; omítalo para no usar categoría.
Crear por la API ahora hace exactamente lo que hace emitir en la aplicación: las mismas comprobaciones, el mismo correo al destinatario y el mismo PDF o insignia automáticos cuando la categoría los activa. send_email: true envía el correo al destinatario aunque la categoría no lo enviaría; send_email: false no envía nada; si lo omite, decide la categoría. bypass_email_validation: true omite la comprobación de que el dominio del correo del destinatario puede recibir correo; úselo solo con una dirección que sabe que es correcta. La respuesta es 201, con la credencial en data y el id de la tarea de seguimiento en meta.followup_job_id.
Tres rechazos a tener en cuenta: un campo que esta API no conoce responde 400 UNKNOWN_FIELD y lo nombra (una credencial nueva no puede llevar design_id ni filas de tabla); emitir la misma credencial a la misma persona el mismo día responde 409 DUPLICATE_CREDENTIAL, con el id de la credencial existente en error.details.existing_id; un status distinto de active responde 400 STATUS_NOT_ALLOWED.
Renovar una credencial mediante la API
Para renovar, pregunte primero a quién reemplazaría la credencial nueva. Envíe POST /external/credentials/renewal-check con el email y el name de los destinatarios (hasta 100 a la vez) y, si lo conoce, el category_id en el que emitirá. No se escribe nada y no se gasta ningún crédito.
Cada resultado contiene una credential (una credencial activa o vencida de la misma persona en esa categoría, que la nueva reemplazaría) y un email_holder (otra credencial en la misma dirección de correo; nunca es un objetivo de renovación). Ambos son null cuando no se encontró nada.
Para cada resultado con una credential, cree la credencial nueva con supersedes_id igual al id de esa credencial. La anterior pasa a Reemplazada. Para un resultado sin credential, emita una credencial nueva sin supersedes_id. La comprobación de renovación necesita el alcance credentials:write.
Emitir por lotes
POST /external/credentials/batch emite hasta 100 credenciales en una sola llamada. Envíe { "rows": [ ... ] }, donde cada fila es un cuerpo que enviaría a POST /external/credentials. Un send_email opcional en el nivel superior se aplica a cada fila que no fija su propia opción de correo. Una fila no se rellena a partir de un borrador guardado: una fila con un participant_id debe llevar ella misma cada campo.
El lote funciona en dos pasos:
- Comprobación. Cada fila recibe las mismas comprobaciones que una creación individual, y CertLister busca filas que se repitan entre sí. Si se rechaza alguna fila, la respuesta es
422 BATCH_INVALID, con las filas rechazadas enerror.details.rows(indexdesde 0,code,message). No se crea nada: ninguna credencial, ningún número de credencial usado, ningún crédito gastado. Corrija las filas y envíe el lote completo de nuevo. Una fila que repite una anterior respondeDUPLICATE_IN_BATCH, ydetails.first_indexnombra esa fila anterior. - Emisión. Las filas se crean una por una, en el orden de las filas. La respuesta es
201.createdlista cada credencial porindex, yfailedlista las filas que pasaron la comprobación pero no se pudieron crear, por ejemplo un duplicado creado entre tanto por otra llamada. Las filas decreatedse mantienen.
Más de 100 filas responde 400 BATCH_TOO_LARGE. Divida una lista más larga en llamadas de 100 filas o menos. Agregue ?dry_run=true para ejecutar la comprobación sin crear nada; la respuesta es 200 con { "data": { "dry_run": true, "rows": 100 } }.
Cada credencial sigue recibiendo su propio correo al destinatario, su PDF y su insignia, según la configuración de la categoría. Al terminar el lote, el propietario de la clave recibe un solo correo de «credenciales creadas» en lugar de uno por fila.
Reintentar sin riesgo
Una llamada que agota el tiempo puede haberse ejecutado o no. Envíe un encabezado Idempotency-Key con cada llamada que crea algo o envía correo, para que un reintento nunca lo haga dos veces: POST /external/credentials, POST /external/credentials/batch, POST /external/credentials/{id}/send-email, POST /external/credentials/bulk-send-email, POST /external/jobs, POST /external/jobs/{id}/retry, POST /external/categories, POST /external/drafts y POST /external/event-subscriptions. Use un valor nuevo para cada solicitud, por ejemplo un UUID (de 1 a 255 caracteres ASCII imprimibles).
- Envíe la misma clave con la misma solicitud en un plazo de 24 horas y recibirá de nuevo la respuesta de la primera llamada, con el encabezado
Idempotent-Replayed: true. No se crea ni se envía nada por segunda vez. - «La misma solicitud» significa el mismo método, la misma ruta y exactamente los mismos bytes de cuerpo. El mismo JSON con sus claves en otro orden es otra solicitud.
- La misma clave con una solicitud distinta responde
422 IDEMPOTENCY_KEY_REUSED. - Si la primera llamada sigue en curso, el reintento responde
409 IDEMPOTENCY_IN_PROGRESSconRetry-After. Espere unos segundos y envíelo de nuevo. Si la primera llamada nunca respondió, un reintento hecho más de 90 segundos después ejecuta la solicitud otra vez. - Un
429o un5xxno se conserva, así que el reintento se ejecuta de nuevo. Una prueba en seco nunca se conserva. Las claves pertenecen a la clave de API que las envía. - Un rechazo conservado también se repite. Tras corregir lo que causó un rechazo sin cambiar el cuerpo (por ejemplo, un borrador que vuelve a estar pendiente, o un número generado que perdió una carrera poco común), envíe la llamada con una clave nueva.
Límite diario de emisión
Cada clave de API tiene un límite diario de emisión: 1000 credenciales por defecto, de 1 a 100 000, definido al crear la clave. El conteo empieza a las 00:00 UTC. Una creación individual cuenta 1; un lote cuenta todas sus filas, antes de comprobar ninguna.
Al superar el límite, la respuesta es 429 DAILY_ISSUE_LIMIT. error.details contiene limit, used, requested y resets_at, y el encabezado Retry-After indica los segundos hasta que el conteo se reinicia. Un lote que superaría el límite no crea nada. Una prueba en seco se comprueba igual pero no se cuenta, ni tampoco el reenvío de un correo. Para subir el límite, cree una clave nueva con uno más alto.
Descargar archivos
Un registro de credencial indica qué archivos existen, en files: cuatro valores verdadero o falso llamados pdf, full_pdf, wallet_card y badge. No contiene enlaces a archivos.
Para obtener un archivo, envíe GET /external/credentials/:id/files/pdf (o full_pdf, wallet_card, badge). La respuesta es { "url", "expires_at" }. El enlace funciona durante 15 minutos. Agregue ?redirect=1 para ir directamente al archivo.
Si el archivo aún no existe, la respuesta es 404 NOT_FOUND, y su mensaje explica cómo crearlo. Para el PDF, envíe POST /external/credentials/:id/generate-pdf. generate-pdf y generate-badge responden lo mismo: { "url", "expires_at" }. Una tarjeta de billetera o una insignia que su organización desactivó responde 403 FEATURE_OFF.
Administrar credenciales por la API
Edite una credencial con PATCH /external/credentials/:id. Envíe solo lo que cambia. custom_attributes se combina: los valores que envía reemplazan esas claves, una clave enviada como "" se elimina, y todos los demás valores guardados se conservan. Las filas de tabla que no envía se conservan. La edición sigue las reglas de la aplicación, así que también puede cambiar status (active, expired o revoked). Un campo que la API no puede cambiar responde 400 READ_ONLY_FIELD, y una clave desconocida responde 400 UNKNOWN_FIELD. Un PATCH debe nombrar al menos un campo. Un category_id debe pertenecer a su organización; si no, la respuesta es 400 CATEGORY_NOT_FOUND.
Revoque con POST /external/credentials/:id/revoke (un reason opcional) y reactive con POST /external/credentials/:id/reinstate. Revocar una credencial que ya está revocada no cambia nada y no dispara ningún evento. Una credencial reemplazada no se puede revocar (409 CREDENTIAL_SUPERSEDED). Reactivar solo funciona con una credencial revocada (409 NOT_REVOKED), y el nuevo estado sigue la fecha de vencimiento: expired si la fecha ya pasó, y active si no.
Dos llamadas requieren el permiso credentials:delete. Anular la emisión (POST /external/credentials/:id/unissue) devuelve una credencial emitida a borrador. Se rechaza con 409 NO_CATEGORY si la credencial no tiene categoría (envíe un category_id para resolverlo) y con 409 EMAIL_SENT si el destinatario ya recibió un correo. Eliminar (DELETE /external/credentials/:id) quita la credencial y sus archivos de forma definitiva. Su enlace de verificación deja de funcionar: quien lo tenga verá «no encontrado».
Los cambios en lote aceptan hasta 500 identificadores y cubren estado, categoría, fecha de vencimiento, eliminación y anulación de la emisión. Estado, categoría y fecha de vencimiento responden { "updated", "skipped", "not_found" }: skipped cuenta sus credenciales que el cambio dejó como estaban (por ejemplo, una credencial reemplazada), y los tres suman el número de identificadores distintos enviados. La eliminación responde { "deleted", "not_found" }, y la anulación de la emisión { "unissued", "skipped", "not_found" }, donde cada elemento de skipped tiene un id y un code. not_found lista, una sola vez cada uno, los identificadores que no son de su organización. Enviar un correo a muchos destinatarios equivale a iniciar un trabajo de correo, descrito más abajo.
Suba un PDF con PUT /external/credentials/:id/pdf como multipart/form-data, una sola parte llamada file, un PDF real de 10 MB o menos. Quite un archivo con DELETE /external/credentials/:id/files/pdf (o wallet_card, badge). Ambos responden 200 con la credencial completa. Las fotos de los destinatarios nunca pasan por la API: adminístrelas en la aplicación. Mover una credencial que tiene foto a una categoría que publica fotos responde 403 PHOTO_PUBLISHING_APP_ONLY y no mueve nada.
Historial: GET /external/credentials/:id/email-events lista lo que pasó con los correos de la credencial (enviado, entregado, rebotado, etc.), del más antiguo al más reciente. GET /external/credentials/:id/verifications lista quién verificó la credencial, del más reciente al más antiguo, por páginas. La dirección IP de cada visitante se enmascara (la última parte se reemplaza) y nunca se muestra completa.
La lista acepta los filtros de la aplicación: search, status, category_id, expiry_before, expiry_after, has_pdf, has_wallet_card, pdf_design_id, email_status, verified, además de sort y order. Un parámetro desconocido responde 400 UNKNOWN_FIELD. Para copiar los cambios a otro sistema, recorra la lista con un cursor, no con page. Envíe sort=updated_at&order=asc&per_page=100 en cada llamada, junto con updated_after (una fecha y hora con zona horaria) y after_id: el updated_at y el id de la última credencial que procesó. En la primera llamada de una ejecución, es el par que guardó al final de la ejecución anterior. En cada llamada siguiente, es el último elemento de la página que acaba de leer. Deténgase cuando una página tenga menos de 100 elementos, y guarde el par del último elemento para la próxima ejecución. Para la primera ejecución de todas, envíe updated_after=1970-01-01T00:00:00Z&after_id=00000000-0000-0000-0000-000000000000. Las credenciales cambiadas en el mismo momento nunca se omiten ni se repiten. Cualquier cambio cuenta, incluido un correo rebotado. created_after filtra por hora de creación. GET /external/credentials/summary acepta los mismos filtros y devuelve totales: por estado, por vencer en 30 días, sin PDF, con un correo fallido y nunca verificadas.
Los trabajos ejecutan una tarea sobre muchas credenciales en segundo plano. Inicie uno con POST /external/jobs, indicando un kind (pdf, badge o email) y hasta 500 credential_ids. La respuesta es 202 con el trabajo. Consúltelo con GET /external/jobs/:id hasta que su status sea succeeded, partial, failed o stopped. Vea lo que falló con GET /external/jobs/:id/failures, que da un code por credencial y como máximo 100 filas. Reintente los elementos fallidos con POST /external/jobs/:id/retry, o detenga un trabajo en curso con POST /external/jobs/:id/stop. Un trabajo que ya terminó responde 409 JOB_FINISHED. Los trabajos iniciados por la API no aparecen en la franja de trabajos de la aplicación, salvo que falle un elemento. POST /external/credentials/bulk-send-email inicia el mismo trabajo de correo.
Agregue ?dry_run=true para ejecutar todas las comprobaciones sin guardar nada. Funciona en la edición (PATCH), la revocación, la reactivación, la anulación de la emisión, la eliminación, la subida de un PDF, la eliminación de un archivo, las seis llamadas en lote y POST /external/jobs. Reintentar o detener un trabajo, la comprobación de renovación, generate-pdf, generate-badge, el envío de un solo correo (send-email) y todas las lecturas responden 400 DRY_RUN_UNSUPPORTED. Los campos y los códigos de cada llamada están en el documento OpenAPI.
Administrar categorías por la API
Todos los ajustes de una categoría se pueden leer: GET /external/categories las lista todas y GET /external/categories/:id devuelve una.
Cree una categoría con POST /external/categories y edítela con PATCH /external/categories/:id. Envíe solo lo que cambia. Elimine una con DELETE /external/categories/:id. Se rechaza con 409 CATEGORY_HAS_CREDENTIALS mientras la categoría tenga credenciales, y con 409 CATEGORY_HAS_DRAFTS mientras tenga borradores guardados. Muévalos primero, o use POST /external/categories/bulk-delete con reassign_to (el id de una categoría a la que moverlos, o null para dejar las credenciales sin categoría y eliminar los borradores). Los borradores ya emitidos también cuentan, aunque la aplicación no muestre ninguno; bulk-delete se encarga de ellos. POST /external/categories/bulk-update cambia los interruptores de automatización (send_email_on_issue, send_expiry_reminder, auto_expire) en varias categorías a la vez, enviados como { "ids", "fields" }; las dos llamadas en lote aceptan hasta 500 ids.
Agregue ?dry_run=true a una creación o a una edición para ejecutar todas las comprobaciones sin guardar nada. La respuesta es 200 con { "data": { "dry_run": true } }. Emitir una credencial o un lote y las escrituras de credenciales también la admiten (vea más arriba), igual que toda escritura de la organización (vea más abajo). El documento OpenAPI marca cada punto de acceso con x-supports-dry-run; uno marcado como falso responde 400 DRY_RUN_UNSUPPORTED.
La publicación de las fotos de los destinatarios en la página de verificación no se puede activar por la API: responde 403 PHOTO_PUBLISHING_APP_ONLY. Actívela en la aplicación, en el diálogo de confirmación de la categoría (vea Categorías). Desactivarla sí funciona por la API. Una eliminación en lote cuya categoría reassign_to publica las fotos se rechaza de la misma forma si alguna credencial que se movería tiene foto, porque el movimiento haría públicas esas fotos.
POST /external/categories/:id/generate-badges responde 202 y genera las insignias en segundo plano. Los campos y los códigos de cada punto de acceso de categorías están en el documento OpenAPI.
Administrar la configuración de la organización por la API
GET /external/organization devuelve la configuración de la organización y un bloque plan con sus límites, funciones, uso y saldo de créditos. No contiene secretos.
El método indica lo que hace la llamada. PATCH cambia algunos ajustes y deja los demás como están (perfil, marca, numeración, correo, slug, opciones de verificación, diseños, funciones y más). PUT reemplaza un valor completo (títulos predefinidos, etiquetas de campos, campos de búsqueda de verificación, logotipo, favicon). DELETE quita el logotipo o el favicon. POST /external/organization/email/preview y POST /external/organization/custom-domain/check son acciones. El documento OpenAPI lista cada ruta y los campos que acepta.
Toda escritura correcta devuelve el objeto completo de la organización, así que nunca tiene que combinar una respuesta parcial. Agregue ?dry_run=true a cualquier escritura, incluidas las dos llamadas DELETE, para ejecutar todas las comprobaciones sin guardar nada. Una prueba en seco del favicon no demuestra que la imagen se decodifique. Una prueba en seco no ve un correo ya usado por otra organización, un slug ya tomado ni una organización inexistente. Eso solo aparece en la llamada real.
Las comprobaciones son estrictas. Un campo desconocido responde 400 UNKNOWN_FIELD. Un número debe enviarse como número. Un PATCH debe nombrar al menos un campo. Las dos llamadas DELETE y la comprobación del dominio personalizado no admiten cuerpo. Una carga solo admite su parte file. Envíe true y false como booleanos, no como texto.
Numeración: envíe solo las claves que cambian. Las claves que omita conservan su valor guardado.
Suba un logotipo o un favicon como multipart/form-data con una sola parte llamada file, de menos de 2 MB. El logotipo es JPEG o PNG; el favicon es PNG. CertLister comprueba los bytes reales del archivo, no solo su nombre.
Los ajustes que requieren una función de pago responden 403 UPGRADE_REQUIRED y nombran la función. Activar la descarga de Open Badge 3.0 responde 403 FEATURE_OFF mientras Insignias digitales esté desactivado en Configuración → Funciones.
El dominio personalizado es solo estado y nueva comprobación: GET /external/organization/custom-domain y POST /external/organization/custom-domain/check. La comprobación está limitada a unas pocas llamadas cada diez minutos por organización, y un dominio pendiente se vuelve a comprobar en segundo plano cada diez minutos de todos modos, así que llame a la comprobación una sola vez después de cambiar su DNS. Definir o quitar un dominio sigue en la aplicación. Ninguna de estas llamadas cambia el diseñador de la página de verificación, el portal de destinatarios, las automatizaciones ni el correo de prueba.
Administrar borradores por la API
Un borrador es un destinatario guardado antes de emitir. GET /external/drafts lista los borradores pendientes, del más antiguo al más reciente, y GET /external/drafts/:id devuelve uno. Cree un borrador con POST /external/drafts, edítelo con PATCH /external/drafts/:id (envíe solo lo que cambia) y elimínelo con DELETE /external/drafts/:id.
Un borrador usa los mismos nombres de campo que una credencial nueva: recipient_name y category_id (ambos obligatorios al crear), recipient_email, title, description, internal_notes, custom_attributes, expiry_date (YYYY-MM-DD), send_expiry_reminder y bypass_email_validation. Un borrador conserva su categoría, así que category_id en una edición responde 400 READ_ONLY_FIELD. La respuesta incluye además table_values, las filas de las tablas de expediente. Son de solo lectura: agréguelas en la aplicación. Enviar table_values, status o cualquier otro campo que fija el sistema responde 400 READ_ONLY_FIELD. Un category_id que no es una de sus categorías responde 400 CATEGORY_NOT_FOUND. recipient_name, recipient_email y title admiten como máximo 255 caracteres. En una edición, custom_attributes se fusiona con los valores guardados, como en una credencial: las claves que envía cambian, las demás se conservan, y una clave enviada con "" se elimina.
La lista solo contiene borradores pendientes. Un borrador emitido sale de la lista, y también uno eliminado. GET /external/drafts/:id todavía lee un borrador emitido, con status: "issued" y el credential_id en que se convirtió, hasta que esa credencial se elimine. Para sincronizar, llame a la lista con updated_after (una marca de tiempo ISO 8601 con zona horaria, como 2026-11-01T00:00:00Z; una fecha sola responde 400 VALIDATION_ERROR) y relacione las filas por id. También puede filtrar por category_id. Un borrador emitido o eliminado simplemente deja de aparecer: compare con su propia copia para detectarlos. Un borrador emitido no se puede cambiar ni eliminar: responde 409 PARTICIPANT_ALREADY_ISSUED, y details.credential_id contiene el id de la credencial que debe cambiar en su lugar.
Agregue ?dry_run=true a la creación, edición o eliminación de un borrador para ejecutar todas las comprobaciones sin guardar nada.
Para emitir un borrador, envíe POST /external/credentials con participant_id igual al id del borrador. Cada campo que omita viene del borrador, como la aplicación rellena su formulario de emisión: nombre, correo, título, descripción, notas internas, categoría, fecha de vencimiento, recordatorio de vencimiento y atributos personalizados. Un campo que usted envía gana, incluso si es null. Un participant_id que no es uno de sus borradores responde 400 PARTICIPANT_NOT_FOUND. Solo un POST /external/credentials individual se rellena a partir del borrador: una fila de POST /external/credentials/batch con un participant_id debe llevar ella misma cada campo.
Consultar informes por la API
Los informes son de solo lectura y requieren el permiso reports:read. Dan las cifras de la página de Informes, en cuatro grupos:
- Verificaciones: un resumen de cuántas veces se comprobaron las credenciales, una tendencia en un rango de fechas, las credenciales más verificadas y un registro de actividad.
- Credenciales: un resumen, el desglose por estado, un pronóstico de vencimientos a 12 meses, los totales por categoría y las credenciales vencidas o que vencerán en 30 días.
- Uso: lo que contiene su organización hoy.
- Correo: resumen de entregas, embudo, desglose por resultado, destinatarios con problemas, resultados por categoría y la lista de correos enviados.
Los totales de verificaciones, la tendencia y las credenciales más verificadas excluyen los bots, como en la aplicación. El total_verifications del resumen de uso cuenta todas las comprobaciones, bots incluidos. El registro de actividad lista las comprobaciones más recientes, como máximo 200, bots incluidos y marcados con is_bot. Las direcciones IP de quienes verifican siempre van enmascaradas (203.0.113.x), nunca completas, porque una respuesta puede acabar en otra herramienta o en un chat con una IA.
Solo el resumen de verificaciones y la tendencia aceptan time_zone, un nombre IANA como America/Toronto, para cortar los días en esa zona; un nombre desconocido responde 400 VALIDATION_ERROR. Los demás informes usan el día UTC del servidor. En una cadena de consulta, envíe el + de un desfase horario como %2B, o use Z. La tendencia requiere start_date y end_date, ambas marcas de tiempo ISO 8601 con zona horaria. Las listas más largas aceptan page y per_page (hasta 100; un valor fuera de rango responde 400 VALIDATION_ERROR, como en la lista de credenciales), y el registro de actividad acepta limit (hasta 200).
Las credenciales más verificadas y el registro de actividad requieren el registro de verificaciones, y los seis informes de correo requieren el seguimiento de entrega de correos. Un plan sin esa función responde 403 UPGRADE_REQUIRED, como en la aplicación. Los campos de cada informe están en el documento OpenAPI.
Administrar diseños por la API
GET /external/designs y GET /external/designs/:id devuelven cada diseño guardado con su contenido (design_data). Haga un diseño el predeterminado con PUT /external/designs/:id/default, o elimínelo con DELETE /external/designs/:id (respuesta 204). El único diseño de la organización no se puede eliminar: responde 409 ONLY_DESIGN. Una categoría que usaba un diseño eliminado vuelve al diseño predeterminado de la organización. Un id desconocido responde 404 NOT_FOUND. Estas dos llamadas no admiten dry_run.
Los diseños se crean y se editan en Design Studio, no por la API.
Campos de solo lectura
Al crear una credencial, no puede enviar un campo que fija el sistema: id, organization_id, created_at, updated_at, y los campos de archivos y de seguimiento de correos. Enviar uno responde 400 READ_ONLY_FIELD y lo nombra.
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
GETde una credencial y de la lista devuelven los campos de la credencial. Cuando una credencial tiene filas,customizations.tableslas contiene, por clave de tabla. Cada fila es un objeto indexado por clave de columna, y una celda en blanco se omite. Las fechas sonYYYY-MM-DD. - Escritura:
POSTyPATCHno pueden fijar filas. Un campotablesocustomizationsen el cuerpo de unPOSTse rechaza con400 UNKNOWN_FIELD. UnPATCHque cambiacustom_attributesconserva 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
| Estado | Cuándo |
|---|---|
400 | Error de validación (campos requeridos faltantes, valores inválidos), o dry_run en un punto de acceso que no lo admite, o BATCH_TOO_LARGE (más de 100 filas en un lote, o más de 500 ids en una llamada en lote o un trabajo), o PARTICIPANT_NOT_FOUND (un participant_id que no es uno de sus borradores) |
401 | Clave de API inválida, expirada o revocada |
402 | El plan no incluye la función (envío de correos) |
403 | La clave de API carece del alcance requerido, o una acción que la API no permite (activar la publicación de fotos, o mover fotos a una categoría que las publica), UPGRADE_REQUIRED (un ajuste que su plan no incluye) o FEATURE_OFF |
404 | Recurso no encontrado |
409 | Duplicado: la misma credencial emitida a la misma persona el mismo día, o un número de credencial ya en uso, o una categoría que aún tiene credenciales o borradores, o un borrador ya emitido (PARTICIPANT_ALREADY_ISSUED), o el único diseño (ONLY_DESIGN), o SLUG_TAKEN o EMAIL_IN_USE en un ajuste de la organización, o CREDENTIAL_SUPERSEDED (revocar una credencial reemplazada), NOT_REVOKED (reactivar una que no está revocada), NO_CATEGORY o EMAIL_SENT (anular la emisión), JOB_FINISHED (detener un trabajo terminado), o IDEMPOTENCY_IN_PROGRESS (la primera llamada con esa Idempotency-Key sigue en curso) |
422 | BATCH_INVALID (se rechazó al menos una fila del lote y no se creó nada; una fila repetida es DUPLICATE_IN_BATCH), o IDEMPOTENCY_KEY_REUSED (la Idempotency-Key se usó para otra solicitud) |
429 | Límite de solicitudes excedido (demasiadas solicitudes), o DAILY_ISSUE_LIMIT (se alcanzó el límite diario de emisión de la clave) |
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.
Iniciar envíos de correo tiene su propio límite: 30 lotes de correo por hora por clave de API. POST /external/jobs con kind email, POST /external/credentials/bulk-send-email y el reintento de un trabajo de correo cuentan juntos. Un lote puede incluir hasta 500 credenciales. Una llamada con ?dry_run=true, o una llamada rechazada, no cuenta. Por encima del límite, la respuesta es 429 RATE_LIMITED, y Retry-After indica los segundos de espera.
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
- Vaya a Integraciones → pestaña Webhooks
- Haga clic en Crear punto de conexión
- 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)
- Para Crear credencial: elija la Categoría predeterminada y active Enviar correo electrónico al destinatario si las credenciales nuevas deben enviarse
- Para Activar automatización: elija la automatización que se ejecutará
- 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 - 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:
| Campo de la credencial | Requerido | Ruta JSON de ejemplo |
|---|---|---|
recipient_name | Sí | data.student_name |
recipient_email | No | data.email |
title | No | data.course_name |
issue_date | No | data.completion_date |
expiry_date | No | data.expiry |
| Atributos personalizados | No | data.score, data.instructor |
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:
| Campo | Descripción |
|---|---|
| Estado | Código de respuesta HTTP (200 = éxito) |
| Marca de tiempo | Cuándo se recibió el webhook |
| Tiempo de procesamiento | Cuánto tomó procesarlo |
| Credencial | Enlace a la credencial creada (si aplica) |
| Error | Mensaje de error (si falló) |

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
| Evento | Cuándo se dispara |
|---|---|
credential.issued | Se crea una credencial nueva (por la aplicación, la API o un webhook). Una importación CSV no lo envía; las automatizaciones reciben import.completed en su lugar |
credential.revoked | El estado de una credencial cambia a Revocada |
credential.expired | El estado de una credencial pasa a Vencida (mediante el trabajo diario de vencimiento) |
credential.updated | Una credencial se edita, se restablece o vuelve a borrador (se anula su emisión), en la aplicación o por la API. No se envía por cambios en masa, cambios de archivos ni una prueba en seco. Revocar editando la credencial también envía credential.revoked |
credential.superseded | Una credencial es reemplazada por una renovación |
credential.verified | Alguien comprueba una credencial en su página de verificación (al mejor esfuerzo) |
credential.expiring_soon | Una credencial activa está a 30 días o menos de su fecha de vencimiento |
Las renovaciones envían credential.superseded. Al renovar una credencial, la que sustituye pasa a Reemplazada y dispara credential.superseded. La carga contiene la credencial reemplazada, y superseded_by_id es la nueva.
El reemplazo sigue disparando credential.issued. Su carga incluye supersedes_id — la credencial que reemplazó, o null. Así puede leer una renovación en cualquiera de los dos eventos.
Para conciliar en masa, GET /external/credentials?status=superseded lista las reemplazadas.
Crear una suscripción
- Vaya a Integraciones → pestaña Suscripciones a eventos
- Haga clic en Crear suscripción
- Elija el Tipo de evento: uno de los tipos de evento de la lista
- Ingrese la URL de destino — el punto HTTPS que recibirá el evento
- 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
}
}
Qué añade cada evento
Cada carga tiene los mismos campos event, occurred_at, organization_id y credential de arriba. Algunos eventos añaden más:
credential.updatedañadechanged_fieldsyaction.changed_fieldslista lo que cambió, con los nombres de campo del objeto credencial de la API.actionesedited,reinstatedounissued. Conunissuedla credencial ya no existe: sustatusdiceunissuedy su número ya no se verifica.credential.supersededañadesuperseded_by_id, el identificador de la nueva credencial. La credencial (credential) de la carga es la que fue reemplazada.credential.verifiedañadeverification, conid,verified_at,ip_address_masked(la última parte está oculta, por ejemplo203.0.113.x) yuser_agent.credential.expiring_soonañadedays_until_expiry. Se envía cuando una credencial activa está a 30 días o menos de su fecha de vencimiento, así quedays_until_expiryva de 0 a 30. Una fecha nueva lo envía de nuevo. CertLister revisa cada hora. Cada credencial y fecha de vencimiento se envía una vez por organización, a las suscripciones activas en ese momento. Cuando una organización se suscribe por primera vez, las credenciales que ya están dentro de los 30 días llegan en unas horas; una suscripción añadida después solo recibe las credenciales que entran en la ventana después de ella.
Eventos al mejor esfuerzo
credential.verified se envía al mejor esfuerzo. Los bots quedan fuera. Cada comprobación en la página de verificación cuenta, incluidas las de su propia organización, y una búsqueda por nombre envía un evento por cada credencial que encuentra (hasta 25). Cada suscripción recibe unos 60 por minuto. Más allá de eso, los eventos se descartan. Para el registro completo, use GET /external/credentials/:id/verifications: el verification.id de un evento es el id de la misma comprobación en esa lista, que también muestra las comprobaciones hechas por bots (is_bot).
credential.updated lo envían una edición (PATCH /external/credentials/:id o la aplicación), un restablecimiento (POST /external/credentials/:id/reinstate o la aplicación) y una anulación de emisión individual (POST /external/credentials/:id/unissue o la aplicación). No se envía por cambios en masa (las llamadas bulk-* y las acciones en masa de la aplicación), por cambios de archivos (PDF, insignia, tarjeta de bolsillo) ni por una prueba en seco. Después de un cambio en masa, vuelva a listar sus credenciales. Una revocación hecha al editar la credencial (en la aplicación, o un PATCH con status revoked) envía credential.revoked y credential.updated; POST /credentials/{id}/revoke y los cambios de estado en masa envían solo credential.revoked.
Administrar suscripciones por la API
Una clave de API puede administrar suscripciones con dos permisos: event_subscriptions:read (listar, ver, registros de entrega) y event_subscriptions:write (crear, editar, eliminar, probar, nuevo secreto de firma). El secreto de firma solo se muestra al crear una suscripción o al pedir uno nuevo. Listar y ver nunca lo devuelven.
El documento OpenAPI describe cada ruta y cada carga de evento: https://app.certlister.com/api/v1/external/openapi.json.
Encabezados
Cada entrega incluye estos encabezados:
| Encabezado | Descripción |
|---|---|
Content-Type | application/json |
X-CertLister-Signature | Firma HMAC-SHA256 del cuerpo de la solicitud |
X-CertLister-Event | El tipo de evento (p. ej., credential.issued) |
X-CertLister-Delivery | ID único de esta entrega. Es el mismo en cada reintento, así que puede ignorar uno que ya procesó |
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 conserva cada entrega hasta que su dirección la acepta. Una entrega fallida se reintenta después de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas y 12 horas: 7 intentos en unas 20 horas. Si el último intento falla, la entrega se registra como fallida. Su dirección debe responder en 10 segundos; un intento más largo cuenta como fallido y se reintenta.
Una entrega puede llegar más de una vez, por ejemplo cuando su respuesta se perdió por el camino. Cada reintento lleva el mismo ID X-CertLister-Delivery, así que omita un ID que ya procesó. Si pausa o elimina una suscripción, sus entregas que esperan un reintento se descartan.
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:
| Campo | Descripción |
|---|---|
| Estado | Éxito o Fallida |
| Marca de tiempo | Cuándo se intentó la entrega |
| Evento | El tipo de evento |
| Respuesta | Código de estado HTTP de su punto de acceso |
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
- En Zapier, cree un nuevo Zap
- Configure su activador (p. ej., "New Row in Google Sheets", "New Form Submission in Typeform")
- Agregue una acción: elija Webhooks by Zapier → POST
- Establezca la URL en su punto de acceso de webhook entrante de CertLister
- Establezca el Payload Type en JSON
- Mapee los campos del activador del Zap a los campos de credencial que su webhook espera
- Pruebe y habilite
Recibir eventos de CertLister en Zapier
- En Zapier, cree un nuevo Zap con el activador: Webhooks by Zapier → Catch Hook
- Copie la URL del webhook de Zapier
- En CertLister, cree una suscripción a eventos con la URL de Zapier como destino
- Haga clic en Probar en la suscripción para enviar un evento de muestra a Zapier
- En Zapier, pruebe el activador — debería captar el evento de muestra
- 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
- En Make, cree un nuevo escenario
- Agregue su módulo activador (p. ej., Google Sheets — Watch New Rows)
- Agregue un módulo HTTP — Make a Request
- Establezca la URL en su punto de acceso de webhook entrante de CertLister
- Establezca el Method en POST
- Establezca el Body Type en JSON
- Mapee sus datos del activador a la estructura JSON esperada
- Ejecute y active el escenario
Recibir eventos de CertLister en Make
- En Make, cree un nuevo escenario con un módulo activador de Custom Webhook
- Copie la URL del webhook de Make
- En CertLister, cree una suscripción a eventos con la URL de Make como destino
- Haga clic en Probar en la suscripción para enviar un evento de muestra
- En Make, haga clic en Run once para capturar el evento de prueba
- 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:writesi 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 conserva la entrega y la reintenta 6 veces más en unas 20 horas (después de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas y 12 horas). Su dirección debe responder en 10 segundos, o el intento cuenta como fallido. Si el último intento falla, 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: No por créditos. La API requiere un plan Pro, y Pro tiene credenciales ilimitadas. Cada clave de API sí tiene un límite diario de emisión (1000 por defecto; vea Límite diario de emisión más arriba). Una respuesta 402 significa que la solicitud necesita una función que su plan no incluye. Hoy es el envío de correos en el endpoint send-email.
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.