Esquema de datos y datos predeterminados

El esquema de una plantilla define los campos que acepta y sus tipos. Los datos predeterminados dan valores a la vista previa del editor y a los campos que no se incluyen en una solicitud de generación de documentos.

Por ejemplo, una plantilla de factura puede definir el nombre del cliente, el número de factura y una colección de partidas. Los datos predeterminados te permiten diseñar la factura con valores realistas antes de conectar tu aplicación.

Abre las herramientas de datos

Abre una plantilla en el editor y selecciona Campos de datos en el inspector de la derecha. Este panel muestra tus campos y tiene dos botones:

Editar esquema abre el Editor de campos, donde defines la estructura de los datos.
Datos predeterminados abre los valores que se usan para la vista previa y para completar los datos omitidos.

Después de definir los campos, arrástralos desde Campos de datos hasta elementos de texto o encabezados de tabla para vincularlos al diseño.

Esquema

Define los campos

Haz clic en Editar esquema y selecciona la pestaña Campos.
Haz clic en Agregar campo, escribe un nombre y elige su tipo.
Para un objeto o una colección, usa Agregar hijo para definir los campos que contiene.
Haz clic en Aplicar cambios cuando el esquema esté listo.

Los nombres de los campos se convierten en claves de tu entrada JSON. Usa letras, números y guiones bajos, y empieza con una letra o un guion bajo: customer_name es válido; customer name y 1customer no lo son. Los nombres deben ser únicos dentro del mismo elemento padre, por lo que pueden existir tanto customer.name como company.name.

Puedes buscar campos por nombre, arrastrar sus controles para reordenarlos dentro de un elemento padre y deshacer o rehacer cambios mientras el Editor de campos está abierto. Cancelar cierra el diálogo sin aplicar los cambios.

Elige los tipos de campo

Tipo	Para qué sirve
Cadena	Texto como nombres, direcciones o descripciones.
Número	Cantidades, precios, porcentajes y otros valores numéricos. Envía números JSON como `2` o `19.95`, en lugar de texto entre comillas.
Booleano	Un valor `true` o `false`, por ejemplo, si una factura está pagada.
Fecha	Una fecha del calendario como `"2026-10-01"`.
Fecha/hora	Una marca de tiempo como `"2026-10-01T09:30:00Z"`.
Objeto	Un grupo de campos relacionados, como un cliente con nombre y dirección.
Colección	Un arreglo de objetos con los mismos campos, como las partidas de una factura.
Lista de cadenas, números, booleanos, fechas o fechas/horas	Un arreglo de valores simples del mismo tipo, como `["priority", "paid"]`.
Número calculado	Un resultado numérico calculado a partir de una colección o lista del mismo elemento padre. Esta opción aparece cuando existe una fuente adecuada.

La plantilla calcula los campos calculados. No aparecen en el esquema JSON de entrada ni en el formulario de Datos predeterminados, por lo que no necesitas enviarlos.

Organiza los datos anidados

Usa objetos para agrupar campos y colecciones para registros que se repiten. Para una factura sencilla, crea esta estructura:

invoice                  Objeto
|-- number               Cadena
|-- currency             Cadena
`-- items                Colección
    |-- description      Cadena
    |-- quantity         Número
    `-- unit_price       Número

Cada elemento de invoice.items es un objeto con sus propios valores de description, quantity y unit_price. Usa una colección cuando una tabla o un diseño repetido necesite varios campos por elemento. Usa una lista cuando cada elemento sea un solo valor.

Cuando cambias el nombre de un campo, el editor actualiza sus referencias en el diseño y conserva su valor predeterminado con el nuevo nombre. Si eliminas un campo que se usa en el diseño, te pide confirmar la eliminación de sus referencias. Revisa la vista previa después de cambiar el esquema, especialmente si cambias los tipos de campo.

Exporta el esquema JSON

En el Editor de campos, selecciona Esquema JSON y haz clic en Copiar para compartir la estructura de entrada con tu integración. Esta vista es de solo lectura y se genera a partir de los campos actuales; cambia la pestaña Campos para modificarla.

El esquema exportado describe objetos anidados, arreglos y tipos de campo. Los campos de entrada son opcionales porque los valores omitidos usan los datos predeterminados de la plantilla. Los campos calculados se excluyen y no se permiten claves adicionales fuera del esquema.

Datos predeterminados

Edita los valores predeterminados

Abre Datos predeterminados desde el panel Campos de datos. Elige la vista que prefieras:

Constructor ofrece controles para cada campo. Usa Agregar elemento para las colecciones y Agregar valor para las listas. Puedes duplicar o eliminar los elementos de una colección.
JSON te permite pegar o editar el objeto de datos completo. Formatear JSON aplica formato al JSON válido sin cambiar sus valores.

Para el esquema de factura anterior, escribe:

{
  "invoice": {
    "number": "INV-1042",
    "currency": "USD",
    "items": [
      {
        "description": "Design services",
        "quantity": 2,
        "unit_price": 50
      }
    ]
  }
}

El editor comprueba los datos con tu esquema. Corrige los errores de JSON o de tipo hasta que aparezca Coincide con el esquema, y haz clic en Aplicar cambios.

Restablecer desde el esquema reemplaza los datos predeterminados que editaste por valores generados a partir del esquema. Úsalo cuando quieras empezar de nuevo y revisa los valores generados antes de aplicarlos. Puedes deshacer y rehacer cambios en el Constructor; estos controles están desactivados en la vista JSON.

Cómo los datos de la solicitud reemplazan los valores predeterminados

Cuando generas un documento, los valores que envías reemplazan los datos predeterminados de la plantilla. Los objetos anidados se combinan, por lo que puedes enviar solo los campos que quieres cambiar.

Con los datos predeterminados anteriores, esta entrada cambia el número de factura y conserva currency e items:

{
  "invoice": {
    "number": "INV-1043"
  }
}

Las colecciones y listas se reemplazan como arreglos completos, sin combinar sus elementos uno a uno. Enviar "items": [] produce una colección vacía; no reutiliza los elementos predeterminados. Los valores enviados como 0, false o una cadena vacía también reemplazan los predeterminados. Un null enviado no usa el valor predeterminado y puede fallar la validación de tipo.

Elige valores predeterminados que quieras incluir cuando se omita un campo, ya que afectan tanto a los PDF generados como a las vistas previas.

Guarda, revisa y publica

Aplicar cambios actualiza el editor abierto. Guarda la plantilla para conservar tus cambios y usa Ver vista previa del PDF para comprobar el diseño con sus datos predeterminados.

Publica la plantilla cuando esté lista para generar documentos. Los cambios de esquema y datos predeterminados llegan a las solicitudes de generación cuando publicas una nueva revisión; editar un borrador no cambia la revisión publicada existente.

Próximos pasos

Vincula campos a los elementos y controla cómo aparecen sus valores en Vinculaciones de campos de datos y formato.
Descubre cómo se relacionan las plantillas, revisiones y vinculaciones de datos en Conceptos.
Genera un PDF con tu plantilla publicada usando el inicio rápido.
Consulta el esquema de datos de una plantilla en la referencia de la API o crea plantillas con MCP.