交付状态回执

说明当下游写入发生在 Numora 外部时，外部执行器如何把交付结果回写到 Numora。

适用范围

本页说明当下游系统写入发生在 Numora 外部时，如何把交付结果回写到 Numora。

只在以下场景使用：

你的 worker 直接写目标系统
Numora 没有通过 dispatch 执行下游写入
你仍希望 Numora 保留交付审计记录

如果目标系统写入由 Numora 内部执行，请走 dispatch，不要走 callback 模式。

回执接口

POST /v1/documents/{id}/delivery

该接口为单个 document 记录一次 delivery attempt。

支持的状态值

succeeded
failed
skipped

必填字段

始终必填：

provider
status
execution_id
attempted_at

当 status=succeeded 时必填：

external_record_id

可选字段：

external_url
error_code
error_message

典型的 status=skipped 场景：

supplier 或 team 等 lookup 前置条件未命中
worker 有意结束执行，但不创建任何 CRM 记录
你仍希望 Numora 记录一次“已完成”的 delivery attempt，并停止自动 outbox 重试

成功示例

curl -X POST "https://api.numora.example/v1/documents/4be38121-3791-4856-80d5-c57dbec2cf78/delivery" \
  -H "Authorization: Bearer $NUMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-request-id: delivery-callback-success-001" \
  -d '{
    "provider": "dynamics365",
    "status": "succeeded",
    "external_record_id": "crm-row-001",
    "execution_id": "n8n-4be38121-3791-4856-80d5-c57dbec2cf78",
    "attempted_at": "2026-03-24T03:00:00.000Z"
  }'

失败示例

curl -X POST "https://api.numora.example/v1/documents/4be38121-3791-4856-80d5-c57dbec2cf78/delivery" \
  -H "Authorization: Bearer $NUMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-request-id: delivery-callback-failed-001" \
  -d '{
    "provider": "dynamics365",
    "status": "failed",
    "execution_id": "n8n-4be38121-3791-4856-80d5-c57dbec2cf78",
    "error_code": "crm_429",
    "error_message": "Dataverse rate limited",
    "attempted_at": "2026-03-24T03:00:00.000Z"
  }'

Skipped 示例

当外部执行器有意不创建 CRM 记录时使用 skipped，例如 supplier lookup 没有命中任何记录。

curl -X POST "https://api.numora.example/v1/documents/4be38121-3791-4856-80d5-c57dbec2cf78/delivery" \
  -H "Authorization: Bearer $NUMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-request-id: delivery-callback-skipped-001" \
  -d '{
    "provider": "dynamics365",
    "status": "skipped",
    "execution_id": "n8n-4be38121-3791-4856-80d5-c57dbec2cf78",
    "error_code": "supplier_not_found",
    "error_message": "No supplier matched vendor_name \"Acme Supplies Ltd\".",
    "attempted_at": "2026-03-24T03:00:00.000Z"
  }'

幂等规则

该 callback 会按 execution_id 做幂等。

相同 execution_id 且 delivery 数据相同，可以安全重放
相同 execution_id 但 delivery 数据不同，会返回 409 conflict

这让外部 worker 在不确定 Numora 是否收到第一次回执时，可以安全重试。

审计读取口

用下面的接口读取已记录的 attempts：

GET /v1/documents/{id}/delivery?provider=dynamics365&limit=20

对于 callback 模式集成，这就是主要的审计读取口。

对文档状态的影响

该 callback 会影响 document 资源上的下游交付可见状态。

通常可以这样理解：

push_pending：下游写入仍在执行中，或尚未确认完成
push_succeeded：已有成功或有意跳过的 delivery attempt
push_failed：最近一次 delivery attempt 失败

具体状态语义见文档生命周期。

什么时候不要用这个接口

在推荐的 Numora 管理 dispatch 模式下，不要再调用 POST /v1/documents/{id}/delivery。

那种模式下应：

轮询 outbox
调 dispatch
由 Numora 执行写入并更新 document 状态