申请客户端凭证
确认 Supplier 组织、回调联系人和所需 Scope。每个 Supplier 使用独立凭证，严禁跨组织共享。
Dental Atlas · Public API
Supplier OpenAPI
第三方接入文档
面向 Supplier ERP、MES 和自动化系统的订单履约接口。通过短期 OAuth Token 安全读取本厂商订单、更新生产状态、提交物流信息并管理装箱照片。
OpenAPI 3.1
OAuth 2.0
15 分钟 Token
租户严格隔离
幂等写入
请求限流
请将地址替换为 Dental Atlas 提供给贵司的实际环境地址。页面不会发起任何网络请求。
四步完成接入
Client ID 与 Client Secret 由 Dental Atlas 管理员分配。Secret 只展示一次，请使用企业密钥管理系统保存。
获取 Access Token
使用 HTTP Basic 调用 POST /oauth/token。Token 有效期 900 秒，不提供 Refresh Token。
携带 Bearer Token
调用 V1 接口时发送 Authorization: Bearer <token>。组织和 Supplier 身份由 Token 决定，无需也不允许自行传入。
安全处理写请求
每次写操作生成新的 Idempotency-Key。超时后可使用同一 Key 和相同请求体安全重试。
不要在浏览器、移动端或前端 JavaScript 中保存 Client Secret。
Client Credentials 仅适用于服务器到服务器通信。日志中也不应记录 Secret、Authorization、患者数据或预签名 URL。
通用约定
所有 V1 成功响应均包含 request_id，故障排查时请向 Dental Atlas 支持人员提供该值。
请求与响应
- 除 Token 接口外，请求和响应使用
application/json。 - 日期时间必须使用带时区的 ISO 8601，例如
2026-07-28T10:30:00+08:00。 - 未在文档声明的请求字段会被拒绝。
- 越权订单或附件统一返回 404，不透露资源是否存在。
幂等与并发
- 所有 POST 写接口及 DELETE 接口必须携带
Idempotency-Key。 - Key 长度 8–200，仅允许字母、数字、点、下划线、冒号和短横线。
- 记录保留 24 小时；相同 Key 搭配不同请求体返回 409。
- 批量操作最多 100 单，任一订单失败时整批回滚。
授权范围（Scopes）
| Scope | 用途 | 典型接口 |
|---|---|---|
orders:read | 读取当前 Supplier 的订单列表和详情 | GET /v1/orders |
orders:write | 接单、完成制作和批量状态变更 | actions/accept、complete-fabrication |
shipments:write | 填写 Supplier → Lab 物流信息 | shipments/supplier-to-lab |
files:read | 读取 Vendor 可见附件及下载 URL | GET .../files |
files:write | 上传或删除 SHIPMENT 图片 | upload-url、complete、DELETE |
限流策略
| 类别 | 限制 | 说明 |
|---|---|---|
| Token | 每 IP 10 次/分钟；每 Client 30 次/分钟 | 同时受两层规则约束 |
| 查询 | 300 次/分钟；10 秒突发 60 次 | 按 Client ID 统计，并有 IP 防滥用保护 |
| 普通写入 | 60 次/分钟 | 建议配合幂等重试 |
| 文件预签名 | 30 次/分钟 | 不包含对象存储的数据传输 |
| 批量操作 | 10 次/分钟 | 每批最多 100 单 |
响应头包括 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset；返回 429 时还会包含 Retry-After。
公开接口
共 15 个接口。点击接口卡片查看参数、业务前置条件、cURL 请求和完整响应样例。
没有找到匹配的接口，请尝试其他关键词。
附件上传流程
文件不会经过 OpenAPI 服务中转。第三方先获取隔离区预签名 URL，直接 PUT 到对象存储，再调用确认接口完成魔数和归属校验。
申请上传 URL
调用 POST .../files/upload-url，声明文件名、Content-Type、大小及可选 SHA-256。URL 有效期 10 分钟。
上传对象
使用返回的 upload_url 执行 HTTP PUT，Content-Type 必须与申请时一致。此请求不携带 OpenAPI Bearer Token。
确认并登记
调用 POST .../{uploadId}/complete。服务校验对象大小、扩展名、MIME、文件魔数和 SHA-256 后登记为 SHIPMENT 文件。
文件限制
支持 JPEG、PNG、WEBP、HEIC、HEIF；单文件最大 10 MB；每个订单最多 10 张 SHIPMENT 图片；仅在 IN_PRODUCTION 或 FABRICATION_COMPLETED 阶段允许上传或删除。
curl -X PUT "$UPLOAD_URL" \
-H 'Content-Type: image/jpeg' \
--upload-file './packing-front.jpg'错误与重试
错误统一采用 application/problem+json。请根据 HTTP 状态和稳定的 code 编写程序逻辑，不要匹配可能调整的 detail 文案。
| HTTP | 常见 code | 处理建议 |
|---|---|---|
| 400 | validation_failed | 修正字段，查看 errors 数组 |
| 401 | invalid_client / invalid_token | 检查凭证或重新获取 Token |
| 403 | insufficient_scope | 申请所需 Scope |
| 404 | resource_not_found | 核对资源 ID；同样可能表示资源不属于当前 Supplier |
| 409 | invalid_order_state / idempotency_conflict | 刷新订单状态或更换幂等 Key |
| 428 | idempotency_key_required | 为写请求添加 Idempotency-Key |
| 429 | rate_limit_exceeded | 等待 Retry-After 后加随机抖动重试 |
| 503 | engine_unavailable / rate_limit_unavailable | 指数退避；写请求必须沿用原 Key 和请求体 |
{
"type": "https://api.dentalatlas.ai/problems/invalid_order_state",
"title": "Conflict",
"status": 409,
"code": "invalid_order_state",
"detail": "Order must be IN_PRODUCTION for completeFabrication",
"instance": "/v1/orders/12451/actions/complete-fabrication",
"request_id": "019fa42d-b20b-7da3-9a25-4792b07b5c82"
}生产安全建议
凭证管理
使用 Secret Manager 或 HSM 保存 Client Secret，至少每 90 天轮换。不要提交到 Git、配置镜像或工单。
网络与日志
仅通过 TLS 调用。日志应保留 request_id、路径和状态码，但必须脱敏 Authorization、患者信息及预签名 URL。
可靠重试
只对 429、502、503、504 使用指数退避。写请求重试必须保持同一 Idempotency-Key 和完全相同的请求体。