门店与组织 REST API

个人 API 令牌适合对接报表、后台任务等以本人身份运行的服务端应用。门店接口前缀是 /api/v1/stores/{storeId}，组织接口是 /api/v1/orgs/{organizationId}。主体写在 URL 里；不要把门店名或小票短号当作资源 ID。

创建只读令牌

1. 用自己的账号登录商家工作台，在账号菜单进入 API 令牌。
2. 选择需要查询的门店、相应的可委托权限和到期时间。只查订单时选 can_orders_read；如配置 IP 白名单，应填服务端的出口地址。
3. 把仅显示一次的令牌存入服务端密钥配置。下面的命令使用环境变量 FOODIY_API_TOKEN；FOODIY_STORE_ID 是已授权门店的 32 位标识，可从工作台当前门店 URL 中取得。

读取一页订单

下面是服务端终端中的 Bash 示例。请求不下单、不接单，门店没有订单时，空列表也是正常结果。

curl --silent --show-error \
  --header "Authorization: Bearer ${FOODIY_API_TOKEN}" \
  "https://api-fdy.lintuhd.com/api/v1/stores/${FOODIY_STORE_ID}/orders?page=1&pageSize=10"

先检查 HTTP 状态，再读 JSON。成功时 code 为 OK，业务结果在 data；出错时读取 code、message，保留响应中的请求标识供排查。金额字段如 totalMinor 用币种最小单位表示：人民币 12.50 元对应整数 1250。

写入与重试

个人令牌请求无需浏览器 Cookie 或 CSRF。除 GET、HEAD 外，请带 Idempotency-Key；即使是用 POST 表达的编译或试运行，也要带此头。一次操作产生一个键；网络中断时，保留原键、原目标和原请求体，先按对应接口核对结果。遇到版本冲突，重新读取资源再决定是否提交。

错误	检查
401 TOKEN_INVALID	令牌是否过期、撤销，或账号已停用。
403 TOKEN_SCOPE / TOKEN_IP_DENIED	目标门店或组织是否在范围内；出口 IP 是否在允许列表。
403 权限不足	令牌勾选的权限与本人当前权限取交集。角色调整后，旧令牌不会保留已失去的权限。
400 IDEMPOTENCY_KEY_REQUIRED	写请求缺了幂等头；不要通过重复新建令牌解决。

个人令牌不能管理其他令牌或访问平台管理接口。若要给一家门店的助手独立分配工具，请使用门店 MCP。