Logo PDFHQ

Documenti

DocumentazioneGuida introduttiva

Idempotenza e sicurezza dei tentativi

Riprova in sicurezza la creazione di attività di documenti tra timeout di rete utilizzando intestazioni Idempotency-Key con ambito progetto, e distingui questi dall'elaborazione a pagamento e dal dispatch del provider.

Chiavi API lato server Caricamenti di archiviazione firmati

Creazione attività replay-safe#

POST /v1/tasks accetta un parametro facoltativo Idempotency-Key (8–128 lettere ASCII, cifre, punti, trattini bassi, due punti o trattini; inizia con una lettera o una cifra). Ripetere una chiave per lo stesso account HQTools e progetto API restituisce l'attività esistente. Il riutilizzo della stessa chiave per uno strumento diverso restituisce 409 IDEMPOTENCY_KEY_REUSED.

Crea attività con chiave di ripetizione
curl -q --fail-with-body -X POST 'https://api.pdfhq.io/v1/tasks' \
  -H 'x-api-key: YOUR_SERVER_SIDE_API_KEY' \
  -H 'Idempotency-Key: job-20261025-00001' \
  -H 'Content-Type: application/json' \
  -d '{"tool":"compress"}'

L'ID attività restituito è stabile tra i tentativi. Le chiavi sono limitate a un account e a un progetto API e rimangono associate all'attività fino a quando il record sottostante non viene eliminato. Crea una nuova chiave per una nuova attività.

Regole di ripetizione diverse per risorse diverse#

Creazione dell'attività: ripeti utilizzando lo stesso Idempotency-Key dopo un'interruzione di rete. Elaborazione attività: l'ID attività fisso fornisce già idempotenza del job/credito backend per opzioni identiche; ispeziona il suo stato prima di riprovare. Processi AI: utilizza una citazione approvata dall'utente aggiornata e una Idempotency-Key stabile come supportato dall'endpoint di IA. Invio eSignature: una risposta incerta del provider richiede la riconciliazione della busta; non rinviare ciecamente una richiesta di firma.

I caricamenti S3 firmati utilizzano policy di moduli POST di breve durata. Non inviare x-api-key o Idempotency-Key a S3. I caricamenti di archiviazione e la stima dei preventivi non addebitano crediti di per sé; l'elaborazione sì.

Logo PDFHQ

Strumenti PDF e intelligenza documentale. Prepara, comprendi e lavora con i tuoi documenti.

© 2026 PDFHQ. Tutti i diritti riservati.