API 参考
幂等与外部标识
说明 Numora 对外 API 开发者预览版中，文档创建与 delivery callback 当前使用的幂等模型。
适用范围
本页说明 Numora 对外 API 开发者预览版当前采用的幂等模型。
关键区别是：
- 文档创建当前以
external_id为核心 - delivery callback 当前以
execution_id为核心 - 通用的 header 级幂等合同目前还不是首要公开模型
当前预览版模型
在当前预览版中，Numora 通过资源级标识来提供重试安全性。
文档创建
POST /v1/documents
当你的系统需要安全地创建或重试同一份业务文档时，应使用 external_id。
当前行为：
external_id的作用域是同一用户下的同一 schema- 对同一 schema 重复提交相同
external_id时，接口会返回已有 document，而不是再创建一个新的逻辑文档
实际含义：
- 对同一份上游业务文档，使用一个稳定不变的
external_id - 重试时不要重新生成新的
external_id
Delivery callback
POST /v1/documents/{id}/delivery
当外部 worker 需要安全地重试同一次 delivery callback 时，应使用 execution_id。
当前行为：
- callback 按
execution_id做幂等 - 相同
execution_id且 delivery 数据相同，可以安全重放 - 相同
execution_id但 delivery 数据不同，会返回409 conflict
那 Idempotency-Key 呢
有些 API 体系会使用统一的 Idempotency-Key 请求头，为所有修改型请求提供通用幂等语义。
这不是 Numora 当前 public API preview 的主要合同。
在当前预览版里，更应优先使用：
external_id处理文档创建去重execution_id处理 delivery callback 去重
不要假设只发送 Idempotency-Key，就能为所有 /v1 修改型接口自动提供重试安全性。
推荐用法
面向上游文档系统
当 ERP、邮件采集服务或文档队列向 Numora 提交文档时：
- 选择一个稳定的
external_id - 重试同一份业务文档时保持这个值不变
- 保存 Numora 返回的
document.id
示例：
{
"schema": "invoice_v2",
"file_url": "https://example.com/invoice-001.pdf",
"external_id": "ap-100024"
}面向外部交付 worker
当你的 worker 在 Numora 外部写入目标系统时：
- 为这次 delivery attempt 生成一个稳定的
execution_id - 如需重放同一次 callback，复用该值
- 如果交付结果语义不同，不要复用同一个
execution_id
推荐心智模型
document.id：Numora 分配的资源标识external_id：客户端分配的业务文档标识，用于创建去重execution_id：客户端分配的交付 attempt 标识，用于 callback 去重