# Richieste e risposte La forma condivisa da ogni chiamata: una richiesta multipart, una risposta che è un documento e nessuno stato conservato tra le due. Tutte le azioni dell’API condividono un solo contratto. Si invia una richiesta `multipart/form-data` con il PDF in un campo `file` e si riceve indietro il documento elaborato come corpo della risposta. Non c’è nessun processo da interrogare, nessun passaggio di upload e nessuna risorsa da ripulire in seguito: una richiesta in entrata, un documento in uscita. Una volta imparata questa forma, ogni pagina di azione si legge allo stesso modo. ## Ogni richiesta ha lo stesso aspetto Ogni azione è un unico `POST` verso `/v1/<action>` con un corpo `multipart/form-data`. Tre elementi sono sempre presenti: - L’intestazione `X-API-Key` che contiene la chiave segreta, su HTTPS. - Una parte `file` che contiene il PDF di input. - Zero o più parti di testo per le opzioni dell’azione (ad esempio `line_1` o `pages`), con i nomi esatti elencati nel riferimento dell’azione. Ecco una richiesta completa che appone una filigrana, mostrata come HTTP grezzo: ```http POST /v1/add_text_watermark HTTP/1.1 Host: api.pdfblocks.com X-API-Key: your_api_key Content-Type: multipart/form-data; boundary=----PdfBlocksBoundary ------PdfBlocksBoundary Content-Disposition: form-data; name="file"; filename="input.pdf" Content-Type: application/pdf %PDF-1.7 <binary PDF bytes> ------PdfBlocksBoundary Content-Disposition: form-data; name="line_1" CONFIDENTIAL ------PdfBlocksBoundary-- ``` Leggendola parte per parte: - **Riga di richiesta**: `POST /v1/add_text_watermark`. Il nome dell’azione è il percorso; il metodo è sempre `POST`. - **`X-API-Key`**: la chiave autentica la richiesta. Vedere [Autenticazione](/docs/api/authentication). - **`Content-Type`**: `multipart/form-data` con una stringa di delimitazione. L’helper multipart di qualsiasi client HTTP imposta questa intestazione e il delimitatore al posto dell’utente; è raro doverlo scrivere a mano. - **La parte `file`**: il PDF di input, inviato in binario. - **Le parti di opzione**: una parte per opzione, qui `line_1`. Ciascuna è un semplice valore di testo. Quel corpo non va mai assemblato a mano. Il client HTTP di ogni linguaggio lo costruisce a partire da un handle di file e da qualche campo. La stessa richiesta in cURL: ```bash title="cURL" curl https://api.pdfblocks.com/v1/add_text_watermark \ -H 'X-API-Key: your_api_key' \ -F file=@input.pdf \ -F line_1='CONFIDENTIAL' \ -o watermarked.pdf ``` <Info> L’URL di base predefinito è `https://api.pdfblocks.com`. Per mantenere l’elaborazione in una giurisdizione precisa, sostituire l’host con uno regionale. Vedere [Regioni e residenza dei dati](/docs/api/regions-and-data-residency). Cambia soltanto l’host; il percorso, le intestazioni e il corpo sono identici ovunque. </Info> ## Ogni risposta è il documento Un’azione a output singolo risponde con `200 OK` e il PDF elaborato come corpo grezzo: ```http HTTP/1.1 200 OK Content-Type: application/pdf Content-Length: 48213 %PDF-1.7 <binary PDF bytes> ``` Il corpo è il documento finito, non un JSON che avvolge un URL né una stringa base64. Scriverlo in streaming direttamente in un file oppure passarlo al passaggio successivo della pipeline. In cURL è il `-o watermarked.pdf` qui sopra; nel codice è scrivere i byte di `response` su disco, esattamente come fanno gli esempi di ogni pagina di azione. ## *Stateless* per progettazione L’API non memorizza nulla. Il documento viene elaborato in memoria, nella regione a cui ci si rivolge, e scartato non appena la risposta è stata scritta. Non esiste alcun ID di documento a cui fare riferimento in seguito né alcuna copia lato server da eliminare. Poiché tra una chiamata e l’altra non persiste nulla, ogni richiesta deve portare il proprio `file` di input, anche quando si concatenano le azioni e si passa l’output di una chiamata direttamente alla successiva (vedere [Concatenare le azioni](/docs/api/chaining-actions)). ## Dove il contratto varia Tre cose si aggiungono a questa base, ciascuna documentata sulla propria pagina: - **Più di un input.** [Unire documenti](/docs/api/merge-pdf-documents) accetta un array ordinato di parti `file` e [Aggiungere una filigrana immagine](/docs/api/add-image-watermark-to-pdf) accetta una seconda parte binaria `image`. Entrambe sono trattate in [Lavorare con i file](/docs/api/working-with-files). - **Più di un output.** La famiglia delle divisioni restituisce più documenti e l’impacchettamento si sceglie (ZIP, JSON o multipart) con l’intestazione `Accept`. Vedere [Formati di risposta](/docs/api/response-formats). - **Gli errori.** Qualsiasi errore restituisce un corpo `application/problem+json` conforme alla RFC 7807, mai un PDF parziale. Vedere [Errori](/docs/api/errors).