API 参考

API 约定

对外 API 的通用约定，覆盖鉴权、幂等、webhook、错误模型、分页与异步处理。

范围

本页定义 Numora 对外 API 开发者预览版统一使用的约定。

基础路径与版本

对外路由统一放在 /v1 下
内部应用路由继续独立存在
schema 版本显式出现在资源字段中，例如 invoice_v2

鉴权

对外 API 使用 API key，而不是浏览器 session cookie。

鉴权模型：

Authorization: Bearer <api_key>
创建时仅展示一次明文
服务端只存 hash
支持 scope
支持轮换与吊销

幂等

当前预览版主要通过资源级标识来表达幂等语义。

当前建议：

文档创建优先使用 external_id
delivery callback 优先使用 execution_id

不要假设当前所有 /v1 修改型接口都已经把通用 Idempotency-Key 请求头作为主要重试合同。

Webhook

Webhook 是一等公民，而不是补充能力。

事件类型：

document.processing
document.review_required
document.reviewed
push.succeeded
push.failed
run.failed

投递模型：

基于时间戳的 HMAC 签名
使用原始请求体做验签
退避重试
每个 endpoint 都可查看投递日志

错误模型

错误响应统一使用以下结构：

{
  "error": {
    "code": "invalid_schema",
    "message": "schema must be one of invoice_v2, receipt_v1, contract_v1",
    "request_id": "req_01jpwqkshg6x8j9k9j29m8n0n4"
  }
}

错误分类：

unauthorized
forbidden
invalid_payload
invalid_schema
not_found
conflict
rate_limited
internal_error

分页

长期对外开放的列表接口使用 cursor 分页。

响应示例：

{
  "data": [],
  "next_cursor": "cur_01jpwqv8k0fbbbx7k2y7w1v7r7"
}

运行时响应头

常用响应头包括：

x-request-id
retry-after，用于 429
x-rate-limit-limit
x-rate-limit-remaining
x-rate-limit-reset

默认异步

只要一个操作可能持续多秒、需要后台队列处理，或依赖第三方系统调用，API 就返回 202 Accepted 与可查询资源，而不是长时间同步阻塞请求。

相关页面

Webhooks

Numora 对外 API 开发者预览版中的 webhook 事件、签名、重试与投递处理方式。

错误与限制

Numora 对外 API 开发者预览版的 HTTP 状态码、错误响应模型、接入限制与重试建议。

On this page

基础路径与版本

运行时响应头