道来开发者

开发文档

一套规范覆盖四大系统:先看快速开始跑通第一次调用,再按系统查接口清单。文档与接口同步更新,变更记录在「更新记录」里。

入门
系统接口
参考

快速开始

适用:全部系统最近更新:—

本页接口清单为规划草稿,正式接口以开发者控制台发布的版本为准。

完成下面四步,就能在沙箱里拿到第一条真实返回。整个过程不需要联系任何人。

  1. 在 注册页 创建开发者账号,并完成企业或个人认证。
  2. 进入开发者控制台,新建一个应用,记录系统分配的 client_id 与 client_secret。
  3. 为该应用申请沙箱租户,沙箱内已预置示例主数据与单据。
  4. 用应用凭证换取访问令牌,带着令牌调用任一只读接口。

第一次调用

以下示例以读取工单列表为例,接口域名与路径为示例写法。

curl -X GET "https://api.droplet.example.com/v1/mes/work-orders?page=1&size=20" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"

返回结构

所有接口统一返回 code、message、data 三个字段;列表类接口的 data 内含 items 与 total。

{
  "code": 0,
  "message": "ok",
  "data": { "items": [], "total": 0, "page": 1, "size": 20 }
}

下一步

  • 阅读 认证与鉴权,了解令牌有效期与刷新方式。
  • 按系统查看接口清单,从目录左侧选择对应系统。
  • 卡住时到 开发者社区 发帖,或在 在线课程 里看实操演示。

认证与鉴权

适用:全部系统最近更新:—

开放接口采用基于应用凭证的令牌鉴权:应用先用凭证换取访问令牌,再在每次请求的请求头里携带令牌。令牌与租户绑定,一个应用可以被多个客户租户授权。

获取访问令牌

POST /v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

携带令牌

在请求头加入 Authorization: Bearer <access_token>。令牌过期后用同样的方式重新获取即可,不提供单独的刷新令牌。

项目说明
令牌有效期—
令牌类型Bearer
租户标识多租户授权时,在请求头 X-Tenant-Id 中指定目标租户
凭证轮换控制台可生成新的 client_secret,旧凭证保留一段过渡期

权限范围

每个应用在创建时声明需要的权限范围,客户在授权时逐项确认。请求超出范围的接口会返回 403。

  • mes:read / mes:write — AI X 水产MES平台
  • lead:read / lead:write — 涟漪AI获客系统
  • sourcing:read / sourcing:write — 清湍AI采购招标平台
  • hire:read / hire:write — 镜鉴AI面试系统

AI X 水产MES平台

权限:mes:read / mes:write最近更新:—

覆盖水产加工现场的生产执行数据:工单、报工、批次与追溯、设备状态。适合把产线数据同步到企业已有的 ERP、仓储或看板系统。

资源清单

资源方法与路径说明
工单GET /v1/mes/work-orders按状态、产线、时间范围查询工单
工单POST /v1/mes/work-orders从外部系统下达工单
报工POST /v1/mes/reports写入工序完工数量与人员
批次追溯GET /v1/mes/batches/{id}/trace按批次号取得原料来源与加工路径
设备GET /v1/mes/devices设备台账与当前运行状态

事件回调

在控制台登记回调地址后,以下事件发生时平台会向该地址推送消息:

  • work_order.completed — 工单完工
  • batch.quality_hold — 批次被品控拦截
  • device.alarm — 设备报警

示例代码与数据字典见 AI X 水产MES平台 课程。

涟漪AI获客系统

权限:lead:read / lead:write最近更新:—

线索、触达记录与转化状态的读写接口,常见用法是把外部渠道的表单或广告线索导入,再把成交结果回传给渠道。

资源清单

资源方法与路径说明
线索POST /v1/leads导入单条或批量线索,自动去重
线索GET /v1/leads/{id}读取线索详情与 AI 评分
触达记录GET /v1/leads/{id}/touches该线索的全部触达历史
阶段PATCH /v1/leads/{id}/stage更新线索所处阶段
渠道GET /v1/channels已接入渠道及其编码

事件回调

  • lead.scored — AI 评分完成
  • lead.converted — 线索转化为客户

清湍AI采购招标平台

权限:sourcing:read / sourcing:write最近更新:—

供应商、寻源项目与标书数据的接口,用于和企业的供应商主数据、合同与付款系统对接。涉及投标文件的接口只在项目开标后开放读取。

资源清单

资源方法与路径说明
供应商GET /v1/sourcing/suppliers供应商名录、资质与评级
供应商POST /v1/sourcing/suppliers从外部主数据同步供应商
寻源项目GET /v1/sourcing/projects项目列表与当前阶段
标书GET /v1/sourcing/projects/{id}/bids开标后读取投标汇总
评标结果GET /v1/sourcing/projects/{id}/award定标结果与评分明细

事件回调

  • project.opened — 项目开标
  • project.awarded — 项目定标

镜鉴AI面试系统

权限:hire:read / hire:write最近更新:—

职位、候选人与面试评估的接口,用于和招聘网站、人力资源系统打通。候选人个人信息按最小必要原则返回,敏感字段需要单独授权。

资源清单

资源方法与路径说明
职位GET /v1/hire/jobs在招职位及其面试流程配置
候选人POST /v1/hire/candidates从外部渠道导入候选人
面试POST /v1/hire/interviews为候选人创建 AI 面试并取得邀请链接
评估报告GET /v1/hire/interviews/{id}/report面试完成后的结构化评估
状态PATCH /v1/hire/candidates/{id}/status回写录用或淘汰结果

事件回调

  • interview.completed — 候选人完成面试
  • report.ready — 评估报告生成

错误码与限流

适用:全部系统最近更新:—

接口层面的错误通过 HTTP 状态码表达,业务层面的错误通过返回体里的 code 与 message 表达。

状态码含义建议处理
400参数缺失或格式错误对照文档检查必填项与类型
401令牌缺失、无效或已过期重新获取令牌后重试
403超出已授权的权限范围在控制台补充申请权限,并由客户重新授权
404资源不存在或不属于当前租户检查标识与租户头
429触发限流按返回头中的等待时间退避后重试
500平台内部错误携带返回头中的请求标识到社区或工单反馈

限流规则

  • 限流按应用与租户的组合计算,读接口与写接口分别计数。
  • 默认阈值:— 次 / 分钟 ;需要更高配额可在控制台申请。
  • 触发限流时返回 429,并在 Retry-After 头中给出建议等待秒数。

更新记录

接口版本:v1弃用策略:旧版本在新版本发布后保留至少一段过渡期

所有对外接口的新增、变更与弃用都会记录在这里,破坏性变更会提前在 开发者社区 公告。

常见问题

接入时最常被问到的几件事

沙箱是独立的测试租户,预置了示例主数据与若干业务单据,与任何客户的生产数据完全隔离。沙箱可以随时重置,接口行为与生产一致。

文档里找不到答案?

到开发者社区发帖,或直接提交技术工单,道来的工程师会跟进。