首页 / API

API

把门店项目的进度接进你自己的系统：项目走到第几步、货发到哪、培训到不到位。全部是只读接口，无需注册、无需 API Key。

基本约定

Base URL: https://www.icook.cloud
鉴权: 本页所列接口不需要任何凭据；凭码接口用链接里的 token 本身作为凭据
格式: JSON（application/json; charset=utf-8），时间一律 UTC
错误: 400 参数错 · 401 缺口令 · 404 不存在，响应体形如 {"error":"…"}
跨域: 不返回 CORS 头——浏览器端跨域调用会被拦，请从你的服务端调用。确需浏览器直连请来信说明来源域名。
频率: 没有硬性配额。请自觉缓存，项目进度按分钟级轮询足够，别按秒轮
版本: 无版本号。字段只增不删；确需破坏性调整会先按邮件通知已知调用方

这些接口驱动的就是本站公开页面本身——你看到的项目页展示什么，接口就返回什么，不多也不少。

开放数据

无需任何凭据。适合把项目进度接进你自己的看板。

GET/api/projects

在推门店项目列表。状态为「进行中」的项目。

字段	说明
`id`	项目号，其余接口的路径参数
`name / biz_type / city`	项目名 · 业态 · 城市
`status`	active（进行中）· 其余为归档态
`current_stage`	当前处在九步中的第几步，1–9
`note`	对外一句话背景（公开字段）
`track / cuisine`	选址赛道 / 菜单品类，与资源库共用取值
`submission_count`	已收方案数（只有数量，无内容）
`stage_counts`	按阶段的方案数，形如 { "5": 12 }
`created_at`	立项时间，UTC

GET/api/projects/:id

单个项目详情。比列表多三个跨阶段状态字段。

字段	说明
`…`	含列表的全部字段
`opening_status`	⑨开业周期状态词（仅状态，无经营数据）
`training_status`	⑧培训周期状态词
`accepted_count`	已采纳方案数

营收、成本、问题、负责人、开业日连字段都不返回——这是设计红线，不是遗漏。

GET/api/projects/:id/sites

该项目的候选铺位短名单（②选址的交付物）。

字段	说明
`site_id`	选址库中的铺位标识；铺位详情在选址库，此处只存引用
`external_title / external_url`	库外铺位的标题与链接
`status`	pending 待实地 · visited 已实地 · chosen 已选定 · rejected 已否决
`note`	候选备注

注意：`note` 是公开字段，会随项目页一起对外展示。写备注时当它是公开的——不要写价格底牌、对家名字或任何不方便被看到的判断。

GET/api/projects/:id/menus

该项目的候选菜单短名单（①诊断的交付物）。结构与候选铺位同构，只存 menu_id 引用。

字段	说明
`menu_id`	菜单库中的菜单标识
`status / note`	同候选铺位

GET/api/projects/:id/shipments

该项目的发运进度。已脱敏：只回几票货、走到哪、几号到、几箱。

字段	说明
`id`	票号
`cargo_class`	food 食品 · general 非食品
`transport_mode`	sea_fcl 整柜 · sea_lcl 拼柜 · air 空运 · ground 美国本地陆运
`cold_chain`	是否冷链，0 / 1
`status`	箱单状态
`node`	depart 起运 · transit 在途 · arrived 到港 · customs 清关 · final_mile 尾程 · delivered 已送达
`eta`	预计到港日
`item_count / carton_total`	货品行数 / 总箱数

只返回已定稿及之后的票。货值、HS CODE、收货地址、承运方、提单号一概不出。

GET/api/projects/:id/training-readiness

该项目的⑧培训就绪度。只回聚合数，无花名册、无个人信息。

字段	说明
`started / status`	是否已启动 · 周期状态词
`staffed / plan_total`	实到人数 / 编制人数
`cert_passed / cert_required`	已通过认证项 / 应有认证项
`critical_passed / critical_required / critical_pending`	关键项通过 / 应有 / 未过
`hollow`	是否「只录了一项就显示满分」的空壳状态
`ready`	是否达到开业的培训条件

完成度按应有项算，不按已建行算——所以 `cert_required` 通常远大于已录入的行数。

凭码接口

链接即凭据。token 由我们随业务链接发出，不对外申请——收到哪条链接就能读哪份单据。

GET/api/ticket/:code

方案评估状态。code 是提交成功页给出的 8 位查询码。

字段	说明
`title / supplier`	方案标题 / 提交方公司名
`stage`	所属阶段 1–9
`status`	new 新提交 · reviewing 评估中 · accepted 已采纳 · rejected 未采纳
`created_at`	提交时间，UTC

不返回方案正文、报价与附件。

GET/api/quote/:token

客户报价单。token 来自我们发出的 /q/ 链接。

字段	说明
`title / category / stage`	报价单标题 · 类目 · 阶段
`quote_amount / quote_currency`	对外报价与币种
`member_discount`	会员折扣比例，0 表示不设会员价档
`items[]`	明细行：name · spec · unit · qty · sale_price · category · img_url
`shipments[]`	关联的发运进度（同上，脱敏）

设了查阅口令的报价单需带 `?pass=<口令>`，否则 401。成本价、加价率、毛利永不返回。

GET/api/booking/:token

物流箱单客户链接的去向。token 来自我们发出的 /logistics/f/ 链接；箱单在 freight.icook.cloud 填写，本接口只回对应的客户链接。

字段	说明
`redirect`	freight 客户链接，带对口令时含 ?pass=；没有对应的单时为 null
`note`	没有对应的单时的说明

同样支持 `?pass=`。不返回箱单内容。

GET/api/booking-share/:token

物流箱单承运方链接的去向。token 来自我们发出的 /logistics/s/ 链接；本接口只回对应的 freight 承运方链接。

字段	说明
`redirect`	freight 承运方链接；没有对应的单时为 null
`note`	没有对应的单时的说明，有去向时为空

不返回箱单内容。

试一下

curl https://www.icook.cloud/api/projects

# 单个项目
curl https://www.icook.cloud/api/projects/1

# 发运进度（脱敏）
curl https://www.icook.cloud/api/projects/1/shipments

# 演示查询码 / 演示报价单（指南里用的那两条）
curl https://www.icook.cloud/api/ticket/GUIDE2026
curl https://www.icook.cloud/api/quote/GUIDEQUOTE26

不提供什么

没有公开的写接口。提交方案、入会申请、填箱单、改报价数量，请走网页表单——它们带有必要的防滥用措施，绕开表单直接打接口的请求会被拒。
不提供方案内容、报价成本与客户名录。这些只在管理端可见。
不提供员工信息。培训模块本身就不存身份、住址、薪资这类数据，只有工号与岗位。
不提供批量导出。需要历史数据请来信说明用途。

要接数据、要浏览器端直连、或需要本页没有的字段？来信 [email protected]，说明用途与调用量。使用本接口即表示接受服务条款；数据处理见隐私政策。