# Solicitudes y respuestas

La forma que comparte toda llamada: una solicitud de formulario multipart, una respuesta con el documento y ningún estado guardado entre ambas.

Todas las acciones de la API comparten un mismo contrato. Usted envía una
solicitud `multipart/form-data` con su PDF en un campo `file` y recibe el
documento procesado como cuerpo de la respuesta. No hay un trabajo que
consultar, ni un paso de carga, ni un recurso que limpiar después: entra una
solicitud, sale un documento. Aprenda esta forma una vez y todas las páginas
de acciones se leerán igual.

## Todas las solicitudes tienen la misma forma

Cada acción es un único `POST` a `/v1/<action>` con un cuerpo
`multipart/form-data`. Siempre están presentes tres cosas:

- La cabecera `X-API-Key` con su clave secreta, por HTTPS.
- Una parte `file` con el PDF de entrada.
- Cero o más partes de texto con las opciones de la acción (por ejemplo
  `line_1` o `pages`), con exactamente los nombres que indica la referencia
  de la acción.

Esta es una solicitud completa que estampa una marca de agua, mostrada como
HTTP en crudo:

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

Leyéndola parte por parte:

- **Línea de solicitud**: `POST /v1/add_text_watermark`. El nombre de la
  acción es la ruta; el método siempre es `POST`.
- **`X-API-Key`**: su clave autentica la solicitud. Consulte
  [Autenticación](/docs/api/authentication).
- **`Content-Type`**: `multipart/form-data` con una cadena de límite. El
  ayudante multipart de cualquier cliente HTTP establece esta cabecera y el
  límite por usted; rara vez se escribe a mano.
- **La parte `file`**: el PDF de entrada, enviado como binario.
- **Partes de opciones**: una parte por opción, aquí `line_1`. Cada una es un
  valor de texto simple.

Nunca tendrá que armar ese cuerpo usted mismo. El cliente HTTP de cualquier
lenguaje lo construye a partir de un manejador de archivo y unos pocos
campos. La misma solicitud 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>
  La URL base predeterminada es `https://api.pdfblocks.com`. Para mantener el
  procesamiento en una jurisdicción concreta, cambie el host por uno
  regional: consulte [Regiones y residencia de
  datos](/docs/api/regions-and-data-residency). Solo cambia el host; la ruta,
  las cabeceras y el cuerpo son idénticos en todas partes.
</Info>

## Toda respuesta es el documento

Una acción de salida única responde con `200 OK` y el PDF procesado como
cuerpo en crudo:

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

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

El cuerpo es el documento terminado: no es un JSON que envuelve una URL, ni
una cadena en base64. Escríbalo directamente en un archivo o páselo al paso
siguiente de su pipeline. En cURL eso es el `-o watermarked.pdf` de arriba;
en código es escribir los bytes de `response` en disco, tal como hacen los
ejemplos de cada página de acción.

## Sin estado por diseño

La API no almacena nada. Su documento se procesa en memoria, en la región a
la que se dirige, y se descarta en cuanto se escribe la respuesta. No hay un
identificador de documento al que referirse después ni una copia en el
servidor que borrar. Como no persiste nada entre llamadas, cada solicitud
debe llevar su propio `file` de entrada, incluso cuando encadena acciones y
pasa la salida de una llamada directamente a la siguiente (consulte
[Encadenar acciones](/docs/api/chaining-actions)).

## Dónde varía el contrato

Sobre esta base se apoyan tres cosas, cada una documentada en su propia
página:

- **Más de una entrada.** [Unir documentos](/docs/api/merge-pdf-documents)
  recibe una matriz ordenada de partes `file`, y [Añadir una marca de agua de
  imagen](/docs/api/add-image-watermark-to-pdf) recibe una segunda parte
  binaria `image`. Ambas se tratan en [Trabajar con
  archivos](/docs/api/working-with-files).
- **Más de una salida.** La familia de división devuelve varios documentos y
  el empaquetado (ZIP, JSON o multipart) se elige con la cabecera `Accept`.
  Consulte [Formatos de respuesta](/docs/api/response-formats).
- **Fallos.** Cualquier error devuelve un cuerpo `application/problem+json`
  conforme a RFC 7807, nunca un PDF parcial. Consulte
  [Errores](/docs/api/errors).