API Template PDF

Panoramica

L'API Template PDF accetta un file XML FatturaPA e lo converte in un PDF di cortesia con il template e le personalizzazioni scelti. Il rendering può essere sincrono (risposta immediata con PDF) o asincrono (notifica via webhook al completamento).

Base URL	https://api.fattureai.it/v1
Sandbox URL	https://sandbox.api.fattureai.it/v1
Formato	JSON (request), JSON o PDF binario (response)

Autenticazione

Stessa autenticazione dell'API di generazione. Includi la tua API key nell'header:

X-API-Key: fa_live_xxxxxxxxxxxxxxxx

POST /v1/pdf

Converte un file XML FatturaPA in PDF con il template specificato.

Request body

Campo	Tipo	Obbligatorio	Descrizione
xml	string	Si	XML FatturaPA codificato in Base64.
template	string	No	Nome del template. Default: classico.
formato	string	No	A4 o letter. Default: A4.
personalizzazione	object	No	Personalizzazioni del template.
personalizzazione.logo	string	No	Logo in Base64 (PNG/JPG, max 500KB).
personalizzazione.colore_primario	string	No	Colore primario esadecimale (es. #2563eb).
personalizzazione.colore_secondario	string	No	Colore secondario esadecimale.
personalizzazione.font	string	No	Font: inter, roboto, lora, montserrat. Default: inter.
personalizzazione.footer_testo	string	No	Testo personalizzato nel footer del PDF.
webhook_url	string	No	URL per la notifica asincrona. Se fornito, il rendering avviene in background.
risposta	string	No	json (default) o binary. Con binary il PDF viene restituito direttamente.

Esempio richiesta (sincrona)

POST /v1/pdf HTTP/1.1
Host: api.fattureai.it
X-API-Key: fa_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "xml": "PD94bWwgdmVyc2lvbj0i...base64...encoded==",
  "template": "elegante",
  "formato": "A4",
  "personalizzazione": {
    "colore_primario": "#1e40af",
    "font": "montserrat",
    "footer_testo": "Grazie per la fiducia! Pagamento entro 30 giorni."
  }
}

Esempio risposta (200 OK, modalità JSON)

{
  "success": true,
  "pdf": {
    "id": "pdf_xyz789abc123",
    "url": "https://api.fattureai.it/v1/pdf/download/pdf_xyz789abc123",
    "expires_at": "2026-03-16T12:00:00Z",
    "dimensione_bytes": 145280,
    "template": "elegante",
    "pagine": 1
  },
  "file": "JVBERi0xLjQK...base64...pdf==",
  "crediti_residui": 85
}

Rendering Asincrono con Webhook

Per volumi elevati o PDF complessi, puoi usare il rendering asincrono. Fornisci un webhook_url nella richiesta e ricevi una notifica HTTP POST quando il PDF è pronto.

Richiesta asincrona

{
  "xml": "PD94bWwg...base64...",
  "template": "corporate",
  "webhook_url": "https://tuoserver.com/webhook/pdf-pronto"
}

Risposta immediata (202 Accepted)

{
  "success": true,
  "status": "processing",
  "job_id": "job_abc123def456",
  "estimated_seconds": 5
}

Notifica webhook (POST al tuo server)

{
  "event": "pdf.completed",
  "job_id": "job_abc123def456",
  "pdf": {
    "id": "pdf_xyz789abc123",
    "url": "https://api.fattureai.it/v1/pdf/download/pdf_xyz789abc123",
    "expires_at": "2026-03-16T12:00:00Z",
    "dimensione_bytes": 145280
  },
  "timestamp": "2026-03-09T10:30:05Z"
}

Il webhook include un header X-Webhook-Signature con firma HMAC-SHA256 per verificare l'autenticità della notifica. La chiave segreta per la verifica è disponibile nella dashboard.

GET /v1/pdf/status/{job_id}

In alternativa al webhook, puoi controllare lo stato del rendering con polling.

GET /v1/pdf/status/job_abc123def456 HTTP/1.1
Host: api.fattureai.it
X-API-Key: fa_live_xxxxxxxxxxxxxxxx

{
  "job_id": "job_abc123def456",
  "status": "completed",
  "pdf": {
    "id": "pdf_xyz789abc123",
    "url": "https://api.fattureai.it/v1/pdf/download/pdf_xyz789abc123"
  }
}

Valori possibili per status: queued, processing, completed, failed.

GET /v1/templates

Recupera l'elenco dei template disponibili con anteprime.

GET /v1/templates HTTP/1.1
Host: api.fattureai.it
X-API-Key: fa_live_xxxxxxxxxxxxxxxx

{
  "templates": [
    {
      "id": "classico",
      "nome": "Classico",
      "descrizione": "Design pulito e tradizionale.",
      "anteprima_url": "https://api.fattureai.it/templates/classico/preview.png",
      "personalizzabile": true,
      "disponibile_free": true
    },
    {
      "id": "elegante",
      "nome": "Elegante",
      "descrizione": "Linee raffinate con accenti dorati.",
      "anteprima_url": "https://api.fattureai.it/templates/elegante/preview.png",
      "personalizzabile": true,
      "disponibile_free": false
    }
  ]
}

Codici di Errore

HTTP	Codice	Descrizione
400	INVALID_XML	L'XML fornito non è un FatturaPA valido.
400	INVALID_TEMPLATE	Il template specificato non esiste.
400	INVALID_LOGO	Il logo è troppo grande o in formato non supportato.
400	INVALID_COLOR	Il colore esadecimale non è valido.
400	INVALID_WEBHOOK_URL	L'URL del webhook non è raggiungibile o non è HTTPS.
401	UNAUTHORIZED	API key mancante o non valida.
402	TEMPLATE_NOT_IN_PLAN	Il template non è disponibile nel tuo piano. Fai upgrade.
429	RATE_LIMIT	Limite di richieste superato.
429	CREDITI_ESAURITI	Crediti esauriti.
500	RENDER_ERROR	Errore durante il rendering del PDF.

Rate Limits

Piano	Richieste / minuto	Max dimensione XML
Free	10	500 KB
Starter	60	2 MB
Pro	120	5 MB
Enterprise	Personalizzato	Personalizzato

Esempi di Codice

cURL — Conversione sincrona con download diretto

curl -X POST https://api.fattureai.it/v1/pdf \
  -H "X-API-Key: fa_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "xml": "'$(base64 -w0 fattura.xml)'",
    "template": "moderno",
    "risposta": "binary"
  }' \
  --output fattura.pdf

Python — Conversione con personalizzazione

import os
import base64
import requests

api_key = os.environ["FATTURAAI_API_KEY"]

with open("fattura.xml", "rb") as f:
    xml_b64 = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.fattureai.it/v1/pdf",
    headers={"X-API-Key": api_key},
    json={
        "xml": xml_b64,
        "template": "elegante",
        "personalizzazione": {
            "colore_primario": "#1e40af",
            "font": "montserrat",
            "footer_testo": "Pagamento entro 30 giorni.",
        },
    },
)

data = response.json()
if data["success"]:
    pdf = base64.b64decode(data["file"])
    with open("fattura.pdf", "wb") as f:
        f.write(pdf)

Node.js — Rendering asincrono con webhook

import { readFile } from "fs/promises";

const apiKey = process.env.FATTURAAI_API_KEY;
const xml = await readFile("fattura.xml");

const response = await fetch("https://api.fattureai.it/v1/pdf", {
  method: "POST",
  headers: {
    "X-API-Key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    xml: xml.toString("base64"),
    template: "corporate",
    webhook_url: "https://tuoserver.com/webhook/pdf",
  }),
});

const data = await response.json();
console.log(`Job avviato: ${data.job_id}`);
// Il PDF sara' consegnato via webhook quando pronto