认证与首次 CRM 交付

适用范围

本页是面向 CRM 或业务系统对接团队的推荐起步路径。

它默认以下前提成立：

• 文档已经在 Numora 内完成处理
• 复核在 Numora 内完成
• 交付流程由 n8n 等外部 worker 协调

如果你需要先做文件接入，请继续阅读 认证 和 文档资源。

1. 获取 API Key

对外 API 使用 bearer token 认证。

示例请求头：

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxx

请使用工作区或环境分配给你的实际 API 基础地址。

2. 理解首次 CRM 交付主路径

对于首阶段 CRM 集成，主路径不是：

POST /v1/documents

推荐主路径是：

1. 在 Numora 内完成文档复核
2. 轮询 GET /v1/delivery/outbox
3. 调 dispatch，或由外部执行写入
4. 观察 push_* 交付状态

这也是把已复核文档接到下游 CRM 流程的最快路径。

3. 轮询已复核文档

使用：

GET /v1/delivery/outbox?provider=dynamics365&limit=100

示例：

curl "https://api.numora.example/v1/delivery/outbox?provider=dynamics365&limit=100" \
  -H "Authorization: Bearer $NUMORA_API_KEY" \
  -H "x-request-id: first-crm-delivery-001"

该 outbox 会返回已经 reviewed 且 finalized、可进入下游交付流程的文档。

4. 选择交付模式

推荐：Numora 管理 dispatch

1. 轮询 outbox
2. 调 POST /v1/documents/{id}/dispatch
3. 轮询 GET /v1/documents/{id}，直到状态离开 push_pending

兜底：外部执行后 callback

只有当目标系统写入由你的 worker 直接执行时才使用。

1. 轮询 outbox
2. 调 GET /v1/documents/{id}/result
3. 在外部写入目标系统
4. 调 POST /v1/documents/{id}/delivery

5. 读取交付状态

对于 dispatch 模式，document 资源就是主要的状态读取口。

常见语义：

• reviewed：已确认，可进入交付
• push_pending：交付已排队或正在执行
• push_succeeded：交付成功
• push_failed：最近一次交付失败

6. 什么时候 POST /v1/documents 是可选的

POST /v1/documents 仍然是合法的接入口。

但在“首次 CRM 交付”这条主叙事里，它是可选项，不是必经路径。

如果文档已经存在于 Numora 并且已经完成复核，你可以直接从 delivery outbox 开始。

7. 推荐阅读顺序

1. 认证
2. 轮询已复核文档
3. n8n 出站交付
4. 交付状态回执
5. 文档生命周期
6. 错误与限制

相关页面

• 认证
• 幂等与外部标识
• 轮询已复核文档
• n8n 出站交付
• 交付状态回执
• 文档资源
• 复核与确认