# Travailler avec les fichiers

Comment joindre des fichiers d’entrée à une requête : un seul PDF, une liste ordonnée pour la fusion, une seconde image pour les filigranes, et les limites de chacun.

Les entrées sont envoyées comme parties binaires d’une requête
`multipart/form-data`. La plupart des actions prennent exactement un PDF dans un
champ `file`, mais deux actions en demandent davantage : la fusion prend un
tableau ordonné de fichiers, et le filigrane image prend un second binaire à côté
du PDF. Cette page couvre les trois formes d’entrée.

## Un seul fichier

Le cas par défaut. Joignez un PDF dans le champ `file` et ajoutez les options de
l’action sous forme de champs texte :

```bash title="cURL"
curl https://api.pdfblocks.com/v1/extract_pages \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F pages='1..3' \
  -o extract.pdf
```

Le `@` de `-F file=@input.pdf` indique à cURL d’envoyer le contenu du fichier.
Toutes les actions à entrée unique (filigranes, sécurité, opérations sur les
pages, divisions) fonctionnent ainsi.

## Plusieurs fichiers : la fusion

[Fusionner des documents](/docs/api/merge-pdf-documents) est la seule action
qui accepte un tableau. Envoyez le champ `file` **plusieurs fois** et les
documents sont fusionnés dans l’ordre où les parties apparaissent dans la
requête. Fournissez au moins un fichier ; vous pouvez en envoyer beaucoup en un
seul appel.

<Warning>
  L’ordre est positionnel : envoyez donc les parties dans la séquence où vous
  voulez les fusionner. Quand votre client HTTP expose un objet formulaire,
  utilisez sa méthode *append* (et non *set*) pour que la répétition de `file`
  ajoute des parties au lieu d’écraser la précédente.
</Warning>

<CodeGroup>

```bash title="cURL"
curl https://api.pdfblocks.com/v1/merge_documents \
  -H 'X-API-Key: your_api_key' \
  -F file=@cover.pdf \
  -F file=@body.pdf \
  -F file=@appendix.pdf \
  -o merged.pdf
```

```python title="Python"
# pip install requests
import requests

files = [
    ('file', ('cover.pdf', open('cover.pdf', 'rb'), 'application/pdf')),
    ('file', ('body.pdf', open('body.pdf', 'rb'), 'application/pdf')),
    ('file', ('appendix.pdf', open('appendix.pdf', 'rb'), 'application/pdf')),
]

response = requests.post(
    'https://api.pdfblocks.com/v1/merge_documents',
    headers={'X-API-Key': 'your_api_key'},
    files=files,
)

response.raise_for_status()
with open('merged.pdf', 'wb') as output:
    output.write(response.content)
```

```javascript title="Node.js"
// Node.js 18+
import { readFile, writeFile } from 'node:fs/promises';

const body = new FormData();
for (const name of ['cover.pdf', 'body.pdf', 'appendix.pdf']) {
  body.append('file', new Blob([await readFile(name)]), name);
}

const response = await fetch('https://api.pdfblocks.com/v1/merge_documents', {
  method: 'POST',
  headers: { 'X-API-Key': 'your_api_key' },
  body,
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
await writeFile('merged.pdf', Buffer.from(await response.arrayBuffer()));
```

</CodeGroup>

<Note>
  Si répéter le champ `file` est malcommode dans votre client HTTP (cURL en PHP,
  les assistants de formulaire en Ruby), envoyez plutôt des champs numérotés de
  `file_1` à `file_10` : ils sont fusionnés dans l’ordre numérique. Utilisez le
  tableau `file` répété quand il vous faut plus de dix documents.
</Note>

## Une image à côté du PDF : le filigrane image

[Ajouter un filigrane image](/docs/api/add-image-watermark-to-pdf) prend
deux parties binaires : le PDF dans `file` et l’image du filigrane dans un champ
`image`. L’image doit être au format **PNG ou JPEG**. Les deux parties sont
obligatoires.

```bash title="cURL"
curl https://api.pdfblocks.com/v1/add_image_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F image=@logo.png \
  -o watermarked.pdf
```

Les champs restants (`transparency`, `margin` et `pages`) sont des options texte
ordinaires. Consultez la référence de l’action pour leurs plages et leurs valeurs
par défaut.

## Entrées acceptées et taille

- L’entrée `file` (et chaque fichier fusionné) doit être un PDF lisible. Un
  fichier qui ne peut pas être analysé comme un PDF renvoie un `400` qui nomme le
  champ `file`. Consultez [Erreurs](/docs/api/errors).
- L’entrée `image` du filigrane image doit être au format PNG ou JPEG.
- Les pages qu’une action touche sont une question distincte de la façon dont
  vous joignez le fichier. Exprimez vos sélections de pages avec le champ `pages`
  documenté dans [Sélectionner des pages](/docs/api/selecting-pages).

Pour les gros documents (envoi et téléchargement en flux, délais d’attente,
nouvelles tentatives), consultez
[Travailler avec de gros fichiers](/docs/api/working-with-large-files).