Valida prima di inviare

Chiedi che cosa troverebbe una chiamata di generazione, prima di farla. La prova a vuoto applica ogni controllo della chiamata reale, ti dice quante pagine avrà il documento e quanto dovrebbe costare, e non addebita nulla, non riserva nulla e non conserva nulla.

La chiamata

POST /api/v1/compose/documents/validate
Authorization: Bearer <key>

{
  "data": { "number": "2026-000147" },
  "settings": { "templateId": "invoice-standard-8bc99b" },
  "estimatePages": true,
  "plannedExtras": ["signature"]
}

Il corpo è quello di generate, più due chiavi facoltative. Chiede lo stesso ambito del token (documents:compose), le stesse regole di settings (isTest chiede il suo ambito) e accetta una Idempotency-Key facoltativa come ogni altra POST: una ripetizione entro 24 ore restituisce la prima risposta, saldo compreso, quindi usa una chiave nuova per una stima nuova. In ogni caso non si addebita nulla.

• estimatePages (predefinito true): impagina il documento una volta, solo per questa chiamata, per contarne le pagine. Non viene mai conservato né addebitato e si mette in coda dopo il lavoro di produzione. Manda false per una risposta più economica senza pages.estimate.
• plannedExtras: le aggiunte che farai dopo il documento. Oggi ["signature"], così il suo costo compare nella stima.

La risposta

La chiamata in sé è riuscita (output.status vale succeeded); il verdetto è in output.compose.validation.

Campo	Significato
ok	Nessun problema bloccante: generate non sarebbe rifiutata per ciò che è stato controllato qui.
errors	Ciò che farebbe rifiutare la chiamata, nella forma di un errore reale (code, number, message, details): un campo mancante in un modello rigoroso, un payload che non passa uno JSON Schema reject, un file conservato che non esiste, un limite superato, un sigillo che la tua organizzazione non ha acquistato.
warnings	Gli avvisi che darebbe la chiamata reale, nella forma di output.warnings.
templateErrors, templateWarnings	La diagnostica del modello, in frasi: lo stesso motore del pulsante Valida della console e del caricamento (codici di formattazione sconosciuti, grafici che non si possono disegnare, condizioni che il motore non sa spiegare).
missingFields, unusedFields	Letti dal modello e assenti dal payload; inviati e mai letti.
payloadSchema	Il verdetto dello JSON Schema del modello: mode, checked, valid e le prime violazioni (path, keyword, message; mai un valore).
pages	estimate (il numero reale di pagine di un'impaginazione fatta per questa chiamata, PDF accodati compresi), method (rendered, not_requested oppure unavailable quando la piattaforma era troppo occupata per un'impaginazione in più), limit.
files	I file conservati che la richiesta nomina, controllati perché esistano e siano del tipo giusto.
estimatedCredits	Vedi sotto.
charged, stored	Sempre 0 e false.

Che cosa promette la stima dei crediti

La stima è un modello deterministico (per-operation-rate/v1), non un'ipotesi: è la stessa funzione di prezzo che usa la prenotazione reale, alle tariffe della tua organizzazione.

"estimatedCredits": {
  "model": "per-operation-rate/v1",
  "certainty": "dependsOn",
  "credits": 5,
  "maximum": 15,
  "dependsOn": [
    {"item": "signature", "credits": 10,
     "condition": "charged when the envelope is sent (Signer Fly or Document Fly)"}
  ],
  "testItems": 0,
  "chargedOn": "delivery",
  "balance": {"availableCredits": 1247, "sufficient": true},
  "plan": {
    "subscriptionId": "6c1f...", "planCode": "PIONR026",
    "takes": [{"item": "document", "counter": "calls", "units": 1},
              {"item": "signature", "counter": "calls", "units": 0}],
    "remaining": {"calls": 4210}, "sufficient": true,
    "whenShort": "refused", "endsAt": "2026-12-31T23:00:00+00:00"
  }
}

• credits è la tariffa del documento: fissa, qualunque siano il formato o il numero di pagine. Si addebita quando il documento è consegnato ed è rimborsata a ogni errore.
• certainty vale exact quando non si può addebitare nient'altro e dependsOn quando sì: un sigillo o una marca temporale qualificati (solo se apposti) o le aggiunte che hai dichiarato. maximum è il massimo che può costare il tutto, e sufficient lo confronta con quanto puoi ancora spendere.
• plan vale null senza un piano. Con un piano, dice che cosa prende ogni voce da quale contatore del piano (takes; su un piano a chiamate una firma prevista dopo il suo documento sta nella stessa chiamata, units 0), quanto resta, se basta e che cosa succede quando non basta (whenShort: credit se hai attivato il pagamento con i crediti, block per un piano che non blocca mai, altrimenti refused con SUBSCRIPTION_ALLOWANCE_EXHAUSTED). Una voce coperta dal piano non prende credito; credits e maximum restano il prezzo in crediti.
• Una chiamata isTest vale 0 crediti e un elemento di prova.
• Vale per le tariffe di oggi. Un cambio di tariffa successivo, o i costi propri di una busta oltre le aggiunte che hai indicato, ne restano fuori.