Sigillo qualificato e marca temporale qualificata

Due cose che un documento finito può portare e che gli permettono di dimostrarsi da solo, senza di noi. Funzionano su tutte e tre le API — composizione, firma e flusso in una chiamata — e si acquistano a parte rispetto ai prodotti.

	Cosa dimostra	Chi lo afferma
`qeSeal`	questi byte sono usciti da questa organizzazione in questa forma e nessuno li ha toccati da allora (eIDAS art. 35)	noi, con un certificato qualificato rilasciato da un QTSP
`qualifiedTimestamp`	questi esatti byte esistevano a quest'ora (eIDAS art. 41)	un'autorità di marcatura temporale indipendente

Nessuno dei due cambia il livello della firma. Un sigillo è l'atto di una persona giuridica e non dice nulla su chi ha firmato; la firma resta SES in ogni caso. Vedi Livelli di firma — la distinzione conta, e un documento con cui ci stai confrontando probabilmente la confonde.

Disponibili ora, per ogni organizzazione che non sia di test. Un sigillo costa 2 crediti, un sigillo con la sua marca temporale qualificata 6 (la marca vale 4 e non si vende mai da sola). Il credito regalato li paga come qualunque altro credito. Un'organizzazione che si registra da sola li ha entrambi fin dall'inizio; una aperta da un operatore li ha quando l'operatore li attiva. Si chiedono per chiamata (qeSeal, qualifiedTimestamp) o con l'impostazione della tua organizzazione.

Cosa dicono, e cosa non dicono. Il sigillo è apposto con il certificato d'organizzazione di DoConure, non con uno a nome della tua organizzazione. Dice che il file viene da DoConure e non è stato modificato da allora; non dice chi ha firmato (quella è la firma, che resta SES). Con la marca temporale il file è PAdES B-LT: continua a verificarsi dopo la scadenza del certificato.

Cosa torna indietro. Si pagano prima, e ciò che un problema lascia inutilizzato torna al credito da cui veniva. Una busta paga sigillo e marca insieme alla firma all'invio; se viene annullata, scade o è rifiutata, vengono restituiti (la firma no); se non si possono apporre quando l'ultimo firmatario finisce, vengono restituiti subito, e così quando il fornitore ha ricevuto la richiesta e la sua risposta è andata persa (non la ripetiamo mai). Ogni restituzione è una riga del tuo registro delle attività con il suo codice (ATTESTATION_REFUNDED_*, da 2130 a 2132).

Servono un fornitore esterno configurato per la piattaforma, la funzione abilitata per la tua organizzazione e una configurazione di produzione valida. Finché non ci sono tutti e tre, una richiesta che ne chiede uno viene rifiutata con TRUST_PROVIDER_NOT_CONFIGURED o FEATURE_NOT_ENABLED, mai soddisfatta con un documento non sigillato. Un fornitore simulato è indicato come non qualificato.

Chiederne uno

Entrambi sono facoltativi in settings e hanno tre stati: true lo chiede, false lo rifiuta, e omettere la chiave lascia la decisione all'impostazione della tua organizzazione (vedi la tabella più sotto). Mandare false non applica nulla e non addebita nulla.

POST /api/v1/compose/documents/generate
Authorization: Bearer lpdc_…

{
  "data": { "cliente": "Acme S.r.l." },
  "settings": {
    "templateId": "contract",
    "qeSeal": true,
    "qualifiedTimestamp": true
  }
}

Sull'API di firma le stesse due capacità si chiamano seal e timestamp dal 2026-09-18, e si chiamano ancora così — qui un campo pubblicato è per sempre. qeSeal e qualifiedTimestamp sono accettati anche lì, come alias, così un solo vocabolario funziona su tutte e tre le superfici e nulla di già scritto si rompe.

POST /api/v1/sign/envelopes

{
  "signers": { … },
  "settings": {
    "documentId": "…",
    "subject": "Contratto di servizio",
    "qeSeal": true
  }
}

Su una busta i due sono registrati come intenzione e applicati quando l'ultimo firmatario finisce, il che può accadere giorni dopo. Su una composizione sono applicati dentro la chiamata.

Le quattro combinazioni, e cosa produce ciascuna

La marca temporale è un'opzione del sigillo, non un prodotto a sé: puoi avere il sigillo senza, mai il contrario. Un sigillo è un certificato annuale fisso e una marca costa ogni volta, quindi comprare l'origine senza comprare il tempo è una scelta legittima per un cliente — e il profilo PAdES che ne risulta è riportato in output.compose.trust.padesProfile, così nessuno scopre nel 2031 di aver comprato un sigillo e non dieci anni.

`qeSeal`	`qualifiedTimestamp`	Profilo	Cosa vale
false	false	`null`	un normale PDF
false	true	—	rifiutato con `TIMESTAMP_REQUIRES_SEAL` (1012): la marca è un'opzione del sigillo e non si applica mai da sola — vedi sotto
true	false	`B-B`	l'origine, finché il certificato non scade — dopo non si può più verificare
true	true	`B-T` o `B-LT`	origine e tempo. `B-LT` continua a verificarsi dopo la scadenza del certificato

Quanto costano. Un sigillo apposto da un fornitore qualificato costa 2 crediti e la sua marca temporale qualificata 4 (6 insieme), pagati all'invio per una busta e con il documento per una composizione. Un sigillo o una marca di un fornitore non qualificato (di test o simulato, riportato con TRUST_NOT_QUALIFIED e "qualified": false) non costa nulla: non attesta nulla, quindi non si vende. L'estimatedCredits della prova a vuoto segue la stessa regola. Cosa viene restituito quando uno dei due non è applicato è descritto in cima alla pagina.

La tua organizzazione deve avere la capacità

Si vendono a parte rispetto ai tre prodotti. Un'organizzazione che si è registrata da sola li ha entrambi dall'inizio; per una aperta da un operatore, li attiviamo noi. Il tuo amministratore vede quali sono attivi in Impostazioni → Fiducia e conformità nella console; solo noi possiamo cambiarli.

Una richiesta che ne chiede uno che non hai è rifiutata:

403 Forbidden

{
  "code": "FEATURE_NOT_ENABLED",
  "number": 1007,
  "message": "Qualified electronic seal is not enabled for this organisation…",
  "details": {
    "feature": "qeSeal",
    "enabled": { "qeSeal": false, "qualifiedTimestamp": true },
    "note": "the request was refused, not downgraded"
  },
  "retryable": false
}

Rifiutata su ogni API, e mai prodotta in silenzio senza. È lo stesso ragionamento di SIGNATURE_LEVEL_UNAVAILABLE: ricevere un documento che credi sigillato e non lo è è peggio che sentirsi dire di no. Non si addebita nulla, e details.enabled ti dice cosa hai, così un'integrazione può adattarsi senza una chiamata al supporto.

Le tue impostazioni sono un tetto separato, più basso

Una volta attiva una capacità, la tua organizzazione sceglie ancora quando si applica, in Impostazioni → Autenticità dei documenti. Tre posizioni, che si comportano come ogni altro filtro di questa API:

	chiedi `true`	chiedi `false`	non dici nulla
`off`	no, con un avviso	no	no
`optional`	sì	no	no
`always`	sì	sì, con un avviso	sì

A differenza del diritto d'uso qui sopra, questo avvisa invece di rifiutare — ricevi il documento normale più un avviso SEAL_NOT_ENABLED o TIMESTAMP_NOT_ENABLED. La differenza è che questo tetto l'ha scelto il tuo amministratore e lo vede nella sua pagina delle impostazioni, quindi ricevere meno è qualcosa che puoi scoprire e su cui puoi agire.

Leggi sempre il valore effettivo, mai la tua richiesta. La risposta riporta quello che è successo davvero:

{
  "settings": { "qeSeal": true, "qualifiedTimestamp": false, … },
  "output": {
    "compose": {
      "trust": {
        "qeSeal":             { "requested": true, "applied": true,
                                "provider": "local",
                                "appliedAt": "2026-09-23T14:02:11+00:00" },
        "qualifiedTimestamp": { "requested": true, "applied": false },
        "padesProfile": "B-B"
      }
    },
    "warnings": [ { "code": "TIMESTAMP_NOT_ENABLED", "number": 2002, … } ]
  }
}

Un errore trattiene il documento

Se hai chiesto un sigillo e non è stato possibile apporlo, la composizione fallisce — 502 con SEAL_FAILED o TIMESTAMP_FAILED — e non torna nessun documento. L'attestazione non viene addebitata.

È voluto. Una composizione si può rifare, quindi trattenerla ti costa un nuovo tentativo; restituire un PDF non sigillato dove era stato chiesto un sigillo qualificato vorrebbe dire attribuire al file una proprietà che non ha, l'unica cosa che questo servizio non farà.

Nessuno dei due è segnato come da ritentare, ed è voluto anche questo: il fornitore potrebbe aver eseguito l'operazione prima che la connessione cadesse, e ritentare alla cieca un'operazione a pagamento è il modo in cui un documento ne costa due. Dove l'errore è chiaramente passeggero — il fornitore non era raggiungibile affatto, un limite di frequenza, un'autorità di marcatura che non ha risposto — ricevi invece TRUST_PROVIDER_UNAVAILABLE, che è da ritentare, con details.category che dice perché.

Il confine tra i due è se il fornitore ha ricevuto la richiesta. Una richiesta di sigillo andata in timeout dopo l'invio torna come SEAL_FAILED con details.category: "OUTCOME_UNKNOWN" — non sappiamo se è stata eseguita, quindi non la ripetiamo mai per conto tuo, e registriamo il riferimento del fornitore ogni volta che lo abbiamo, così l'operazione si può riconciliare dopo.

Una firma data non si perde mai per questo. Una busta si comporta all'opposto, di proposito: se il sigillo fallisce al completamento, la busta si completa lo stesso, con SEAL_NOT_APPLIED tra gli avvisi e padesProfile: null registrato. Una persona ha percorso tutto il flusso di firma; bloccare il suo documento perché l'endpoint di qualcun altro si stava riavviando la punirebbe per un guasto che non è suo, per un'attestazione che si può ottenere di nuovo in altri modi.

Le organizzazioni di test non acquistano mai né l'uno né l'altra

Un'organizzazione segnata come di prova non riceve nessuno dei due, qualunque cosa dicano le sue impostazioni, e la risposta porta PAID_EXTRA_SKIPPED_ON_TEST, così vedi perché il profilo è tornato null. Usa l'organizzazione reale per vedere un documento sigillato.

Lo stesso vale per una singola chiamata: isTest: true insieme a qeSeal: true o qualifiedTimestamp: true è rifiutato con FEATURE_NOT_AVAILABLE_IN_TEST_MODE prima che si riservi o si mandi qualcosa a un fornitore.

Una marca temporale da sola è rifiutata

La marca temporale qualificata esiste solo come opzione del sigillo. Chiedere qualifiedTimestamp: true senza qeSeal: true è rifiutato con TIMESTAMP_REQUIRES_SEAL (1012, HTTP 422, non da ritentare), su ogni porta — composizione, flusso, batch, busta — prima di comporre, riservare, inviare o addebitare qualunque cosa. Una marca da sola verrebbe da un'autorità non necessariamente qualificata e sembrerebbe quello che non è; un documento sigillato senza marca va benissimo.

422 Unprocessable Entity

{
  "code": "TIMESTAMP_REQUIRES_SEAL",
  "number": 1012,
  "message": "a qualified timestamp is an option of the qualified seal and is never applied on its own: …",
  "details": { "feature": "qualifiedTimestamp", "requires": "qeSeal",
               "source": "request" },
  "retryable": false
}

details.source è request quando hai chiesto la marca tu, e organisation setting quando il timestamp_mode della tua organizzazione è always e il documento non è sigillato: imposta anche il Sigillo su always, o la marca su optional. Una busta che perde il sigillo prima di completarsi finisce senza nessuno dei due, e lo dice in due avvisi (SEAL_NOT_APPLIED, TIMESTAMP_NOT_APPLIED).

Chi li esegue

Sigillo qualificato e marca temporale qualificata sono capacità di DoConure. Quale QTSP e quale autorità di marcatura ci siano dietro sta a noi cambiarlo — la richiesta che scrivi, gli errori su cui decidi e i metadati che rileggi non cambiano quando uno viene sostituito. output.compose.trust.*.provider riporta il nostro nome interno di chi l'ha eseguito, così in una conversazione con il supporto c'è qualcosa da citare.

Dove un ambiente gira con un'autorità simulata — il percorso completo gira, e il token non attesta nulla a nessuno — lo dice, su ogni schermata e in capabilities, e qualified è riportato come false qualunque cosa sostenga la configurazione.