使用指南
认证与首次 CRM 交付
面向首阶段 CRM 集成的推荐起步路径，说明如何用 Numora API key 把已复核文档接入下游交付流程。
适用范围
本页是面向 CRM 或业务系统对接团队的推荐起步路径。
它默认以下前提成立：
- 文档已经在 Numora 内完成处理
- 复核在 Numora 内完成
- 交付流程由
n8n等外部 worker 协调
1. 获取 API Key
对外 API 使用 bearer token 认证。
示例请求头：
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxx请使用工作区或环境分配给你的实际 API 基础地址。
2. 理解首次 CRM 交付主路径
对于首阶段 CRM 集成，主路径不是：
POST /v1/documents
推荐主路径是：
- 在 Numora 内完成文档复核
- 调用
POST /v1/documents/{id}/dispatch - 由 Numora 解析当前激活的 delivery route
- 观察
push_*交付状态
这也是把已复核文档接到下游 CRM 流程的最快路径。
3. 启动 Route-Based Delivery
使用：
POST /v1/documents/{id}/dispatch
示例：
curl -X POST "https://api.numora.example/v1/documents/doc_123/dispatch" \
-H "Authorization: Bearer $NUMORA_API_KEY" \
-H "Content-Type: application/json" \
-H "x-request-id: first-crm-delivery-001" \
-d '{
"provider": "dynamics365"
}'Numora 会根据当前命中的 delivery route，决定这份文档应走内部 workflow，还是通知共享 n8n executor。
4. 选择交付模式
推荐：Numora 管理 dispatch
- 调
POST /v1/documents/{id}/dispatch - 由 Numora 解析当前 route
- 轮询
GET /v1/documents/{id}，直到状态离开push_pending
兜底：外部执行后 callback
只有当目标系统写入由你的 worker 直接执行时才使用。
- 调
POST /v1/documents/{id}/dispatch - 让 Numora 通知共享
n8nexecutor - 如需最新结构化结果，再调
GET /v1/documents/{id}/result - 在外部写入目标系统
- 调
POST /v1/documents/{id}/delivery
5. 读取交付状态
对于 dispatch 模式，document 资源就是主要的状态读取口。
常见语义：
reviewed：已确认，可进入交付push_pending：交付已排队或正在执行push_succeeded：交付成功push_failed：最近一次交付失败
6. 什么时候 POST /v1/documents 是可选的
POST /v1/documents 仍然是合法的接入口。
但在“首次 CRM 交付”这条主叙事里，它是可选项，不是必经路径。
如果文档已经存在于 Numora 且已完成复核，你可以直接从 dispatch 与当前激活的 delivery route 开始。