# Mesclar documentos PDF

Combine vários documentos PDF em um só, na ordem em que você os enviar.

Combine vários documentos PDF em um só. Os arquivos são mesclados exatamente na
ordem em que aparecem na requisição, de modo que você controla a sequência final
de páginas. Envie quantos arquivos precisar em uma única chamada. A API é
*stateless*: seu documento é processado na região e nunca é armazenado.

## Endpoint

<Endpoint method="POST" path="/v1/merge_documents" />

Disponível em todas as regiões. Consulte [Regiões e residência de
dados](/docs/api/regions-and-data-residency) para o roteamento e a residência
de dados.

| Região               | URL                                                  |
| -------------------- | ---------------------------------------------------- |
| Global               | `https://api.pdfblocks.com/v1/merge_documents`       |
| Estados Unidos       | `https://us.api.pdfblocks.com/v1/merge_documents`    |
| HIPAA Estados Unidos | `https://hipaa.api.pdfblocks.com/v1/merge_documents` |
| União Europeia       | `https://eu.api.pdfblocks.com/v1/merge_documents`    |
| Reino Unido          | `https://uk.api.pdfblocks.com/v1/merge_documents`    |
| Canadá               | `https://ca.api.pdfblocks.com/v1/merge_documents`    |
| Austrália            | `https://au.api.pdfblocks.com/v1/merge_documents`    |
| Japão                | `https://jp.api.pdfblocks.com/v1/merge_documents`    |
| Índia                | `https://in.api.pdfblocks.com/v1/merge_documents`    |
| Brasil               | `https://br.api.pdfblocks.com/v1/merge_documents`    |

## Autenticação

Autentique cada requisição com sua chave de API secreta no cabeçalho
`X-API-Key`, por HTTPS. Crie e gerencie suas chaves no
[dashboard](https://dashboard.pdfblocks.com). Consulte
[Autenticação](/docs/api/authentication) para mais detalhes.

## Requisição

O endpoint aceita um corpo de requisição `multipart/form-data`.

<ParamField name="file" type="file[]" required>
  Os documentos PDF de entrada, enviados como partes `file` repetidas. Forneça
  pelo menos uma; envie quantos arquivos precisar em uma única requisição. Os
  documentos são mesclados exatamente na ordem em que as partes aparecem na
  requisição. Consulte [Trabalhar com arquivos](/docs/api/working-with-files)
  para saber como enviar várias partes `file`.
</ParamField>

## Exemplos

Mescle três PDFs em um só, na ordem:

<CodeGroup>

```bash title="cURL"
curl https://api.pdfblocks.com/v1/merge_documents \
  -H 'X-API-Key: your_api_key' \
  -F file=@chapter-1.pdf \
  -F file=@chapter-2.pdf \
  -F file=@chapter-3.pdf \
  -o merged.pdf
```

```python title="Python"
# pip install requests
import requests

files = [
    ('file', open('chapter-1.pdf', 'rb')),
    ('file', open('chapter-2.pdf', 'rb')),
    ('file', open('chapter-3.pdf', 'rb')),
]

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();
body.append('file', new Blob([await readFile('chapter-1.pdf')]), 'chapter-1.pdf');
body.append('file', new Blob([await readFile('chapter-2.pdf')]), 'chapter-2.pdf');
body.append('file', new Blob([await readFile('chapter-3.pdf')]), 'chapter-3.pdf');

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()));
```

```php title="PHP"
<?php
// composer require guzzlehttp/guzzle
require 'vendor/autoload.php';

use GuzzleHttp\Client;

// Repeat the `file` part once per document: they merge in the order sent.
$response = (new Client())->post('https://api.pdfblocks.com/v1/merge_documents', [
    'headers' => ['X-API-Key' => 'your_api_key'],
    'multipart' => [
        ['name' => 'file', 'contents' => fopen('chapter-1.pdf', 'r'), 'filename' => 'chapter-1.pdf'],
        ['name' => 'file', 'contents' => fopen('chapter-2.pdf', 'r'), 'filename' => 'chapter-2.pdf'],
        ['name' => 'file', 'contents' => fopen('chapter-3.pdf', 'r'), 'filename' => 'chapter-3.pdf'],
    ],
]);

if ($response->getStatusCode() === 200) {
    file_put_contents('merged.pdf', $response->getBody());
}
```

```ruby title="Ruby"
# gem install http
require 'http'

response = HTTP
  .headers('X-API-Key' => 'your_api_key')
  .post('https://api.pdfblocks.com/v1/merge_documents', form: {
    file: [
      HTTP::FormData::File.new('chapter-1.pdf'),
      HTTP::FormData::File.new('chapter-2.pdf'),
      HTTP::FormData::File.new('chapter-3.pdf'),
    ],
  })

File.write('merged.pdf', response.body) if response.status.success?
```

```go title="Go"
package main

import (
	"bytes"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	var buf bytes.Buffer
	form := multipart.NewWriter(&buf)

	for _, name := range []string{"chapter-1.pdf", "chapter-2.pdf", "chapter-3.pdf"} {
		file, _ := os.Open(name)
		part, _ := form.CreateFormFile("file", name)
		io.Copy(part, file)
		file.Close()
	}
	form.Close()

	req, _ := http.NewRequest("POST", "https://api.pdfblocks.com/v1/merge_documents", &buf)
	req.Header.Set("Content-Type", form.FormDataContentType())
	req.Header.Set("X-API-Key", "your_api_key")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := os.Create("merged.pdf")
	defer out.Close()
	io.Copy(out, res.Body)
}
```

```csharp title="C#"
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your_api_key");

using var form = new MultipartFormDataContent
{
    { new ByteArrayContent(File.ReadAllBytes("chapter-1.pdf")), "file", "chapter-1.pdf" },
    { new ByteArrayContent(File.ReadAllBytes("chapter-2.pdf")), "file", "chapter-2.pdf" },
    { new ByteArrayContent(File.ReadAllBytes("chapter-3.pdf")), "file", "chapter-3.pdf" },
};

var response = await client.PostAsync(
    "https://api.pdfblocks.com/v1/merge_documents", form);
response.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync(
    "merged.pdf", await response.Content.ReadAsByteArrayAsync());
```

</CodeGroup>

## Resposta

Em caso de sucesso, a resposta é `200 OK` com o PDF mesclado no corpo:

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

A saída é um único PDF cuja contagem de páginas é a soma das páginas dos
documentos de entrada, dispostas na ordem da requisição. Grave o corpo
diretamente em um arquivo, como fazem os exemplos acima; nada é armazenado do
nosso lado.

## Erros

Requisições com falha retornam um corpo `application/problem+json`. O erro
mais comum neste endpoint é um `400`, retornado quando uma das partes `file` não
é um PDF legível. O objeto `errors` nomeia o campo:

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "file": ["Could not parse the PDF document. The file may be invalid or corrupt."]
  }
}
```

Uma `X-API-Key` ausente ou inválida retorna um `401`. Consulte
[Erros](/docs/api/errors) para todos os códigos de status e o formato completo
da resposta.

## Receitas

Variações comuns. Expanda uma para vê-la em todas as linguagens.

<AccordionGroup>

<Accordion title="Colocar uma capa antes de um relatório">

<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=@report.pdf \
  -o report-with-cover.pdf
```

```python title="Python"
import requests

files = [
    ('file', open('cover.pdf', 'rb')),
    ('file', open('report.pdf', 'rb')),
]

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('report-with-cover.pdf', 'wb') as output:
    output.write(response.content)
```

```javascript title="Node.js"
import { readFile, writeFile } from 'node:fs/promises';

const body = new FormData();
body.append('file', new Blob([await readFile('cover.pdf')]), 'cover.pdf');
body.append('file', new Blob([await readFile('report.pdf')]), 'report.pdf');

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('report-with-cover.pdf', Buffer.from(await response.arrayBuffer()));
```

```php title="PHP"
<?php
// composer require guzzlehttp/guzzle
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$response = (new Client())->post('https://api.pdfblocks.com/v1/merge_documents', [
    'headers' => ['X-API-Key' => 'your_api_key'],
    'multipart' => [
        ['name' => 'file', 'contents' => fopen('cover.pdf', 'r'), 'filename' => 'cover.pdf'],
        ['name' => 'file', 'contents' => fopen('report.pdf', 'r'), 'filename' => 'report.pdf'],
    ],
]);

if ($response->getStatusCode() === 200) {
    file_put_contents('report-with-cover.pdf', $response->getBody());
}
```

```ruby title="Ruby"
require 'http'

response = HTTP
  .headers('X-API-Key' => 'your_api_key')
  .post('https://api.pdfblocks.com/v1/merge_documents', form: {
    file: [
      HTTP::FormData::File.new('cover.pdf'),
      HTTP::FormData::File.new('report.pdf'),
    ],
  })

File.write('report-with-cover.pdf', response.body) if response.status.success?
```

```go title="Go"
package main

import (
	"bytes"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	var buf bytes.Buffer
	form := multipart.NewWriter(&buf)

	for _, name := range []string{"cover.pdf", "report.pdf"} {
		file, _ := os.Open(name)
		part, _ := form.CreateFormFile("file", name)
		io.Copy(part, file)
		file.Close()
	}
	form.Close()

	req, _ := http.NewRequest("POST", "https://api.pdfblocks.com/v1/merge_documents", &buf)
	req.Header.Set("Content-Type", form.FormDataContentType())
	req.Header.Set("X-API-Key", "your_api_key")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := os.Create("report-with-cover.pdf")
	defer out.Close()
	io.Copy(out, res.Body)
}
```

```csharp title="C#"
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your_api_key");

using var form = new MultipartFormDataContent
{
    { new ByteArrayContent(File.ReadAllBytes("cover.pdf")), "file", "cover.pdf" },
    { new ByteArrayContent(File.ReadAllBytes("report.pdf")), "file", "report.pdf" },
};

var response = await client.PostAsync(
    "https://api.pdfblocks.com/v1/merge_documents", form);
response.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync(
    "report-with-cover.pdf", await response.Content.ReadAsByteArrayAsync());
```

</CodeGroup>

</Accordion>

</AccordionGroup>

## Ações relacionadas

<CardGroup cols={2}>

<Card title="Extrair páginas" href="/docs/api/extract-pages-from-pdf">
  Extraia um subconjunto de páginas do arquivo mesclado.
</Card>

<Card title="Reordenar páginas" href="/docs/api/reorder-pages-of-pdf">
  Reorganize as páginas depois de mesclar.
</Card>

<Card title="Dividir em uma página" href="/docs/api/split-pdf-at-page">
  Separe novamente o documento combinado.
</Card>

<Card title="Adicionar uma marca-d’água de texto" href="/docs/api/add-text-watermark-to-pdf">
  Carimbe o documento mesclado.
</Card>

</CardGroup>