解析文档 API
此端点的作用
PDF4me 解析文档 使用您保存的解析模板对 PDF 并返回提取的字段 JSON 单个 REST 致电。发送 PDF 作为 Base64， 这 模板 ID 从控制面板和客户端生成的 解析 ID并接收一个结构化的响应，该响应以您在模板中定义的名称为键。该模板包含提取逻辑（正则表达式 对于稳定模式， JavaScript 表达 对于条件规则），因此，同一个调用可以提取发票、合同、收据以及您配置的任何自定义文档布局。
调用此端点之前： 在解析模板中创建解析模板 PDF4me 仪表盘。请参阅 准备文档解析信息 有关完整的设置步骤，请参阅正则表达式示例（INV-\d{6,10} 发票号码 \d{2}/\d{2}/\d{4} （日期），以及两个工作单位 JavaScript 表达式分类器样本。
验证您的身份 API 要求
每一个 PDF4me REST 通话必须包含您的 API 关键在于 Authorization 头部信息。在开发者控制面板中创建或选择一个密钥，并将其保存在服务器端。切勿将其暴露在浏览器代码中。
您不容错过的重要事实
文档内容， 文档名称， 和 异步 是必需的。 模板 ID， 模板名称， 和 解析 ID 这些字段是可选的，只有当您希望响应内容与自定义捕获字段关联时才需要。如果没有它们， API 仍然返回有用的默认字段，例如 文档类型 和 页数。application/json 模板中每个捕获键对应一个字段，外加默认字段。这与返回原始二进制文件的 Protect、Compress 和 Convert 端点不同。 PDFs解析文档始终返回 JSON 因为它返回的是结构化数据，而不是文件。REST API 端点
方法： 邮政
URL： https://api.pdf4me.com/api/v2/ParseDocument
发送 Content-Type: application/json 以及 授权 带有您标题的标题 API 键。设置 异步 到 错误的 对于同步响应（HTTP 200 已解析 JSON）， 或者 真的 接收 HTTP 202 加一个 地点 轮询该标头，直到它返回 200 并包含已解析的内容。 JSON。
Postman 请求设置
| 环境 | 价值 |
|---|---|
| Method | POST |
| URL | https://api.pdf4me.com/api/v2/ParseDocument |
| Headers | Content-Type: application/json |
| Authorization | Basic Auth with your API key, or header Authorization: Basic YOUR_API_KEY |
| Body | raw JSON with docContent, docName, async (and optional TemplateId, TemplateName, ParseId) |
| Response (sync) | When async is false: HTTP 200 with parsed JSON containing one field per template key plus default fields such as documentType and pageCount. |
| Response (async) | When async is true: HTTP 202 with a Location header. GET that URL until you receive 200 with the parsed JSON. Useful for large PDFs or batch processing. |
参数
始终需要： 文档内容， 文档名称， 异步。 条件（基于模板的提取）： 模板 ID （推荐）或 模板名称 加 解析 ID如果没有这些， API 仍然返回有用的默认字段（documentType、pageCount），但不返回自定义键值。
| 范围 | 必需的 | 类型 | 它的作用 | 例子 |
|---|---|---|---|---|
docContent | Yes | Base64 String | The source PDF file encoded as Base64 (no data: prefix). Read the file as bytes and run it through your language's Base64 encoder. | JVBERi0xLjQK... |
docName | Yes | String | Filename of the source PDF including .pdf extension. Used for tracking and error messages. | invoice.pdf |
async | Yes | Boolean | Processing mode. false returns parsed JSON immediately with HTTP 200. true returns HTTP 202 plus a Location header that you poll until it returns 200 with the parsed JSON. Use true for large PDFs or batch processing. | true |
TemplateId | Conditional | String (GUID) | GUID of the saved parse template. Recommended over TemplateName for stable production automation. Get it from the template detail panel after Save Changes in the dashboard. | 12345678-1234-1234-1234-123456789abc |
TemplateName | Conditional | String | Template name as typed in the dashboard. Lookup alternative to TemplateId. Renaming the template breaks calls that reference it by name, so prefer TemplateId in production. | invoice_template |
ParseId | Conditional | String (GUID) | Client-generated GUID per call. Used to correlate the request with the parse output for logging and audit trails. Generate with uuid.uuid4 (Python), Guid.NewGuid (C#), UUID.randomUUID (Java). | 87654321-4321-4321-4321-cba987654321 |
请求示例
示例 A：最小有效载荷（无模板）
最小的呼叫 API 接受请求。返回默认字段（documentType、pageCount），但不返回自定义键值，因为没有引用模板。
{
"docContent": "JVBERi0xLjQK...",
"docName": "invoice.pdf",
"async": true
}
示例 B：基于模板的提取（生产模式）
推荐的生产环境有效负载。它会根据模板中定义的捕获键返回一个字段，外加一些默认字段。
{
"docContent": "JVBERi0xLjQK...",
"docName": "invoice.pdf",
"TemplateId": "12345678-1234-1234-1234-123456789abc",
"ParseId": "87654321-4321-4321-4321-cba987654321",
"async": true
}
示例 C：按名称查找模板
当您没有现成的 TemplateId 时，可以使用此查找方法。请避免在生产环境中使用此方法，因为重命名模板会导致此调用失效。
{
"docContent": "JVBERi0xLjQK...",
"docName": "invoice.pdf",
"TemplateName": "invoice_template",
"ParseId": "87654321-4321-4321-4321-cba987654321",
"async": true
}
成功响应（同步， async: false）
HTTP 200 已解析 JSON模板中的每个捕获键都会成为一个字段。默认字段（documentType， pageCount) 总是会被返回。
{
"parsedData": {
"invoiceNumber": "INV-2024-001",
"invoiceDate": "15/01/2024",
"totalAmount": "$1,250.50",
"customerName": "Acme Corporation"
},
"documentType": "invoice",
"pageCount": 1
}
成功响应（异步， async: true）
HTTP 202 带一个 Location 标题。轮询 URL 和 GET （相同的 Authorization 标头）直到您收到 HTTP 200 已解析 JSON。
HTTP/1.1 202 Accepted
Location: https://api.pdf4me.com/api/v2/ParseDocumentStatus/<job-id>
curl 示例
curl -X POST https://api.pdf4me.com/api/v2/ParseDocument \
-H "Content-Type: application/json" \
-H "Authorization: Basic YOUR_API_KEY" \
-d '{
"docContent": "JVBERi0xLjQK...",
"docName": "invoice.pdf",
"TemplateId": "12345678-1234-1234-1234-123456789abc",
"ParseId": "87654321-4321-4321-4321-cba987654321",
"async": true
}'
模板设置
解析模板包含了所有提取逻辑。只需在控制面板中配置一次，然后调用即可。 TemplateId 从任何地方。
正则表达式稳定模式INV-\d{6,10}），日期（\d{2}/\d{2}/\d{4}），金额（$?\d{1,3}(?:,\d{3})*(?:.\d{2})?）、税务识别号、邮政编码。约 80% 的生产密钥使用这些信息。JavaScript 表达式条件逻辑和分类器文本你的函数返回一个字符串。参见 准备文档解析信息 两个工作分类器示例（functionFormatTextDate1 和 functionGetInvoiceOrder）。代码示例
预构建的示例加载 PDF将其编码为 Base64， POST 到 /api/v2/ParseDocument并处理同步/异步响应。
集成示例
常见的 REST 集成模式Typical ways developers call Parse Document.
- 观察员发现了一家新供应商 PDFs 从电子邮件收件箱或云文件夹。
- 您的服务会读取每个 PDF 将其编码为字节并进行编码 Base64。
- POST 到
/api/v2/解析文档使用发票模板 ID 和新的解析 ID。 - 映射返回结果
发票号，总金额， 和发票日期直接导入数据库 INSERT。
- A JavaScript 模板中的表达式键返回文档类型（发票、订单、条款）。
- POST 返回类型以及通过正则表达式提取的字段。 JSON 回复。
- 您的代码根据类型字段进行分支，并将结构化数据路由到正确的下游系统。
- 对于超过几兆字节的文件， POST 和
异步：是。 - 阅读
地点202 响应的头部信息。 - 民意调查 URL 和 GET 每10秒（ Python 示例最多使用 15 次重试）。
- 当响应状态为 200 时，解析 JSON 主体并继续进行下游加工。