PUBLIC API

调用公开 API

业务请求始终使用 Access Token。企业上下文由 Installation 自动解析，客户端不得传入或覆盖 company_id。

GET /v1/productscURL

curl --request GET \
  --url https://open.dsfulfill.io/v1/products \
  --header 'Authorization: Bearer ds_test_xxx' \
  --header 'Accept: application/json'

把应用能力嵌入 ERP

订单报价中的图片搜索等能力由 ERP 后端调用开放平台，再由平台验证当前企业是否已安装应用、Scope 和能力场景。浏览器不会获得应用 Token，也不会直接请求第三方服务。

能力提供方收到的请求JSON

{
  "invocation_id": "inv_xxx",
  "ticket": "ds_cap_xxx"
}

服务端使用当前环境 Client Credential 兑换票据，以响应中的企业、Installation、能力、场景和输入作为可信上下文。套餐与额度由应用判断，并以 invocation_id 做幂等计费；重复请求不得重复扣费。

阅读 ERP 内嵌能力完整接入指南 →

订阅商品变更

安装完成后使用该企业的 Access Token 创建订阅。平台目前提供 product.created、product.updated、product.deleted 和 product.restored。事件只通知变化，应用收到后按商品 ID 拉取最新详情，并按版本号防止乱序覆盖。

POST /v1/webhooksJSON

{
  "url": "https://app.example.com/webhooks/dsfulfill",
  "events": ["product.created", "product.updated"]
}

创建响应中的签名 Secret 只显示一次。接收端用原始 Body 校验 X-DSFulfill-Signature，按 event_id 幂等，并按企业、商品保存单调递增的 sequence 防止乱序；非 2xx 响应会自动重试。

权限与安全

SECRET

仅保存在服务端禁止写入浏览器、移动端、客户端日志或代码仓库；泄露后立即轮换。

SCOPE

最小权限原则Token 只能访问安装时确认的 Scope；新增权限需要重新审核与授权。

白名单可选固定出口服务器建议配置；Serverless 或多区域应用可以不配置。

REQUEST ID

保留排障标识记录响应的 X-Request-Id，但不要记录完整 Token 或未经清洗的敏感 Body。

机器可读契约

仓库中的 docs/ERP-APP-INTEGRATION.md 提供完整接入步骤；docs/API-PROTOCOL.md 是行为规范，docs/openapi/v1.yaml 是 OpenAPI 3.1 契约。文档以对应部署版本为准。