Identificadores internos de campos para reportes, exportaciones, Workflows y payloads REST.

Audiencia: Admin · Desarrollador

Cada campo del Form Builder tiene dos nombres:

Etiqueta — lo que lee el usuario en móvil (puedes cambiarla cuando quieras).
Clave de campo — identificador interno estable usado por reportes, exportaciones Excel, Workflows y la API REST.

Trata las claves como nombres de columna en base de datos.

Dónde aparecen las claves

Consumidor	Usa la clave para
Reportes de formulario	Encabezados y filtros de columnas
Exportación Excel	Fila de encabezado en `.xlsx`
Workflows	Condiciones sobre respuestas en `form_submitted`
API REST	Nombres de propiedad JSON en objetos de envío
Integraciones	Campos del payload webhook

Si renombras una clave después del go-live, envíos históricos conservan la clave antigua; los nuevos usan la nueva. Los reportes parecen "vacíos" en la transición salvo que fusiones columnas a mano.

Definir claves en Form Builder

Al agregar un campo:

Define una clave corta y descriptiva en inglés o snake_case (qty_delivered, defect_code).
Evita espacios, tildes y caracteres especiales—algunas herramientas de exportación normalizan mal.
No reutilices una clave con significado distinto más adelante.

Chekku puede auto-generar claves desde etiquetas al primer guardado—revísalas antes de publicar.

Claves vs. etiquetas visibles

Etiqueta (ejemplo ES)	Buena clave	Mala clave
Cantidad entregada	`qty_delivered`	`Cantidad entregada`
Código de falla	`failure_code`	`field_7`

Las etiquetas pueden localizarse; las claves no deberían.

Acceso vía API

Clientes REST autenticados obtienen envíos con objetos de respuesta anidados por clave de campo. Consulta esquemas en docs de la API de Chekku.

Patrón típico:

{
  "visitId": "...",
  "formId": "...",
  "answers": {
    "qty_delivered": 12,
    "failure_code": "F003"
  }
}

Campos Lista almacenan la columna valor de la Fuente de datos, no necesariamente la etiqueta mostrada.

Grupos repetibles

Secciones repetibles prefijan o anidan claves por instancia (items[0].sku). Revisa docs API para tu versión de formulario—la estructura varía por tipo de campo.

Checklist de migración

Si debes cambiar una clave:

Congela versión de formulario o publica formulario nuevo con clave nueva.
Actualiza reportes, modelos BI y condiciones de Workflow.
Corre exportaciones paralelas clave antigua vs. nueva una semana.
Comunica fecha de corte a responsables de integraciones.

Preferible no cambiar claves—actualiza etiquetas (Errores comunes).

Consejos

Mantén un diccionario de datos: clave, etiqueta, tipo, lista origen.
Usa prefijos consistentes por formulario (audit_, delivery_) si las claves pueden chocar en reportes cruzados.
Columnas Protegidas de Fuente de datos también mapean a claves—cuidado con PII en respuestas API.

Claves de campo y API