# Trabajar con archivos

Cómo adjuntar los archivos de entrada a una solicitud: un solo PDF, una lista ordenada para unir, una segunda imagen para las marcas de agua y los límites de cada uno.

Las entradas se envían como partes binarias de una solicitud
`multipart/form-data`. La mayoría de las acciones reciben exactamente un PDF
en un campo `file`, pero dos necesitan más: unir recibe una matriz ordenada
de archivos, y la marca de agua de imagen recibe un segundo binario junto al
PDF. Esta página cubre las tres formas de entrada.

## Un solo archivo

El caso predeterminado. Adjunte un PDF en el campo `file` y añada las
opciones de la acción 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
```

La `@` de `-F file=@input.pdf` indica a cURL que envíe el contenido del
archivo. Todas las acciones de entrada única, es decir marcas de agua,
seguridad, operaciones de páginas y divisiones, funcionan así.

## Varios archivos: unir

[Unir documentos](/docs/api/merge-pdf-documents) es la única acción que
acepta una matriz. Envíe el campo `file` **más de una vez** y los documentos
se unirán en el orden en que aparecen las partes en la solicitud. Envíe al
menos un archivo; puede enviar muchos en una sola llamada.

<Warning>
  El orden es posicional, así que envíe las partes en la secuencia en que
  quiere unirlas. Cuando su cliente HTTP expone un objeto de formulario, use
  su método *append* (no *set*) para que repetir `file` añada partes en
  lugar de sobrescribir la 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>
  Si repetir el campo `file` resulta incómodo en su cliente HTTP (cURL de
  PHP, los ayudantes de formularios de Ruby), envíe en su lugar campos
  numerados de `file_1` a `file_10`: se unen en orden numérico. Use la matriz
  `file` repetida cuando necesite más de diez documentos.
</Note>

## Una imagen junto al PDF: marca de agua de imagen

[Añadir una marca de agua de imagen](/docs/api/add-image-watermark-to-pdf)
recibe dos partes binarias: el PDF en `file` y la imagen de la marca de agua
en un campo `image`. La imagen debe ser **PNG o JPEG**. Ambas partes son
obligatorias.

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

Los campos restantes, `transparency`, `margin` y `pages`, son opciones de
texto normales; consulte la referencia de la acción para conocer sus rangos y
valores predeterminados.

## Entradas y tamaños admitidos

- La entrada `file` (y cada archivo que se une) debe ser un PDF legible. Un
  archivo que no se puede analizar como PDF devuelve un `400` que indica el
  campo `file`; consulte [Errores](/docs/api/errors).
- La entrada `image` de la marca de agua de imagen debe ser PNG o JPEG.
- Qué páginas toca una acción es un asunto distinto de cómo adjunta el
  archivo. Exprese las selecciones de páginas con el campo `pages`
  documentado en [Seleccionar páginas](/docs/api/selecting-pages).

Para documentos grandes, con el envío y la descarga en streaming, los tiempos
de espera y los reintentos, consulte [Trabajar con archivos
grandes](/docs/api/working-with-large-files).