API 参考
n8n 出站交付
当前推荐的 route-based n8n 交付模型，基于共享 n8n executor 与 webhook notify。
适用范围
本页描述的是当前推荐的 n8n 集成方式：把已复核的 Numora 文档，通过共享 n8n 执行器编排后写入下游系统。
示例中的首个 provider 仍然是 dynamics365。
当前推荐模型
Numora 现在只保留两条正式交付路径：
workflow：由 Numora 内建执行n8n executor + webhook notify：由共享n8nwebhook 做外部编排
如果你希望由 n8n 负责下游编排，请使用第二条路径。
不要再基于 delivery outbox polling 构建新集成。当前模型已经收敛为 route-based、webhook-driven。
配置边界
1. Admin Settings
在 Admin > Settings > Integrations 中统一配置共享 n8n 执行器：
- shared webhook enabled
- shared webhook URL
- shared webhook secret
2. Connection Settings
每个租户继续在 Numora 中维护自己的下游连接。
对当前 Dynamics 场景，connection 还承载租户级交付参数，例如：
- owner team name
- attachment target
3. Delivery Routes
每条 route 决定文档最终走哪条交付路径：
workflown8n executor
当 route 选择 n8n executor 时，trigger mode 固定为 webhook。
推荐流程
- 文档在 Numora 中完成提取、复核和 finalized。
- 操作员或外部客户端调用
POST /v1/documents/{id}/dispatch。 - Numora 解析该文档当前命中的 delivery route。
- 如果 route 使用
n8n executor，Numora 会先入队 webhook delivery，然后立即通知共享n8nwebhook。 n8n再从 Numora 回拉最新文档状态，并执行下游写入。- 如果真正的下游写入发生在 Numora 管理路径之外，再调用
POST /v1/documents/{id}/delivery记录最终结果。
运行时接口
Dispatch
使用：
POST /v1/documents/{id}/dispatch
请把 202 Accepted 理解为“已入队”，而不是“已完成”。
状态查询
使用：
GET /v1/documents/{id}
推荐状态解释：
reviewed：已确认、可交付push_pending：已入队或仍在执行中push_succeeded：最近一次交付已成功完成push_failed：最近一次交付失败
文档结果
当 n8n 需要最新结构化结果时，使用：
GET /v1/documents/{id}/result
交付状态回执
只有当真正的下游写入发生在 Numora 管理路径之外时，才调用：
POST /v1/documents/{id}/delivery
该回执以 execution_id 做幂等。
Dataverse Session
如果 n8n 需要短期 Dynamics 会话、但不希望自行保存每个租户的 client secret，可调用：
POST /v1/dynamics/session
可靠性模型
当前推荐的 n8n 路径保留以下可靠性机制：
- 入队后立即尝试 webhook notify
- 首次 notify 失败后由 cron 接管重试
- delivery callback 记录按
execution_id幂等 - 以文档状态作为最终完成面的 canonical surface
什么时候改用 workflow
以下情况更适合 workflow：
- 下游写入希望完全留在 Numora 内部
- 希望由 Numora-managed workflow nodes 负责集成逻辑
- 不需要
n8n这层外部编排