Atributos de credencial personalizados

Tiempo de lectura: 8 minutos

Descripción general

Los atributos de credencial personalizados permiten adjuntar campos de datos específicos de su dominio a las credenciales a nivel de categoría. Defina campos como "Calificación", "Instructor", "Horas de capacitación" o "Número de permiso" — y complételos para cada destinatario. Los valores aparecen en los PDF generados y en la página pública de verificación.

Casos de uso de ejemplo:

• Un centro de capacitación en Python agrega los campos "Calificación" e "Instructor" a su categoría "Capacitación en Python"
• Un certificador de seguridad alimentaria agrega "Número de permiso" y "Autoridad emisora" a su categoría de cumplimiento
• Una organización de fitness agrega "Horas completadas" y "Nombre del entrenador" a cada certificación

Requiere: plan Pro

Cómo funciona

Los atributos personalizados siguen un flujo de cuatro pasos:

1. Defina los campos en una categoría (administrador, plan Pro)
2. Ingrese los valores al crear o editar credenciales individuales
3. Coloque los tokens en su diseño de credencial para imprimir los valores en los PDF
4. La página de verificación muestra los valores públicamente cuando alguien consulta una credencial

Parte 1: definir campos personalizados en una categoría

Requiere: rol de administrador y plan Pro

Paso 1: vaya a Categorías

1. Inicie sesión en CertLister en https://app.certlister.com
2. Haga clic en Categorías en la navegación izquierda

Paso 2: abra el diálogo de campos personalizados

1. Encuentre la categoría a la que quiere agregar campos
2. Haga clic en el icono de controles deslizantes en la fila de esa categoría — abre el diálogo de campos personalizados
3. Si su organización está en el plan Gratuito o Basic, verá un icono de candado y un botón de actualización en lugar del editor de campos

Paso 3: agregue los campos

1. Haga clic en Agregar campo
2. Complete las tres propiedades de cada campo:

3. Agregue tantos campos como necesite — no hay límite
4. Haga clic en Guardar campos al terminar

Configuración de ejemplo para una categoría "Capacitación en Python":

Importante: renombrar o eliminar claves de campo

Una advertencia aparece en el diálogo si renombra o elimina una clave que ya tiene valores guardados en credenciales existentes. Cambiar la clave no elimina los datos almacenados — pero los valores no se mostrarán hasta restaurar la clave original. Renombre las claves con cuidado y solo antes de que se hayan creado credenciales en esa categoría.

Parte 2: ingresar valores al crear una credencial

Una vez que una categoría tiene campos personalizados, estos aparecen automáticamente en los diálogos de Agregar credencial y Editar cuando se selecciona esa categoría.

Crear una credencial con campos personalizados

1. Vaya a Credenciales → clic en Agregar credencial (o Importar para lotes)
2. Complete los campos estándar (nombre del destinatario, título, fechas)
3. Seleccione una categoría con campos personalizados definidos
4. Los campos personalizados aparecen debajo de la sección estándar — complételos
5. Los campos requeridos están marcados con asterisco (*) y deben completarse antes de guardar
6. Haga clic en Guardar

Editar credenciales existentes

1. Abra una credencial que pertenezca a una categoría con campos personalizados
2. Haga clic en Editar
3. Los campos personalizados aparecen con los valores previamente guardados
4. Actualice los valores según necesite y guarde

Nota: agregar campos personalizados a una categoría no completa retroactivamente los valores de credenciales existentes. Puede editar cada credencial individualmente para agregarlos, o reimportar con un CSV que incluya las columnas adicionales (vea la Parte 5).

Parte 3: usar tokens en los diseños de credencial

Los tokens de atributos personalizados siguen el formato {{custom.fieldkey}}. Colóquelos en el Estudio de diseño para imprimir los valores personalizados en los PDF generados.

Paso 1: abra el Estudio de diseño

1. Haga clic en Estudio de diseño en la navegación izquierda
2. Abra el diseño que quiere actualizar — o cree uno nuevo

Paso 2: encuentre los tokens de campos personalizados en el panel de Atributos

1. Haga clic en el icono de Atributos en la barra izquierda
2. Baje hasta la sección Campos personalizados en el panel de selección
3. Sus tokens aparecen como botones clicables — uno por cada clave única, entre todas las categorías de su organización
4. Si dos categorías tienen un campo con la misma clave pero etiquetas distintas (p. ej., "Calificación" en una y "Puntaje" en otra), ambas etiquetas se muestran combinadas en el botón

Paso 3: agregue un token al lienzo

• Haga clic en el botón del token para agregarlo al lienzo en una posición predeterminada
• Arrastre el botón directamente al lienzo para colocarlo exactamente donde quiera
• Dé estilo al token como a cualquier elemento de texto: fuente, tamaño, color, alineación

Paso 4: guarde el diseño

Haga clic en Guardar arriba a la derecha. El diseño queda listo para generar PDF con los valores personalizados.

Al generar:

• {{custom.score}} → se reemplaza con la calificación real de cada destinatario (p. ej., "92%")
• {{custom.instructor}} → se reemplaza con el nombre del instructor (p. ej., "Dr. Smith")
• Si una credencial no tiene valor para un token, este se reemplaza con una cadena vacía (espacio en blanco)

Parte 4: atributos personalizados en la página pública de verificación

Cuando alguien consulta una credencial en su página pública de verificación, aparece una sección de Detalles adicionales debajo de la información estándar — pero solo si la credencial tiene valores de atributos personalizados y su organización está en el plan Pro.

Ejemplo de lo que ven los visitantes:

Detalles adicionales

Calificación           92%
Instructor             Dr. Smith
Horas de capacitación  16 horas

Solo se muestran los campos que tienen un valor guardado. Los campos sin valor se omiten. Las direcciones de correo, las notas internas y otros datos privados nunca se exponen en la página de verificación.

Parte 5: importar atributos personalizados por CSV

Al importar credenciales por CSV, cualquier columna que no sea un campo estándar de CertLister se trata automáticamente como atributo personalizado. Sin configuración adicional.

Cómo funciona

Campos estándar que el importador reconoce: Credential Number, Title, Recipient Name, Recipient Email, Issue Date, Expiry Date, Status, Category

Cualquier nombre de columna fuera de esta lista se mapea a {{custom.columnname}}. Por ejemplo, una columna llamada score se convierte en {{custom.score}} en los PDF generados.

CSV de ejemplo

Credential Number,Title,Recipient Name,Recipient Email,Issue Date,Expiry Date,Status,Category,score,instructor
,Python Training,Sarah Johnson,sarah@email.com,2026-01-15,2027-01-15,active,Python Training,92%,Dr. Smith
,Python Training,Michael Chen,mchen@company.com,2026-01-15,2027-01-15,active,Python Training,87%,Dr. Smith

Las columnas score e instructor se guardan como valores de atributos personalizados y se representarán en los PDF mediante los tokens {{custom.score}} y {{custom.instructor}}.

Notas:

• Los nombres de columna del CSV se usan tal cual como clave del atributo. Manténgalos en minúsculas y sin espacios para que coincidan con las claves de campo de su categoría.
• El importador no valida las columnas personalizadas del CSV contra el esquema definido en la categoría. Los valores se almacenan de todos modos.
• El esquema de la categoría (definido en el diálogo de campos personalizados) controla los nombres visibles, la validación de campos requeridos y la resolución de tokens — no la importación.

Más información: importación masiva de credenciales desde CSV

Solución de problemas

El diálogo de campos personalizados muestra un candado

Causa: su organización está en el plan Gratuito o Basic. Los atributos personalizados requieren Pro.

Solución: actualice en https://app.certlister.com/billing

Los campos personalizados no aparecen en el diálogo de credencial

Verifique:

1. Seleccionó una categoría con al menos un campo definido — abra la página de Categorías, busque la categoría, haga clic en el icono de controles deslizantes y confirme que hay campos
2. Su organización está en el plan Pro
3. Está seleccionando la categoría antes de buscar los campos (los campos cargan al seleccionar la categoría)

Un token del PDF se muestra como {{custom.score}} en lugar del valor real

Causas y soluciones:

La página de verificación no muestra los atributos personalizados de una credencial

Verifique:

• Su organización está en el plan Pro (la API no devuelve atributos personalizados para organizaciones sin Pro)
• La credencial tiene al menos un valor de atributo personalizado guardado (edite la credencial para confirmar)
• La clave del atributo en la respuesta de verificación coincide con el esquema de la categoría

La vista previa del diseño muestra [score] en lugar del valor real

Es lo esperado. La vista previa del lienzo no tiene datos reales de credencial. Los tokens personalizados se muestran como [fieldkey] en la vista previa para indicar que el token es reconocido. El valor real se sustituye al generar el PDF.

Preguntas frecuentes

P: ¿Cuántos campos personalizados puedo agregar por categoría?

R: No hay límite.

P: ¿Categorías distintas pueden tener campos personalizados distintos?

R: Sí — cada categoría tiene su propio esquema de campos independiente. "Capacitación en Python" puede tener Calificación e Instructor; "Seguridad alimentaria" puede tener Número de permiso y Región de vencimiento. Son completamente separados.

P: ¿Qué pasa con las credenciales existentes cuando agrego campos nuevos a una categoría?

R: Las credenciales existentes no se ven afectadas. Los campos nuevos aparecen en blanco para las existentes. La validación de campos requeridos aplica solo al crear credenciales nuevas — editar una existente mostrará el campo nuevo pero no lo obligará a completarlo.

P: ¿Puedo usar la misma clave de token en varias categorías?

R: Sí. El Estudio de diseño combina todas las claves únicas de todos los esquemas de categoría en una sola lista en el panel de Atributos. Un token como {{custom.score}} en su diseño se resolverá con el valor de la categoría a la que pertenezca cada credencial específica.

P: ¿Los valores de atributos personalizados se pueden buscar en la lista de credenciales?

R: Actualmente no. La búsqueda funciona por nombre del destinatario, número de credencial y título.

P: ¿Los valores de atributos personalizados se pueden exportar a CSV?

R: Actualmente no. La exportación CSV estándar incluye solo los campos centrales. La exportación de atributos personalizados podría agregarse en una actualización futura.

P: ¿Los atributos personalizados funcionan con el generador SVG heredado?

R: Sí. El generador SVG heredado también resuelve los tokens {{custom.key}} cuando aparecen en una plantilla SVG.

P: ¿Qué pasa con los datos de atributos personalizados si bajo de Pro a Basic?

R: Los valores almacenados permanecen en la base de datos. Sin embargo, la página de verificación dejará de mostrar la sección de Detalles adicionales, y el diálogo de campos personalizados mostrará un candado. Los valores se restauran de inmediato si vuelve a Pro.