Cómo trabajar con campos JSON en plantillas Word para generar documentos

Los campos de tipo JSON en Athento permiten almacenar información estructurada (listas, objetos o matrices) dentro de un metadato. Estos campos son muy útiles cuando necesitamos imprimir tablas dinámicas o listas de elementos en plantillas Word, como contratos, facturas, listados de arrendatarios, o cuotas de pago.

⚙️ Cómo Athento interpreta los campos JSON

Cuando Athento procesa una plantilla Word mediante el DocxParser, los metadatos de tipo JSON se convierten automáticamente en diccionarios o listas de Python, de modo que en el contexto Jinja pueden recorrerse con bucles for o accederse por clave.

Por ejemplo, si el metadato metadata_arrendatarios tiene este valor:

{
 "arrendatarios": [
   {
     "nombre": "Juan Pérez",
     "tipo_documento": "DNI",
     "numero_documento": "12345678A"
   },
   {
     "nombre": "Ana López",
     "tipo_documento": "Pasaporte",
     "numero_documento": "X1234567"
   }
 ]
}

Athento pasará este valor al contexto como un objeto Python, accesible desde la plantilla como:

metadata_arrendatarios.arrendatarios

🧱 Estructura básica en una plantilla Word

Para recorrer los datos de un JSON en Word debes:

1️⃣ Abrir un bucle que recorra los elementos
2️⃣ Imprimir las propiedades dentro de una tabla o párrafo
3️⃣ Cerrar el bucle

📄 Ejemplo de tabla repetitiva (Word)

En una tabla de Word con tres columnas:

👉 Notas importantes:

• Las etiquetas {%tr for ... %} y {%tr endfor %} deben ir dentro de filas de Word, no fuera.

• Solo la fila con los valores {{ arr.* }} se repetirá.

• Los nombres de las claves (nombre, tipo_documento, etc.) deben coincidir exactamente con los del JSON.

💡 Cómo acceder a niveles más profundos

Si el JSON tiene subniveles, puedes acceder con notación de punto o de índice.
Por ejemplo:

{
  "contratos": [
    {
      "ContractId": "AA123",
      "Instalment": [
        {"date": "20230627", "amount": "329.98"}
      ]
    }
  ]
}

Se recorre así:

{% for contrato in metadata_contratos.contracts %}
Contracto: {{ contrato.ContractId }}
{% for pago in contrato.Instalment %}
Fecha: {{ pago.date }} - Importe: {{ pago.amount }}
{% endfor %}
{% endfor %}

🧩 Combinación con condiciones

Puedes combinar bucles y condiciones:

{% for arr in metadata_arrendatarios.arrendatarios %}
{% if arr.tipo_documento == 'DNI' %}
Arrendatario español: {{ arr.nombre }}
{% endif %}
{% endfor %}

También puedes transformar o formatear valores:

{{ arr.nombre|upper }}
{{ pago.amount|float|round(2) }}

🧰 Consejos prácticos

• Verifica que el metadato sea realmente de tipo JSON. Si se crea como texto, no podrás usar notación de punto.

• El JSON debe estar bien formado, con comillas dobles (") y estructura válida.

• Si no imprime nada, revisa que el nombre del campo (metadata_micampo) coincida con el slug del metadato en Athento.

• No uses comillas tipográficas (“ ”) ni paréntesis en filtros.

• Si los datos no se muestran, imprime temporalmente su tipo para depurar:

  {{ metadata_arrendatarios.__class__ }}
  

Si el resultado es <class 'dict'> o <class 'list'>, el JSON está siendo interpretado correctamente.
Si aparece <class 'docxtpl.listing.Listing'>, significa que el metadato no es de tipo JSON.

🧪 Depuración avanzada

Puedes imprimir parte del contenido del JSON directamente para comprobar su estructura:

{{ metadata_arrendatarios }}

o ver cuántos elementos contiene:

{{ metadata_arrendatarios.arrendatarios|length }}

Si necesitas filtrar elementos, puedes usar expresiones Jinja más avanzadas:

{% for arr in metadata_arrendatarios.arrendatarios if arr.tipo_documento == 'DNI' %}
{{ arr.nombre }}
{% endfor %}

✅ Resumen rápido

🧭 Conclusión

Los campos JSON permiten generar plantillas dinámicas y repetitivas sin necesidad de duplicar metadatos.
Al entender que el parser convierte el valor en una lista o diccionario, puedes usar toda la potencia de Jinja para recorrer, filtrar y mostrar información estructurada dentro de tus documentos Word.