Darkroom API 接入概览
用 OAuth 2.0 从外部业务系统创建和查询 Darkroom 订单——base URL、沙盒、认证与接入顺序。
Darkroom API v2 面向已获授权的品牌及其系统集成方，用于从外部业务系统创建和查询 Darkroom 订单。
环境与地址
| 生产 | 沙盒 | |
|---|---|---|
| base URL | https://api.darkroom.net/v2 |
https://sandbox-api.darkroom.net/v2 |
| 凭据前缀 | dr_live_ci_ / dr_live_cs_ |
dr_test_ci_ / dr_test_cs_ |
| 数据 | 真实业务数据 | 独立测试数据，可自助重置 |
| 外部投递 | 正常 | 不发送真实短信、微信或邮件 |
建议先在沙盒环境完成集成验证，再切换到生产环境。两个环境使用不同的 base URL 和凭据前缀；生产凭据不能用于沙盒环境，沙盒凭据也不能用于生产环境。
沙盒环境采用较低的资源上限（5 个门店、5 种服务类型、10 个服务项目和 50 笔订单），便于集成方在上线前验证资源上限和 HTTP 403 的处理逻辑。
认证一眼版
# ① 每小时一次：用长期凭据换 1 小时有效期的 token
curl -X POST https://sandbox-api.darkroom.net/v2/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=dr_test_ci_xxxxxxxx" \
-d "client_secret=dr_test_cs_xxxxxxxx"
# ② 每个业务请求：只带 Bearer token
curl -X POST https://sandbox-api.darkroom.net/v2/orders \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "order_code": "crm-20260727-K7Q2XM", ... }'Darkroom API v2 不使用请求签名、nonce 或签名时间窗口，也不签发 refresh_token。详见认证与访问令牌。
接入顺序
申请 API 权限
联系 Darkroom 支持，说明品牌、接入系统、需要读取还是创建订单，以及负责联调的技术联系人。
安全保存凭据
Darkroom 会签发 client_id 和仅显示一次的 client_secret。请将 client_secret 保存在服务端密钥管理系统或环境变量中，不得嵌入网页、移动端应用或代码仓库。
在沙盒实现认证
按认证与访问令牌实现访问令牌缓存和到期更新。
处理幂等、限流与错误
以 order_code 作为自然幂等键，并按幂等、重试与错误处理区分安全重试、编号冲突和两类不同的 429。
在沙盒验证完整链路
至少验证创建订单、幂等重放、订单编号冲突、订单查询、令牌更新、权限不足，以及分钟配额和秒级突发限制两类限流场景。
切换生产环境
完成沙盒验收后，将 base URL 和凭据切换为生产配置。业务请求结构无需调整。
API Reference
Darkroom API v2 Reference
换取令牌、创建订单与查询订单的完整 JSON schema、响应和错误定义。
契约变更日志
按 breaking / additive / fix 分级的契约变更记录，以及版本策略。
从 API v1 迁移
对照 v1 参数、认证、错误和响应字段，规划无中断迁移。
查看和保护 API 凭据
面向品牌管理员了解凭据保管、泄露处理与轮换流程（商家使用手册）。
仍在维护的 API v1
现有的 https://api.darkroom.net/v1 订单集成可以继续使用。Darkroom API v1 仅提供兼容性维护，不再新增端点或安全能力。新的集成项目应采用 v2。维护存量 v1 集成需要签名与错误码细节时，请联系我们索取。
格式约定
| 项目 | 值 |
|---|---|
| 请求 body | UTF-8 JSON（/oauth/token 除外，用 form-urlencoded） |
| 认证 | Authorization: Bearer <access_token> |
| 时间 | ISO 8601 |
| 限流 | 双层：20 req/min/key 配额 + 2 req/s/key 突发整形；/oauth/token 单独 10 req/min/client_id |
所有生产请求必须使用 HTTPS。日志和错误追踪中不得记录 client_secret、完整 access_token、顾客资料或完整请求正文。