# Requisições e respostas O formato que toda chamada compartilha: uma requisição de formulário multipart, uma resposta que é um documento e nenhum estado guardado entre as duas. Toda ação da API compartilha um mesmo contrato. Você envia uma requisição `multipart/form-data` com seu PDF em um campo `file` e recebe de volta o documento processado no corpo da resposta. Não há tarefa para consultar, nem etapa de upload, nem recurso para limpar depois: uma requisição entra, um documento sai. Aprenda esse formato uma vez e todas as páginas de ação passam a se ler da mesma maneira. ## Toda requisição tem o mesmo formato Cada ação é um único `POST` para `/v1/<action>` com um corpo `multipart/form-data`. Três coisas estão sempre presentes: - O cabeçalho `X-API-Key` com sua chave secreta, por HTTPS. - Uma parte `file` com o PDF de entrada. - Zero ou mais partes de texto para as opções da ação (por exemplo `line_1` ou `pages`), com os nomes exatos que a referência da ação lista. Veja uma requisição completa que carimba uma marca-d’água, mostrada como HTTP bruto: ```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-- ``` Lendo parte por parte: - **Linha de requisição**: `POST /v1/add_text_watermark`. O nome da ação é o caminho; o método é sempre `POST`. - **`X-API-Key`**: sua chave autentica a requisição. Consulte [Autenticação](/docs/api/authentication). - **`Content-Type`**: `multipart/form-data` com uma string delimitadora. O auxiliar multipart de qualquer cliente HTTP define esse cabeçalho e o delimitador para você; raramente você o escreve à mão. - **A parte `file`**: o PDF de entrada, enviado como binário. - **Partes de opção**: uma parte por opção, aqui `line_1`. Cada uma é um valor de texto simples. Você nunca monta esse corpo à mão. O cliente HTTP de qualquer linguagem o constrói a partir de um arquivo aberto e de alguns campos. A mesma requisição em 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> A URL base padrão é `https://api.pdfblocks.com`. Para manter o processamento em uma jurisdição específica, troque o host por um host regional. Consulte [Regiões e residência de dados](/docs/api/regions-and-data-residency). Só o host muda; o caminho, os cabeçalhos e o corpo são idênticos em toda parte. </Info> ## Toda resposta é o documento Uma ação de saída única responde com `200 OK` e traz no corpo bruto o PDF processado: ```http HTTP/1.1 200 OK Content-Type: application/pdf Content-Length: 48213 %PDF-1.7 <binary PDF bytes> ``` O corpo é o documento pronto, não um JSON envolvendo uma URL nem uma string base64. Grave-o em fluxo direto em um arquivo ou passe-o para a próxima etapa do seu pipeline. Em cURL, é o `-o watermarked.pdf` acima; no código, é gravar os bytes de `response` em disco, exatamente como fazem os exemplos de cada página de ação. ## *Stateless* por design A API não armazena nada. Seu documento é processado na memória, na região que você endereça, e descartado assim que a resposta é escrita. Não existe um ID de documento para consultar depois nem uma cópia no servidor para excluir. Como nada persiste entre as chamadas, cada requisição precisa levar o seu próprio `file` de entrada, inclusive quando você encadeia ações e alimenta uma chamada com a saída da anterior (consulte [Encadear ações](/docs/api/chaining-actions)). ## Onde o contrato varia Três coisas se apoiam nessa base, cada uma documentada na sua própria página: - **Mais de uma entrada.** [Mesclar documentos](/docs/api/merge-pdf-documents) recebe uma matriz ordenada de partes `file`, e [Adicionar uma marca-d’água de imagem](/docs/api/add-image-watermark-to-pdf) recebe uma segunda parte binária `image`. As duas são tratadas em [Trabalhar com arquivos](/docs/api/working-with-files). - **Mais de uma saída.** A família de divisão retorna vários documentos, e você escolhe o empacotamento (ZIP, JSON ou multipart) com o cabeçalho `Accept`. Consulte [Formatos de resposta](/docs/api/response-formats). - **Falhas.** Qualquer erro retorna um corpo `application/problem+json` seguindo a RFC 7807, nunca um PDF parcial. Consulte [Erros](/docs/api/errors).