¿Cuándo debo usar Template Render en lugar de JSON Render?

Use Template Render después de aprobar el diseño y cuando los clientes solo deban enviar datos empresariales.

¿template_id es estable?

Sí. La documentación de la API de plantillas describe `template_id` como el identificador estable visible para quien llama.

¿Una solicitud puede renderizar varios elementos de datos?

Sí, Template Render acepta un array `data` dentro de los límites públicos del endpoint.

¿Template Render puede crear facturas electrónicas?

No. El empaquetado Factur-X y ZUGFeRD PDF/A-3b usa el endpoint E-Invoice Render.

Flujos para desarrolladores

API de PDF con plantillas para contratos de documento estables

Renderice PDF desde un `template_id` estable y un array `data` cuando los diseños repetidos deban definirse una vez y reutilizarse por clientes ERP, OMS, WMS o SaaS.

API PRINCIPAL Template Render

ENDPOINT /api/v1/template-render

SISTEMAS backend SaaS / integración ERP / OMS / WMS / cola de trabajos

Probar en Playground Leer la documentación

Trabajo a resolver

Renderizar PDF repetidos enviando un `template_id` estable y un array de datos empresariales, en lugar de pedir a cada cliente que describa páginas, coordenadas y elementos de diseño en cada solicitud.

Cuándo usar esta API

El diseño del documento está aprobado y se reutiliza por varios clientes o trabajos.
Los clientes deben enviar datos empresariales, no JSON de diseño a nivel de coordenadas.
Necesita facturas, packing lists, etiquetas de envío o salida de plantillas personalizadas.
Quiere que las revisiones activas de plantilla se controlen fuera del cliente.

Qué no sustituye

Todavía está diseñando la composición. Use JSON Render hasta estabilizar coordenadas y campos.
Necesita conversión HTML-to-PDF arbitraria.
Necesita empaquetado de factura electrónica PDF/A-3b con XML CII incrustado.

Qué endpoint llamar

PRINCIPAL

/api/v1/template-render

Template Render es la ruta predeterminada para este flujo.

SECUNDARIO 1

/api/v1/pdf/render

Úsalo cuando el flujo necesite la ruta API relacionada, un contrato de plantilla o una consulta de capacidades.

Solicitud mínima

POST /api/v1/template-render - renderizar una factura desde una plantilla.

{
  "template_id": "invoice",
  "data": [
    {
      "invoice_number": "INV-2026-001",
      "date_of_issue": "2026-05-29",
      "date_due": "2026-06-28",
      "issuer_name": "Acme Cloud Inc.",
      "issuer_address": "88 Harbor Rd, Long Beach, CA",
      "bill_to_name": "Receiver Inc.",
      "bill_to_address": "123 Main St, Los Angeles, CA",
      "subtotal": "$100.00",
      "total": "$100.00",
      "amount_due": "$100.00",
      "items": [
        {
          "description": "Service A",
          "qty": 1,
          "unit_price": "$100.00",
          "amount": "$100.00"
        }
      ]
    }
  ]
}

Qué gestiona gPdf

Búsqueda de plantilla por `template_id` estable.
Renderizado de cada elemento de `data` contra la plantilla activa.
Concatenación de páginas renderizadas en un solo PDF dentro de los límites públicos del endpoint.
Comportamiento compartido de autenticación, ID de solicitud y envoltorio de errores.

Qué controla su sistema

Selección de plantilla, mapeo de campos, datos empresariales y autorización del cliente.
Flujo de publicación de plantillas, comunicación de cambios y cobertura de pruebas.
Particionado, colas y reintentos al renderizar muchos documentos.

Checklist de producción

Trate `template_id` como un contrato opaco y estable.
Valide campos de datos antes de llamar a Template Render.
Mantenga pruebas golden-PDF para la plantilla activa y datos representativos.
Divida lotes grandes de acuerdo con los límites públicos de Template Render.
Registre `template_id`, ID de solicitud e IDs de objetos empresariales para trazabilidad.

Límites de la promesa

Template Render no es por sí mismo una herramienta de diseño; las plantillas ya deben estar publicadas.
gPdf no infiere datos empresariales faltantes desde la plantilla.
Template Render no sustituye el endpoint E-Invoice Render.

Template Render es la capa de contrato de producción

JSON Render es ideal mientras se diseña la composición. Template Render es la capa que debe usarse cuando el diseño se convierte en un contrato. Los clientes envían template_id y datos; la plantilla activa controla la estructura del documento.

Esto reduce el tamaño de los clientes y facilita revisar, probar y desplegar cambios de plantilla.

FAQ

¿Cuándo debo usar Template Render en lugar de JSON Render?: Use Template Render después de aprobar el diseño y cuando los clientes solo deban enviar datos empresariales.
¿template_id es estable?: Sí. La documentación de la API de plantillas describe `template_id` como el identificador estable visible para quien llama.
¿Una solicitud puede renderizar varios elementos de datos?: Sí, Template Render acepta un array `data` dentro de los límites públicos del endpoint.
¿Template Render puede crear facturas electrónicas?: No. El empaquetado Factur-X y ZUGFeRD PDF/A-3b usa el endpoint E-Invoice Render.