# 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).