使用指南
认证
如何在 Numora 对外 API 开发者预览版中完成认证并发送第一个文档请求。
范围
本页说明如何在 Numora 对外 API 开发者预览版中完成认证，并针对文档资源发起第一个请求。
认证方式
对外 API 使用 API key 与 Authorization 请求头。
API 基础地址
请使用你的工作区或环境实际分配的 API 基础地址。
本页示例中的 https://api.numora.example 仅为占位地址。
示例请求头：
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxx必要请求头
JSON 请求建议携带：
Authorization: Bearer <api_key>
Content-Type: application/json如果可以，建议同时发送 x-request-id 便于排障关联。
首个请求
创建文档：
curl -X POST "https://api.numora.example/v1/documents" \
-H "Authorization: Bearer $NUMORA_API_KEY" \
-H "Content-Type: application/json" \
-H "x-request-id: create-document-001" \
-d '{
"schema": "invoice_v2",
"file_url": "https://example.com/invoice-001.pdf",
"external_id": "ap-100024",
"metadata": {
"source": "email-import"
}
}'响应示例：
{
"id": "doc_01jpwq4q9m7q4q2k8dax1x1q5n",
"status": "processing",
"schema": "invoice_v2",
"status_url": "/v1/documents/doc_01jpwq4q9m7q4q2k8dax1x1q5n",
"result_url": "/v1/documents/doc_01jpwq4q9m7q4q2k8dax1x1q5n/result"
}轮询状态
文档创建完成后，持续查询状态，直到资源离开 processing。
curl "https://api.numora.example/v1/documents/doc_01jpwq4q9m7q4q2k8dax1x1q5n" \
-H "Authorization: Bearer $NUMORA_API_KEY"当文档可用后，再读取结果：
curl "https://api.numora.example/v1/documents/doc_01jpwq4q9m7q4q2k8dax1x1q5n/result" \
-H "Authorization: Bearer $NUMORA_API_KEY"推荐集成流程
- 创建文档。
- 保存返回的
id。 - 通过轮询或 webhook 监听状态变化。
- 获取最终结果。
- 按需执行 approve、reject 或 retry-push 等动作。
对于当前预览版中的幂等语义，文档创建更应依赖 external_id 做对账与去重，而不是假设所有路由都支持统一的 Idempotency-Key 合同。