DSFulfill Open Platform v1

从 Sandbox 到 Production 的完整接入

开发者只需要接入 https://open.dsfulfill.io/v1。DSFulfill 会统一处理企业上下文、授权权限、请求日志和上游服务转发；应用不得直接依赖或暴露内部 API。

创建与联调

创建应用、配置交接地址与回调地址，在 Sandbox 完成第一条请求。

开始接入 →02

安装授权

了解 ERP 官方授权、一次性交接码、Token 交换与安装完成回执。

查看流程 →03

Production 发布

冻结版本、提交审核并发布；Sandbox 会继续保留用于后续开发。

准备上线 →

快速开始

在开发者中心完成以下配置。Client Secret 只在创建或轮换时完整显示一次，必须存放在服务端密钥系统中。

1创建应用填写应用资料、Logo、封面与支持地址。
2声明最小权限只选择实际需要的 Scope；写权限会在上线审核时重点检查。
3配置授权完成交接地址例如 https://app.example.com/oauth/dsfulfill/install，平台会把一次性 installation_code 发送到这里。
4配置 OAuth 回调地址必须完全匹配协议、域名、端口和路径。
5绑定 ERP 测试企业Sandbox 应用只对绑定企业可见；企业管理员仍需在 ERP 中确认安装权限。

Sandbox 与 Production

两个环境属于同一个应用，但使用独立凭证、Installation、Token 和安装状态。Production 发布不会关闭 Sandbox。

SANDBOX

ds_test_…仅绑定测试企业可见；回调地址可使用 HTTPS，也允许 localhost HTTP。

PRODUCTION

ds_live_…发布后按应用可见性展示；交接地址和回调地址必须使用 HTTPS。

ISOLATION

环境严格隔离不要混用 Client ID、Client Secret、Access Token、Refresh Token 或 Installation ID。

ERP 官方安装授权流程

权限确认必须由 DSFulfill ERP 官方页面完整展示。第三方应用不得自行展示、删减或隐藏权限，也不得让浏览器提交 Scope。

1企业管理员在 ERP 应用市场点击安装。
2ERP 从开放平台读取经过校验的权限清单，并由管理员确认。
3开放平台创建状态为 connecting 的 Installation，生成 10 分钟有效、仅可使用一次的 installation_code。
4浏览器跳转到应用登记的交接地址，并附带 installation_code、authorization_ref 与用于选择 Client 凭证的 environment。最终环境必须以换票响应为准。
5应用服务端交换 Token、完成本地绑定，然后向开放平台回执完成或失败。

重要

用户确认授权不等于安装完成。ERP 只有在应用成功调用完成回执后，才会显示“已安装”。

使用交接码交换 Token

此请求只能从应用服务端发出。不要把 Client Secret、交接码或 Refresh Token 发送给浏览器。

POST /oauth/tokenapplication/json

curl --request POST \
  --url https://open.dsfulfill.io/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "authorization_code",
    "client_id": "ds_test_xxx",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "ds_code_xxx"
  }'

应用必须使用交接地址中 environment 对应的 Client ID 与 Client Secret。开放平台会强制校验凭证环境和 Installation 环境一致。成功响应包含 access_token、refresh_token、expires_in、scope、installation_id、company_id 和 environment；最终必须以换票响应为准。

安装完成与失败回执

应用必须先持久化企业连接、Token 和自身所需配置，再发送完成回执。回执使用刚取得、且绑定该 Installation 的 Access Token。

安装完成Bearer Access Token

curl --request POST \
  --url https://open.dsfulfill.io/v1/installations/ins_xxx/complete \
  --header 'Authorization: Bearer ds_test_xxx' \
  --header 'Accept: application/json'

安装失败Bearer Access Token

curl --request POST \
  --url https://open.dsfulfill.io/v1/installations/ins_xxx/fail \
  --header 'Authorization: Bearer ds_test_xxx' \
  --header 'Content-Type: application/json' \
  --data '{"reason":"APPLICATION_BINDING_FAILED"}'

not_installed未安装

ERP 可以发起安装

connecting连接中

用户已授权，应用正在完成本地初始化

active已安装

应用已回执成功，可以调用业务 API

failed安装失败

允许重新安装，不得显示为已安装

revoked已卸载

Token 与 Webhook 已撤销，可以重新安装

补偿与重试

/complete 未确认返回 active 时，不得向用户显示安装成功。保留可重试状态；本地绑定失败时尽力调用 /fail。

卸载与重新安装

卸载由 ERP 中具有应用管理权限的企业管理员发起。开放平台会把状态改为 revoked，撤销该 Installation 的 Access Token、Refresh Token，并禁用 Webhook。应用应把重复卸载视为幂等操作，并允许用户之后重新安装。

调用公开 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'

权限与安全

SECRET

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

SCOPE

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

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

REQUEST ID

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

提交 Production 审核

完成应用资料、媒体、HTTPS OAuth 回调、权限说明与 Sandbox 企业联调后，在应用的“Production 发布”页面创建不可变版本并提交审核。审核通过后发布并保存只显示一次的 Production Client Secret。

Sandbox 会继续可用

上线、提交审核或发布 Production 都不会关闭 Sandbox。后续新功能应先在 Sandbox 调试，再提交新的 Production 版本。

错误处理

客户端应依据 HTTP Status 与稳定错误 code 处理，不要解析本地化文案。遇到 429 时遵循 Retry-After；网络错误与 5xx 使用带抖动的指数退避；不要自动重试无幂等保护的写请求。

机器可读契约

仓库中的 docs/API-PROTOCOL.md 是行为规范，docs/openapi/v1.yaml 是 OpenAPI 3.1 契约。两者与本指南应保持一致。