# Requêtes et réponses

La forme que partage chaque appel : une requête en formulaire multipart, une réponse qui est un document, et aucun état conservé entre les deux.

Toutes les actions de l’API partagent un seul contrat. Vous envoyez une requête
`multipart/form-data` avec votre PDF dans un champ `file`, et vous récupérez le
document traité comme corps de la réponse. Il n’y a aucune tâche à interroger,
aucune étape d’envoi préalable et aucune ressource à nettoyer ensuite : une
requête entre, un document sort. Apprenez cette forme une fois et toutes les
pages d’action se lisent de la même façon.

## Toutes les requêtes se ressemblent

Chaque action est un unique `POST` vers `/v1/<action>` avec un corps
`multipart/form-data`. Trois éléments sont toujours présents :

- L’en-tête `X-API-Key` qui porte votre clé secrète, en HTTPS.
- Une partie `file` contenant le PDF d’entrée.
- Zéro, une ou plusieurs parties texte pour les options de l’action (par exemple
  `line_1` ou `pages`), nommées exactement comme les liste la référence de
  l’action.

Voici une requête complète qui appose un filigrane, montrée en HTTP brut :

```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--
```

Lecture partie par partie :

- **Ligne de requête** : `POST /v1/add_text_watermark`. Le nom de l’action est le
  chemin ; la méthode est toujours `POST`.
- **`X-API-Key`** : votre clé authentifie la requête. Voir
  [Authentification](/docs/api/authentication).
- **`Content-Type`** : `multipart/form-data` avec une chaîne de délimitation.
  L’assistant multipart de n’importe quel client HTTP renseigne cet en-tête et la
  délimitation pour vous ; vous l’écrivez rarement à la main.
- **La partie `file`** : le PDF d’entrée, envoyé en binaire.
- **Les parties d’options** : une partie par option, ici `line_1`. Chacune est
  une simple valeur texte.

Vous n’assemblez jamais ce corps vous-même. Le client HTTP de chaque langage le
construit à partir d’un descripteur de fichier et de quelques champs. La même
requête en 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 de base par défaut est `https://api.pdfblocks.com`. Pour garder le
  traitement dans une juridiction précise, remplacez l’hôte par un hôte régional,
  voir [Régions et résidence des données](/docs/api/regions-and-data-residency).
  Seul l’hôte change ; le chemin, les en-têtes et le corps sont partout
  identiques.
</Info>

## Chaque réponse est le document

Une action à sortie unique répond `200 OK` avec le PDF traité comme corps brut :

```http
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 48213

%PDF-1.7
<binary PDF bytes>
```

Le corps est le document terminé, pas un JSON enveloppant une URL, ni une chaîne
base64. Écrivez-le en flux directement dans un fichier ou passez-le à l’étape suivante de
votre pipeline. En cURL, c’est le `-o watermarked.pdf` ci-dessus ; dans le code,
c’est écrire les octets de `response` sur le disque, exactement comme le font les
exemples de chaque page d’action.

## Stateless par conception

L’API ne stocke rien. Votre document est traité en mémoire, dans la région que
vous adressez, et abandonné dès que la réponse est écrite. Il n’existe aucun
identifiant de document à réutiliser plus tard, ni aucune copie côté serveur à
supprimer. Comme rien ne persiste entre les appels, chaque requête doit porter
son propre `file` d’entrée, y compris lorsque vous enchaînez des actions et que
vous injectez la sortie d’un appel directement dans le suivant (voir
[Enchaîner les actions](/docs/api/chaining-actions)).

## Là où le contrat varie

Trois choses se greffent sur cette base, chacune documentée sur sa propre page :

- **Plus d’une entrée.**
  [Fusionner des documents](/docs/api/merge-pdf-documents) prend un tableau
  ordonné de parties `file`, et
  [Ajouter un filigrane image](/docs/api/add-image-watermark-to-pdf)
  prend une seconde partie binaire `image`. Les deux sont traitées dans
  [Travailler avec les fichiers](/docs/api/working-with-files).
- **Plus d’une sortie.** La famille des divisions renvoie plusieurs documents, et
  vous choisissez le conditionnement, ZIP, JSON ou multipart, avec l’en-tête
  `Accept`. Voir
  [Formats de réponse et négociation de contenu](/docs/api/response-formats).
- **Les échecs.** Toute erreur renvoie un corps `application/problem+json`
  conforme à la RFC 7807, jamais un PDF partiel. Voir
  [Erreurs](/docs/api/errors).