OFFICIAL INSTALLATION

ERP 官方安装授权流程

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

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

用户确认授权不等于安装完成

ERP 只有在应用成功调用完成回执后，才会显示“已安装”。交接 GET 路由必须允许未登录用户进入，不能再转到 /authorize 要求第二次授权。

使用交接码交换 Token

换票只能从应用服务端发出。Client Secret 与 Token 不得进入浏览器；处理交接码后立即跳转到不带码的 URL，不写入 localStorage、日志或后续页面 URL。

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 与 Secret。成功响应为顶层 Token 对象，包含 access_token、refresh_token、expires_in、scope、application_id、installation_id、company_id 和 environment。

不要套用业务 API 的 data 解包器

直接读取 result.access_token，并校验应用、Installation、企业与环境。可选的 redirect_uri 必须等于这次登记的交接地址。

Refresh 使用同一端点与 JSON Client 凭据，提交 grant_type=refresh_token 和 refresh_token。同一连接串行刷新并安全保存新的 Token 对。

安装完成与失败回执

先持久化企业连接、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“打开/管理”跳到应用启动地址，携带 ds_launch_ticket 与 ds_environment。这不是安装码，不能调用 /oauth/token，也不应再次发起权限确认。

POST /v1/launch/tickets/exchangeHTTP Basic · 服务端

// 使用 ds_environment 对应的 Client ID / Secret 构造 HTTP Basic
{ "ticket": "收到的 ds_launch_ticket" }

// 成功结果位于 data；不是 Token 对象
{ "data": {
  "application_id": "app_example",
  "installation_id": "ins_example",
  "company_ref": "example-company",
  "actor_ref": "example-actor",
  "environment": "sandbox",
  "expires_at": "2026-09-03T12:00:00Z"
} }

启动票据默认 60 秒有效、一次性消费。按可信的应用、环境和企业解析既有工作区，建立 HttpOnly 会话并跳到无票据 URL。退出应用后从 ERP 打开应进入原企业，不新建账号权益；切换 ERP 企业后必须隔离工作区。

失败后安全重新安装

无响应

先定位第一次失败用健康检查检查网络、代理与协议；超时不证明平台未消费交接码。

已换票

继续本地初始化或回执若已安全保存 Token，用已有 Token 重试 /complete，不重新换票或重复创建工作区。

旧事务

新安装不等于刷新旧链接无法继续时，待默认 10 分钟期限结束，再从 ERP 市场进入新的官方确认页。

改配置

重新发起授权交接地址或权限变更会使旧未完成事务失效；只修改启动地址不影响安装。

不要删除防重放记录来“修复”安装

不要靠临时改 URL、清库或卸载已有成功安装强行重试。平台授权期限以服务端时间为准。

卸载与重新安装

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