快速入门

本指南将引导您完成环境配置，并使用 DocMap API 发起您的第一个提取请求。

前置条件

在开始之前，请确保您已具备以下条件：

1. DocMap 账户 -- 如果您还没有账户，请在 docmap.io 注册。
2. 至少一个提取模板 -- 在控制面板中创建一个模板，定义您想从文档中提取的字段。

TIP

模板定义了您想要提取的数据结构。例如，发票模板可能包含 vendor_name、invoice_number、total_amount 和 line_items 数组等字段。您可以在进行任何 API 调用之前，通过控制面板创建和管理模板。

基础 URL

所有 API 请求发送到：

https://api.docmap.io

所有端点均以 /v1/ 为前缀。例如，提取端点为：

https://api.docmap.io/v1/extractions/run

创建 API 密钥

1. 前往 控制面板 > 设置 > API 密钥。
2. 点击 创建 API 密钥。
3. 为您的密钥输入一个描述性名称（例如"生产服务器"或"本地开发"）。
4. 选择有效期。
5. 立即复制密钥 -- 密钥仅显示一次，之后无法再次获取。

WARNING

请安全存储您的 API 密钥。密钥仅在创建时显示一次。如果丢失，您需要创建一个新密钥。

您的 API 密钥格式为 dm_live_...，需在每个请求的 Authorization 头中使用。

您的第一个请求

通过检查 API 健康检查端点来验证您的配置：

curl

curl https://api.docmap.io/health

TypeScript

const res = await fetch('https://api.docmap.io/health')
const data = await res.json()
console.log(data) // { status: "ok" }

Python

import requests
res = requests.get('https://api.docmap.io/health')
print(res.json())  # {"status": "ok"}

如果一切正常，您将收到：

{ "status": "ok" }

运行您的第一次提取

准备好 API 密钥和模板后，您就可以从 PDF 中提取结构化数据了。将您的 PDF 文件编码为 base64 字符串，然后发送到 /v1/extractions/run 端点。

curl

curl -X POST https://api.docmap.io/v1/extractions/run \
  -H "Authorization: Bearer dm_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "your-template-id",
    "fileName": "invoice.pdf",
    "pdfBase64": "JVBERi0xLjQ...",
    "mimeType": "application/pdf"
  }'

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/extractions/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 'your-template-id',
    fileName: 'invoice.pdf',
    pdfBase64: 'JVBERi0xLjQ...', // base64-encoded PDF
    mimeType: 'application/pdf',
  }),
})

const data = await response.json()
console.log(data)

Python

import requests
import base64

api_key = "dm_live_your_api_key"

# Read and encode the PDF
with open("invoice.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.docmap.io/v1/extractions/run",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "templateId": "your-template-id",
        "fileName": "invoice.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

print(response.json())

示例响应

成功的提取将返回与模板字段匹配的提取数据：

{
  "id": "ext_abc123",
  "templateId": "your-template-id",
  "fileName": "invoice.pdf",
  "status": "completed",
  "data": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-001",
    "invoice_date": "2024-11-15",
    "total_amount": 1250.00,
    "currency": "USD",
    "line_items": [
      {
        "description": "Widget A",
        "quantity": 10,
        "unit_price": 125.00
      }
    ]
  },
  "createdAt": "2024-11-20T14:30:00.000Z"
}

查看用量

监控您的 API 用量，以确保不超出计划限额：

curl

curl https://api.docmap.io/v1/usage \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const res = await fetch('https://api.docmap.io/v1/usage', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})
const usage = await res.json()
console.log(usage)

Python

response = requests.get(
    "https://api.docmap.io/v1/usage",
    headers={"Authorization": f"Bearer {api_key}"},
)
print(response.json())

后续步骤

完成第一次提取后，您可以继续探索文档的其他部分：

• 身份认证 -- 了解 API 密钥和安全最佳实践。
• API 参考 -- 所有可用端点的完整参考。