文档资源

Numora 对外 API 中文档接入、状态读取与复核动作的请求和响应模型。

范围

本页定义 Numora 对外 API 开发者预览版中的 document 资源。

API 默认采用异步模式。客户端提交文档后，应保存返回的 id，再通过轮询或 webhook 观察状态变化。

资源模型

每次提交文件都会生成一个 document 资源。

核心字段包括：

id
schema
status
external_id
metadata
created_at
updated_at
review_state
duplicate_of

其中 review_state 应为 null 或一个记录“哪些字段、哪些行项目已被确认”的结构化对象。更完整的语义请继续阅读复核与确认。

创建文档

POST /v1/documents

请求示例：

{
  "schema": "invoice_v2",
  "file_url": "https://example.com/invoice-001.pdf",
  "external_id": "ap-100024",
  "metadata": {
    "source": "email-import",
    "vendor_code": "ACME"
  }
}

响应示例：

{
  "id": "doc_01jpwq4q9m7q4q2k8dax1x1q5n",
  "status": "processing",
  "schema": "invoice_v2",
  "status_url": "/v1/documents/doc_01jpwq4q9m7q4q2k8dax1x1q5n",
  "result_url": "/v1/documents/doc_01jpwq4q9m7q4q2k8dax1x1q5n/result"
}

异步创建返回 202 Accepted。

获取文档状态

GET /v1/documents/{id}

文档生命周期状态包括：

processing
review_required
reviewed
push_pending
push_succeeded
push_failed
failed

关于当前内部 OCR 状态与未来对外 document.status 的精确映射，请继续阅读文档生命周期。

获取文档结果

GET /v1/documents/{id}/result

响应示例：

{
  "id": "doc_01jpwq4q9m7q4q2k8dax1x1q5n",
  "schema": "invoice_v2",
  "status": "review_required",
  "review_state": {
    "version": 1,
    "confirmed_general_field_names": ["invoice_number"],
    "confirmed_line_item_ids": []
  },
  "confidence": 0.93,
  "fields": {
    "vendor_name": {
      "value": "ACME Supplies",
      "confidence": 0.98
    },
    "invoice_number": {
      "value": "INV-2026-001",
      "confidence": 0.97
    }
  },
  "line_items": [],
  "duplicate_of": null
}

复核动作

复核被定义为显式动作，而不是隐式副作用。

POST /v1/documents/{id}/actions/approve
POST /v1/documents/{id}/actions/reject
POST /v1/documents/{id}/actions/retry-push

关于动作语义、review_state 结构以及确认冲突处理，请继续阅读复核与确认。

说明

POST /v1/documents 是合法的接入口，但在首阶段 CRM 交付主路径中，它不是必经第一步。
external_id 可以选填，但强烈建议提供，便于客户端做幂等对账。
在当前预览版里，重试同一份业务文档创建时，应复用同一个 external_id。
结果 schema 必须显式版本化，例如 invoice_v2。
大文件或高成本操作应保持异步。
对外响应体不应泄露 provider 特有的内部字段，除非这些字段被明确纳入公开契约。