# Panoramica delle azioni

Che cos’è un’azione, il catalogo raggruppato per capacità e come l’output di un’azione diventa l’input della successiva.

Un’**azione** è una singola trasformazione PDF pura, esposta come un unico
endpoint. Si invia un documento, l’azione gli fa esattamente una cosa (unire,
apporre una filigrana, crittografare, ruotare, dividere) e se ne riceve indietro
il risultato. Le azioni non conservano stato e non condividono contesto: ogni
chiamata è a sé stante. È questa uniformità che permette di incastrarle una
nell’altra in pipeline.

## Che cos’è un’azione

Ogni azione è un `POST` verso `/v1/<action>`, dove `<action>` è il nome tecnico
riportato nelle tabelle qui sotto. Tutte seguono lo stesso
[contratto di richiesta e risposta](/docs/api/requests-and-responses): un corpo
`multipart/form-data` con il PDF di input in un campo `file`, autenticato con
l’intestazione `X-API-Key`. La maggior parte restituisce un solo
`application/pdf`; la famiglia delle divisioni restituisce più documenti.

## Il catalogo

Diciassette azioni, raggruppate per capacità. Ciascuna rimanda al proprio
riferimento completo.

### Unire e dividere

| Azione | Percorso | Che cosa fa |
| --- | --- | --- |
| [Unire documenti](/docs/api/merge-pdf-documents) | `/v1/merge_documents` | Unire in un solo documento un array ordinato di PDF. |
| [Dividere per numero di pagine](/docs/api/split-pdf-by-page-count) | `/v1/split_by_page_count` | Dividere un PDF in parti consecutive con un numero fisso di pagine. |
| [Dividere a una pagina](/docs/api/split-pdf-at-page) | `/v1/split_at_page` | Dividere un PDF in due parti a un punto di taglio. |
| [Dividere per dimensione del file](/docs/api/split-pdf-by-file-size) | `/v1/split_by_size` | Dividere un PDF in parti che non superano un limite in byte. |
| [Dividere in gruppi di pagine](/docs/api/split-pdf-into-page-groups) | `/v1/split_by_groups` | Dividere un PDF in gruppi di pagine che si definiscono. |

Ognuna delle quattro azioni di divisione produce più documenti;
l’impacchettamento si sceglie con l’intestazione `Accept`. Vedere
[Formati di risposta](/docs/api/response-formats).

### Filigrane

| Azione | Percorso | Che cosa fa |
| --- | --- | --- |
| [Aggiungere una filigrana di testo](/docs/api/add-text-watermark-to-pdf) | `/v1/add_text_watermark` | Apporre fino a tre righe di testo formattato sulle pagine. |
| [Aggiungere una filigrana immagine](/docs/api/add-image-watermark-to-pdf) | `/v1/add_image_watermark` | Apporre sulle pagine un’immagine PNG o JPEG, per esempio un logo. |

### Password e sicurezza

| Azione | Percorso | Che cosa fa |
| --- | --- | --- |
| [Aggiungere una password](/docs/api/add-password-to-pdf) | `/v1/add_password` | Crittografare un documento con una password di apertura e/o di autorizzazioni. |
| [Rimuovere la password](/docs/api/remove-password-from-pdf) | `/v1/remove_password` | Decrittografare un documento di cui si conosce la password. |
| [Aggiungere restrizioni](/docs/api/add-restrictions-to-pdf) | `/v1/add_restrictions` | Impostare i flag di autorizzazione per stampa, copia e modifica. |
| [Rimuovere le restrizioni](/docs/api/remove-restrictions-from-pdf) | `/v1/remove_restrictions` | Azzerare i flag di autorizzazione di un documento. |
| [Rimuovere le firme](/docs/api/remove-signatures-from-pdf) | `/v1/remove_signatures` | Rimuovere le firme digitali perché il documento possa essere modificato. |

### Pagine

| Azione | Percorso | Che cosa fa |
| --- | --- | --- |
| [Estrarre pagine](/docs/api/extract-pages-from-pdf) | `/v1/extract_pages` | Conservare un insieme di pagine scelte e scartare il resto. |
| [Rimuovere pagine](/docs/api/remove-pages-from-pdf) | `/v1/remove_pages` | Scartare un insieme di pagine scelte e conservare il resto. |
| [Ruotare le pagine](/docs/api/rotate-pages-in-pdf) | `/v1/rotate_pages` | Ruotare le pagine scelte di un multiplo di 90 gradi. |
| [Invertire le pagine](/docs/api/reverse-pages-of-pdf) | `/v1/reverse_pages` | Invertire l’ordine delle pagine dalla prima all’ultima. |
| [Riordinare le pagine](/docs/api/reorder-pages-of-pdf) | `/v1/reorder_pages` | Riorganizzare le pagine nell’ordine indicato dal chiamante. |

## Come si compongono le azioni

Poiché ogni azione accetta un PDF e (per le azioni a output singolo) restituisce
un PDF, l’output di un’azione è un input valido per la successiva. Tra una
chiamata e l’altra non viene memorizzato nulla, quindi la composizione avviene
facendo transitare i byte: tenere in memoria la risposta di una richiesta e
inviarla come `file` della successiva.

Una pipeline tipica si legge da sinistra a destra:

```text
merge_documents  →  add_text_watermark  →  add_password
   (many PDFs)         (one watermarked)      (one encrypted)
```

La guida [Concatenare le azioni](/docs/api/chaining-actions) mostra tutto questo
dall’inizio alla fine, nel codice, senza toccare il disco.

## Output singolo o output multiplo

La maggior parte delle azioni restituisce un solo documento `application/pdf`. Le
quattro azioni di divisione ne restituiscono molti e lasciano scegliere come
vengono impacchettati (un archivio ZIP, una busta JSON o un corpo
`multipart/mixed`) tramite la negoziazione del contenuto. Questo meccanismo ha
una sola sede: [Formati di risposta](/docs/api/response-formats).