Quando dovrei usare Template Render invece di JSON Render?

Usate Template Render dopo l'approvazione del layout, quando i sistemi chiamanti devono inviare solo dati di business.

template_id è stabile?

Sì. La documentazione della Template API descrive template_id come identificativo stabile esposto ai sistemi chiamanti.

Una richiesta può renderizzare più elementi data?

Sì. Template Render accetta un array data entro i limiti dell'endpoint pubblico.

Template Render può creare fatture elettroniche?

No. Il packaging Factur-X e ZUGFeRD PDF/A-3b usa l'endpoint E-Invoice Render.

Flussi per sviluppatori

API PDF da template per contratti documentali stabili

Renderizza PDF da template_id stabile e array data quando layout ripetuti devono essere gestiti una sola volta e riusati da ERP, OMS, WMS o sistemi SaaS chiamanti.

API PRINCIPALE Template Render

ENDPOINT /api/v1/template-render

SISTEMI backend SaaS / integrazione ERP / OMS / WMS / coda di job

Provare nel Playground Leggere la documentazione

Lavoro da svolgere

Renderizzare PDF ripetuti inviando un template_id stabile e un array di dati di business, invece di chiedere a ogni sistema chiamante di descrivere pagine, coordinate ed elementi di layout a ogni richiesta.

Quando usare questa API

Il layout del documento è approvato e riutilizzato da più sistemi chiamanti o job.
I sistemi chiamanti devono inviare dati di business, non JSON di layout a livello di coordinate.
Vi serve output per fatture, distinte di imballaggio, etichette di spedizione o template personalizzati.
Volete controllare le revisioni attive del template fuori dal sistema chiamante.

Cosa non sostituisce

State ancora progettando il layout. Usate JSON Render finché coordinate e campi non sono stabili.
Vi serve conversione HTML-to-PDF arbitraria.
Vi serve packaging e-invoice PDF/A-3b con CII XML incorporato.

Quale endpoint chiamare

PRIMARIO

/api/v1/template-render

Template Render è il percorso predefinito per questo flusso.

SECONDARIO 1

/api/v1/pdf/render

Usalo quando il flusso richiede l'API collegata, un contratto di template o una verifica delle capacità.

Request minimo

POST /api/v1/template-render - rendering di una fattura da template.

{
  "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"
        }
      ]
    }
  ]
}

Cosa gestisce gPdf

Ricerca del template tramite template_id stabile.
Rendering di ogni elemento data contro il template attivo.
Concatenazione delle pagine renderizzate in un unico PDF entro i limiti dell'endpoint pubblico.
Comportamento condiviso per autenticazione, request ID ed envelope di errore.

Cosa controlla il tuo sistema

Selezione del template, mappatura dei campi, dati di business e autorizzazione del sistema chiamante.
Processo di pubblicazione del template, comunicazione delle modifiche e copertura dei test.
Suddivisione in blocchi, accodamento e retry quando si renderizzano molti documenti.

Checklist di produzione

Trattate template_id come un contratto stabile e opaco.
Verificate i campi data prima di chiamare Template Render.
Mantenete test golden-PDF per il template attivo e dati rappresentativi.
Suddividete i batch grandi secondo i limiti pubblici di Template Render.
Registrate template_id, request ID e ID degli oggetti di business per tracciabilità.

Limiti della promessa

Template Render non è da solo uno strumento di design; i template devono essere già pubblicati.
gPdf non deduce dal template dati di business mancanti.
Template Render non sostituisce l'endpoint E-Invoice Render.

Template Render è il livello di contratto per la produzione

JSON Render è ideale mentre il layout viene progettato. Template Render è il livello da usare dopo che il layout diventa un contratto. I sistemi chiamanti inviano template_id e data; il template attivo possiede la struttura del documento.

Questo mantiene più piccoli i sistemi chiamanti e rende le modifiche ai template più facili da revisionare, testare e distribuire.

FAQ

Quando dovrei usare Template Render invece di JSON Render?: Usate Template Render dopo l'approvazione del layout, quando i sistemi chiamanti devono inviare solo dati di business.
template_id è stabile?: Sì. La documentazione della Template API descrive template_id come identificativo stabile esposto ai sistemi chiamanti.
Una richiesta può renderizzare più elementi data?: Sì. Template Render accetta un array data entro i limiti dell'endpoint pubblico.
Template Render può creare fatture elettroniche?: No. Il packaging Factur-X e ZUGFeRD PDF/A-3b usa l'endpoint E-Invoice Render.