# Trabalhar com arquivos

Como anexar arquivos de entrada a uma requisição: um único PDF, uma lista ordenada para mesclar, uma segunda imagem para marcas-d’água e os limites de cada caso.

As entradas são enviadas como partes binárias de uma requisição
`multipart/form-data`. A maioria das ações recebe exatamente um PDF em um campo
`file`, mas duas ações precisam de mais: a mesclagem recebe um array ordenado de
arquivos, e a marca-d’água de imagem recebe um segundo binário ao lado do PDF.
Esta página cobre as três formas de entrada.

## Um único arquivo

O caso padrão. Anexe um PDF no campo `file` e adicione as opções da ação como
campos de texto:

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

O `@` em `-F file=@input.pdf` diz ao cURL para enviar o conteúdo do arquivo. Toda
ação de entrada única (marcas-d’água, segurança, operações de página, divisões)
funciona assim.

## Vários arquivos: a mesclagem

[Mesclar documentos PDF](/docs/api/merge-pdf-documents) é a única ação que aceita
um array. Envie o campo `file` **mais de uma vez**, e os documentos são mesclados
na ordem em que as partes aparecem na requisição. Forneça pelo menos um arquivo;
você pode enviar muitos em uma única chamada.

<Warning>
  A ordem é posicional, portanto envie as partes na sequência em que quer que
  sejam mescladas. Quando o seu cliente HTTP expõe um objeto de formulário, use o
  método *append* dele (e não *set*) para que repetir `file` acrescente partes em
  vez de sobrescrever a anterior.
</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>
  Se repetir o campo `file` for incômodo no seu cliente HTTP (o cURL do PHP, os
  auxiliares de formulário do Ruby), envie em vez disso os campos numerados
  `file_1` a `file_10`; eles são mesclados em ordem numérica. Use o array `file`
  repetido quando precisar de mais de dez documentos.
</Note>

## Uma imagem ao lado do PDF: a marca-d’água de imagem

[Adicionar uma marca-d’água de imagem](/docs/api/add-image-watermark-to-pdf)
recebe duas partes binárias: o PDF em `file` e a imagem da marca-d’água em um
campo `image`. A imagem precisa ser **PNG ou JPEG**. As duas partes são
obrigatórias.

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

Os campos restantes (`transparency`, `margin`, `pages`) são opções de texto
comuns; consulte a referência da ação para ver seus intervalos e valores padrão.

## Entradas aceitas e tamanho

- A entrada `file` (e cada arquivo mesclado) precisa ser um PDF legível. Um
  arquivo que não pode ser analisado como PDF retorna um `400` nomeando o campo
  `file`. Consulte [Erros](/docs/api/errors).
- A entrada `image` da marca-d’água de imagem precisa ser PNG ou JPEG.
- Quais páginas uma ação afeta é uma questão separada de como você anexa o
  arquivo. Expresse as seleções de páginas com o campo `pages` documentado em
  [Selecionar páginas](/docs/api/selecting-pages).

Para documentos grandes (upload e download em fluxo, tempos limite e novas
tentativas), consulte [Trabalhar com arquivos
grandes](/docs/api/working-with-large-files).