# 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).