合并多个 PDF 文件

PDF4me 合并 是一个 REST 结合多个端点的端点 PDFs 合并成一个文档。 POST 一个数组 Base64将编码文件转换为 /api/v2/Merge 带有输出名称，以及 API 按数组顺序将它们连接起来，并返回合并后的结果。 PDF 以原始字节形式设置 async 对于大批量订单和轮询来说，情况确实如此。 Location URL 直到结果出来为止。

此端点的作用

需要两个或两个以上 PDFs 返回以下三种结果之一：发票及附件、封面页及报告，或将扫描件合并为一个文件的文件夹。数组顺序即为页面顺序，因此您的代码可以完全控制结果。这是简单的连接端点；覆盖 pages 在两者之上还有一个单独的操作（合并叠加）。

验证您的身份 API 要求

每一个 PDF4me REST 通话必须包含您的 API 关键在于 Authorization 请求头设置为基本身份验证。请从开发者控制面板获取或轮换您的密钥。

Get your API Key

端点

POST/api/v2/合并

邮递员 URLhttps://api.pdf4me.com/api/v2/Merge

您不容错过的重要事实

docContent 是一个数组，顺序很重要。

与大多数 PDF4me 终点 docContent 是一个字符串，这里它是一个数组 Base64 字符串。数组顺序即为合并顺序；没有单独的排序参数。

200 响应是 PDF 自身

身体是原始的二进制数据，而不是…… JSON 包装器。直接将字节写入。pdf 文件。 JSON解析响应或 Base64解码会破坏输出结果。

对于大批量处理，异步操作为真。

和 "异步": true 这 API 答案 202 Accepted 与一个 Location 标头。用以下方式轮询它 GET 大约每隔 10 秒（官方样本使用 10 秒间隔，最多重试 20 次），直到 200 返回合并后的文件。

HTTP 设置

方法： POST
URL： https://api.pdf4me.com/api/v2/Merge
内容类型： application/json
Authorization： 基本 <您的 PDF4me API 键>

200 响应正文是合并后的。 PDF 以原始字节格式保存：直接保存。202 响应表示合并操作正在异步运行：轮询 Location URL 直到200年。

同步处理和异步处理有何区别？

这 async 标志位会更改响应契约，而不是合并结果。按批次大小选择。

同步与异步	`"async": false` （默认）	`"async": true`
对……的回应 success	合并后的200 PDF 原始字节	202 Accepted 与一个 `Location` 民意调查 URL
联系	保持打开状态直至合并完成。	立即退货
如何获取文件	直接保存响应体	GET 这 Location URL 每隔大约 10 秒返回一次，直到返回 200 字节。
最适合	几个小文件	大批量和大型文件

API 身体场

范围	必需的	类型	它的作用	例子
`docContent`	Required	array of strings	An array of Base64-encoded PDF files, at least two entries. The array order is the merge order of the output document.	`["JVBERi0x...", "JVBERi0x..."]`
`docName`	Required	string	Output filename for the merged PDF.	`merged.pdf`
`async`	Optional	boolean	false (default) returns the merged PDF directly on 200. true returns 202 plus a Location URL to poll, for large batches.	`true`

示例有效载荷

合并两个 PDFs 同步

{
 "docContent": [
 "JVBERi0xLjcKJb...first PDF Base64...",
 "JVBERi0xLjcKJb...second PDF Base64..."
 ],
 "docName": "merged.pdf"
}

异步合并大批量数据

{
 "docContent": [
 "JVBERi0x...cover...",
 "JVBERi0x...report...",
 "JVBERi0x...appendix-a...",
 "JVBERi0x...appendix-b..."
 ],
 "docName": "quarterly-pack.pdf",
 "async": true
}

邮递员收款小贴士

Headers

Content-Type: application/json + Authorization: Basic <apiKey>.

Body

raw JSON. docContent is an ARRAY of Base64 strings, one per source PDF, in merge order.

Response

On 200, switch Postman to "Send and Download": the body is the PDF itself, not JSON.

Async

With async true, copy the Location header from the 202 response into a GET request and poll it until 200.

curl 示例

curl -X POST https://api.pdf4me.com/api/v2/Merge \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic YOUR_API_KEY" \
 -d '{
 "docContent": [
 "'"$(base64 -w 0 first.pdf)"'",
 "'"$(base64 -w 0 second.pdf)"'"
 ],
 "docName": "merged.pdf"
 }' \
 --output merged.pdf

什么 API 返回？

场地	类型	它包含什么
`200 response body`	Binary (application/pdf)	The merged PDF file itself as raw bytes. Save it directly to disk; do not JSON-parse or Base64-decode.
`202 Location header`	URL	Async mode only: the polling URL. GET it about every 10 seconds until it returns 200 with the merged PDF bytes.
`4xx/5xx response body`	JSON or text	Error details: 400 for malformed Base64 or a bad payload shape, 401 for a missing or invalid API key, 500 for server-side processing failures.

代码示例

针对此特定端点的官方可运行示例 language：

常问问题

How is the merge order decided?+

By the docContent array order. The first Base64 string becomes the first pages of the output, the second is appended after it, and so on. Reorder the array to reorder the merged document.

Is the response JSON with a Base64 file inside?+

No. A 200 response body is the merged PDF itself as raw binary bytes. Write response.content straight to a .pdf file; do not JSON-parse or Base64-decode it.

When should I set async to true?+

For large batches or big files. With async true the API returns 202 Accepted plus a Location header; poll that URL with GET requests about every 10 seconds until it returns 200 with the merged PDF.

Can I merge Word or Excel files with this endpoint?+

No. /api/v2/Merge accepts PDFs only. Merge Word files with the Merge Documents Word endpoint, or convert other formats to PDF first and then merge the results here.

How many PDFs can I merge in one call?+

The docContent array accepts multiple documents in a single request; two entries is the minimum meaningful merge. For very large batches, set async true so the merge runs server-side while you poll for the result.

What is the difference between Merge and Merge Overlay?+

Merge appends documents one after another, page by page. Merge Overlay stamps the pages of one PDF on top of the pages of another, which is what you want for letterheads and backgrounds.

Why am I getting a 400 Bad Request?+

The usual causes are a docContent that is a single string instead of an array, an entry that is not valid Base64, or a source file that is not actually a PDF. Encode each file separately and keep the array shape.

为什么要合并 PDFs 通过 API 而不是桌面工具？

桌面和网页合并工具对于一次性任务来说还不错，但它们需要人工选择文件、拖拽排序并下载结果。 API 它执行与每个批次一个确定性请求相同的连接操作，顺序由您的代码固定，而不是通过拖放操作。输出是标准格式。 PDF 符合 ISO 32000 规格因此，它可以在任何读取器中打开，并顺利地进入下一个流程步骤，无论是压缩还是其他操作。 OCR或者电子签名。