申请客户端凭证
确认 Supplier 组织、回调联系人和所需 Scope。每个 Supplier 使用独立凭证，严禁跨组织共享。
Dental Atlas · Public API
Supplier OpenAPI
第三方接入文档
面向 Supplier ERP、MES 和自动化系统的订单履约接口。通过短期 OAuth Token 安全读取本厂商订单、更新生产状态、提交物流信息、管理通用附件、参与 Discussion，并以显式 ACK 方式轮询业务通知。
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 | 上传或删除 GENERAL 图片、ZIP、STL | upload-url、complete、DELETE |
discussions:read | 轮询 Discussion 并下载附件 | discussions/messages |
discussions:write | 发送消息并管理 Discussion 附件 | discussion/messages、attachments |
notifications:read | 轮询并 ACK Supplier 通知 | notifications、notifications/ack |
限流策略
| 类别 | 限制 | 说明 |
|---|---|---|
| Token | 每 IP 10 次/分钟；每 Client 30 次/分钟 | 同时受两层规则约束 |
| 查询 | 300 次/分钟；10 秒突发 60 次 | 按 Client ID 统计，并有 IP 防滥用保护 |
| Discussion / 通知轮询 | 120 次/分钟；10 秒突发 30 次 | 建议遵循响应中的 poll_after_seconds |
| 普通写入 | 60 次/分钟 | 建议配合幂等重试 |
| 文件预签名 | 30 次/分钟 | 不包含对象存储的数据传输 |
| 批量操作 | 10 次/分钟 | 每批最多 100 单 |
响应头包括 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset；返回 429 时还会包含 Retry-After。
公开接口
共 23 个接口。点击接口卡片查看参数、业务前置条件、cURL 请求和完整响应样例。
没有找到匹配的接口，请尝试其他关键词。
附件上传流程
文件不会经过 OpenAPI 服务中转。第三方先获取隔离区预签名 URL，直接 PUT 到对象存储，再调用确认接口完成魔数和归属校验。
申请上传 URL
调用 POST .../files/upload-url，声明文件名、Content-Type、准确大小及必填 SHA-256。图片 URL 有效期 15 分钟，ZIP/STL 为 60 分钟。
上传对象
使用返回的 upload_url 执行 HTTP PUT，Content-Type 必须与申请时一致。此请求不携带 OpenAPI Bearer Token。
确认并登记
调用 POST .../{uploadId}/complete。服务流式校验大小、扩展名、MIME、格式结构和 SHA-256 后登记为 GENERAL 文件。
文件限制
支持 JPEG、PNG、WEBP、HEIC、HEIF（单文件最大 30 MiB）以及 ZIP、STL（单文件最大 200 MiB）；每个订单最多 10 个 GENERAL 文件；仅在 IN_PRODUCTION 或 FABRICATION_COMPLETED 阶段允许上传或删除。ZIP 不会在服务端解压，并拒绝加密、多磁盘、损坏或含路径穿越条目的压缩包。
curl -X PUT "$UPLOAD_URL" \
-H 'Content-Type: image/jpeg' \
--upload-file './packing-front.jpg'Discussion 使用说明
Discussion 消息按订单和最多 31 天的时间窗口查询，结果按创建时间升序返回。发送消息时可携带文本、回复目标以及最多 10 个已完成上传的附件。
可写边界
订单仍属于当前 Supplier 且 Thread 未归档时可发送消息；HOLD、QC 阶段仍可沟通。CANCELED、订单重新分配或 Thread 归档后禁止写入。
附件安全
Discussion 附件不计入订单 GENERAL 文件的 10 个配额。未绑定消息的附件可删除；消息发出后只能通过受鉴权的 5 分钟下载 URL 访问。
通知轮询与 ACK
每个 API Client 拥有独立消费位置。GET 只读取，不自动确认；第三方应先持久化事件，再使用返回的 next_cursor 调用 ACK。
| 类型 | 触发条件 | Payload |
|---|---|---|
case-modify | 非 Supplier 修改产品/服务、Supplier 截止日期、模型来源、交付方式或新增 Supplier 可见文件 | changes[].field / previous / current |
case-note | 非 Supplier 修改 CLINIC、LAB、TECHNICIAN 或 COMMENTS Note | note_type / previous / current |
case-response | sales、owner、admin 或 qc 向 Supplier Discussion 发送消息 | message_id / content / sender_role / attachments |
至少一次投递：在 ACK 前进程崩溃时，相同事件会再次返回。若落后超过 180 天，接口返回
410 notification_gap；请先执行订单全量同步，再 ACK 响应中的恢复 Cursor。错误与重试
错误统一采用 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://supplier-api.videatlas.com/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 和完全相同的请求体。