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