UDREAM OPERATIONS API

让 AI 接入你的
运营分析数据

门店、人员、取号与确认观察数据统一读取。文档公开，业务数据凭密钥私密访问。

只读 API v1Asia/Shanghai权限与门店范围

确认数量是“已观察到服务中”的去重取号量。尚未取得支付流水与完整全天订单。

01 · 快速开始

在私有后台生成密钥，保存到调用程序环境变量 UDREAM_API_KEY。

curl 'https://uream.yingbei365.com/api/v1/confirmed-daily?city=%E6%B7%B1%E5%9C%B3&from=2026-10-05&limit=100' -H "Authorization: Bearer $UDREAM_API_KEY"

Base URL https://uream.yingbei365.com/api/v1
业务接口只允许 GET；ID 和 qid 始终作为字符串保存。

02 · 认证与权限

Authorization: Bearer YOUR_API_KEY

有效期 1–365 天，密钥原文只显示一次，数据库只存摘要。可限制到指定门店。每密钥每分钟 60 次，撤销或过期返回 401。

Scope	数据范围
`directory:read`	门店与地区目录
`staff:read`	理发师与在岗状态
`queues:read`	取号、状态事件与门店排队
`orders:read`	已观察确认服务单
`analytics:read`	每日、小时统计与门店排行
`operations:read`	采集覆盖、中断与日志

live-summary 同时需要 staff:read 和 queues:read。运维信息为全国任务，单店密钥不能选该权限。

03 · 接口目录 · 25 个

点击展开查看查询参数和字段。字段类型见 OpenAPI 定义。

GET/cities地区与城市目录

权限 directory:read
参数：region · province · city · storeId · page · limit · q
返回字段：id · name · province · region · officialStoreCount

GET/stores门店目录

权限 directory:read
参数：region · province · city · storeId · page · limit · q · updatedSince
返回字段：id · name · city · province · region · address · phone · hours · haircutPrice · coloringPrice · readAt · openedOn · openingSource · firstSeenAt · lastSeenAt · lastCheckedAt · openStatus · district · catalogState · isBaseline

openedOn 真实开业日期，当前官方接口未提供时 null；不能用首次发现时间替代。

firstSeenAt 目录首次观察时间；初始已有门店保留最早取得时间，不算新增。

openStatus 官方开业状态原始代码，不是开业日期。

catalogState present 本次返回 / missing 本次未返回 / baseline 初始尚未核对；missing 不代表已关店。

GET/store-directory-events门店新增与目录变化

权限 directory:read
参数：region · province · city · storeId · page · limit · from · to · updatedSince
返回字段：eventKey · storeId · eventType · observedAt · beforeValue · afterValue

GET/store-directory-runs每日门店目录监控

权限 operations:read
参数：page · limit
返回字段：runId · finishedAt · status · expectedCities · succeededCities · officialStores · returnedStores · newStores · missingStores · errorCode · nextCheckAt

nextCheckAt 目录低频监控下次检查时间，每 24 小时一次。

GET/hairdressers去重理发师名册

权限 staff:read
参数：region · province · city · storeId · page · limit · personId · q · updatedSince
返回字段：id · name · readAt · storeIds

storeIds 字符串门店 ID 列表；可能有跨店归属

GET/hairdresser-stores理发师与门店归属

权限 staff:read
参数：region · province · city · storeId · page · limit · personId · updatedSince
返回字段：personId · storeId · readAt

GET/staff-states最近在岗快照

权限 staff:read
参数：region · province · city · storeId · page · limit · personId · updatedSince
返回字段：personId · storeId · activeStatus · waitingCount · status · workState · observedAt · fresh

fresh 快照是否在 7 分钟有效期内；false 时当前状态未知

GET/queue-records逐条取号与最后观察状态

权限 queues:read
参数：region · province · city · storeId · page · limit · personId · updatedSince · from · to · status
返回字段：qid · storeId · craftsmanId · queuedStatus · sourceTimeText · firstObservedAt · lastObservedAt · firstServiceObservedAt · isBooking · assignmentChanged · currentStatusKnown

qid 字符串取号 ID；与支付订单的一对一关系尚未验证

queuedStatus 最后观察状态：0 排队中、1 叫号中、2 服务中、null 未提供

sourceTimeText 小程序时间文案，不是下单时间

currentStatusKnown 最后观察是否在最近 2 分钟内；false 时当前状态未知

GET/queue-events取号状态变化事件

权限 queues:read
参数：region · province · city · storeId · page · limit · personId · updatedSince · from · to · status
返回字段：eventKey · qid · storeId · craftsmanId · queuedStatus · observedAt

qid 字符串取号 ID；与支付订单的一对一关系尚未验证

queuedStatus 最后观察状态：0 排队中、1 叫号中、2 服务中、null 未提供

GET/store-queues门店排队快照

权限 queues:read
参数：region · province · city · storeId · page · limit · updatedSince
返回字段：storeId · queuedCount · waitingText · observedAt · fresh

queuedCount 接口排队人数；null 未取得，不是订单量

fresh 快照是否在 7 分钟有效期内；false 时当前状态未知

GET/store-queue-history门店排队历史

权限 queues:read
参数：region · province · city · storeId · page · limit · from · to · updatedSince
返回字段：storeId · queuedCount · waitingText · observedAt · roundId

queuedCount 接口排队人数；null 未取得，不是订单量

GET/confirmations确认服务单明细

权限 orders:read
参数：region · province · city · storeId · page · limit · personId · updatedSince · from · to
返回字段：qid · storeId · craftsmanId · confirmedObservedAt

qid 字符串取号 ID；与支付订单的一对一关系尚未验证

confirmedObservedAt 首次读到 queuedStatus=2 的 UTC 时间，不是实际下单、服务开始或支付时间

GET/confirmed-daily每人每日确认量

权限 analytics:read
参数：region · province · city · storeId · page · limit · personId · from · to
返回字段：date · storeId · craftsmanId · confirmedOrders

date Asia/Shanghai 观察日期 YYYY-MM-DD

confirmedOrders 已观察到服务中的 qid 去重数，不是完整付款成交量

GET/confirmed-hourly每人每小时确认量

权限 analytics:read
参数：region · province · city · storeId · page · limit · personId · from · to
返回字段：date · hour · storeId · craftsmanId · confirmedOrders

date Asia/Shanghai 观察日期 YYYY-MM-DD

hour Asia/Shanghai 观察小时 00–23

confirmedOrders 已观察到服务中的 qid 去重数，不是完整付款成交量

GET/observed-daily按首次取号观察日统计

权限 analytics:read
参数：region · province · city · storeId · page · limit · personId · from · to
返回字段：date · storeId · craftsmanId · observedQueueRecords · observedServiceRecords

date Asia/Shanghai 观察日期 YYYY-MM-DD

observedServiceRecords 按首次取号观察时间汇总的曾服务记录数，不可替代 confirmed 统计

GET/observed-hourly按首次取号观察小时统计

权限 analytics:read
参数：region · province · city · storeId · page · limit · personId · from · to
返回字段：date · hour · storeId · craftsmanId · observedQueueRecords · observedServiceRecords

date Asia/Shanghai 观察日期 YYYY-MM-DD

hour Asia/Shanghai 观察小时 00–23

observedServiceRecords 按首次取号观察时间汇总的曾服务记录数，不可替代 confirmed 统计

GET/store-rankings整店确认观察量排行

权限 analytics:read
参数：region · province · city · storeId · page · limit · from · to · q
返回字段：storeId · name · city · confirmedOrders · observedHairdressers · lastConfirmedObservedAt · rank · share

confirmedOrders 已观察到服务中的 qid 去重数，不是完整付款成交量

rank 同确认观察量并列排名，无确认观察为 null

share 所选地区确认观察量占比，无确认观察为 null

GET/live-summary当前人员活动与覆盖汇总

权限 staff:read + queues:read
参数：region · province · city · storeId · personId
返回字段：roster · working · off · unknown · servingObserved · available · eating · resting · paused · awaiting · activityUnknown · queueCoveredStores · queuedCount · detailCoveredStores · detailCoveredPeople

queuedCount 接口排队人数；null 未取得，不是订单量

GET/coverage采集窗口与覆盖

权限 operations:read
参数：page · limit
返回字段：diagnostics · progress · counts

GET/roster-coverage逐店名册覆盖

权限 operations:read
参数：page · limit
返回字段：storeId · readAt · peopleCount

GET/monitor-runs采集运行记录

权限 operations:read
参数：page · limit
返回字段：runId · phase · deadlineAt · endedAt · elapsedSeconds · successfulResponses · failedResponses · unavailableResponses · hairdressersObserved

GET/directory-differences目录差异

权限 operations:read
参数：page · limit
返回字段：city · expected · actualNonTest · rawReturned · testRecords · checkedAt

GET/interruptions采集中断记录

权限 operations:read
参数：page · limit
返回字段：id · lastObservedBefore · restartObservedAt · resumedAt · reason

GET/excluded-stores已排除的测试门店

权限 operations:read
参数：page · limit
返回字段：storeId · city · testStatus

GET/logs非敏感采集日志

权限 operations:read
参数：page · limit
返回字段：id · observedAt · message

04 · 分页、筛选与增量

按接口定义使用 region、province、city、storeId、personId、from/to。未支持的参数返回 400。日期均按北京时间包含边界。

{
  "data": [
    {
      "qid": "STRING_ID",
      "confirmedObservedAt": "UTC_ISO_8601"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 1234,
    "hasMore": true,
    "nextPage": 2
  },
  "meta": {
    "snapshotAt": "UTC_ISO_8601",
    "timezone": "Asia/Shanghai",
    "limitations": [
      "统计口径"
    ]
  }
}

按 hasMore/nextPage 读取全部页，limit 最大 500。
updatedSince 包含边界；按主键 upsert 去重。实时写入时分页可能变动，请保留重叠窗口避免漏掉变更。
日/小时统计与排行按日期重读并替换，不能每次重复累加。
排行 q 搜索保留地区内排名与占比。无确认观察 rank=null，不认定为真实零单。
confirmed 日期是首次服务观察；observed 与 queue-records 日期是首次取号观察；queue-events 和排队历史日期是事件/快照时间。

05 · 分析时必须保留的口径

开业日期 openedOn 仅接受已核实的官方开业日期；当前接口未提供时为 null。firstSeenAt 是首次发现，不代表开业。目录每日检查，暂时未返回不等于关店。
确认单是 qid 首次被观察到 queuedStatus=2 服务中，按 qid 去重并保留首次服务归属；不代表支付完成或全天完整成交量。
日、小时按首次服务观察时间的 Asia/Shanghai 时区统计；confirmed 与 observed 两类统计时间不可混用。
实际下单、服务开始、支付时间、消费金额、客单价和完整历史尚未取得；逐人轮询可能漏计。
无观察的时段没有统计行，不认定为真实零单。空值、失败、休息或 qid 消失不代表零单或服务完成。
在岗及门店排队快照超过 7 分钟转未知；逐条服务详情超过 2 分钟当前未知。排队人数不是确认订单数。
目录取得 2167 家，官方城市计数 2168 家，差 1 家原因未明；人员为取得目录范围内去重名册，可能继续增长。

snapshotAt 为业务同步时间，diagnosticsAt 为历史与覆盖同步时间，为 null 时数据未齐备。接口不返回顾客身份、顾客手机号、会话、私钥与采集凭证。

06 · 错误处理

HTTP	处理方式
400	核对参数、ID、日期与分页范围
401	停止调用；密钥缺失、过期或撤销
403	核对权限和门店范围
404	查阅接口定义
429	按 Retry-After: 60 等待
503	保留最近数据并有限重试

{"error":{"code":"SCOPE_DENIED","message":"密钥缺少 orders:read 权限"},"requestId":"..."}

07 · Python 分页读取示例

import os, requests
base = "https://uream.yingbei365.com/api/v1"
headers = {"Authorization": "Bearer " + os.environ["UDREAM_API_KEY"]}
page = 1
while True:
    r = requests.get(base + "/confirmations", headers=headers,
        params={"city": "深圳", "page": page, "limit": 500}, timeout=30)
    r.raise_for_status()
    body = r.json()
    for item in body["data"]:
        # 按字符串 qid 持久化 upsert
        print(item["qid"], item["confirmedObservedAt"])
    if not body["pagination"]["hasMore"]: break
    page = body["pagination"]["nextPage"]

其他 AI 可先读取 /openapi.json 或 /llms.txt，再使用你的专用密钥调用。

只读接口 v1.0.0 · 后台与采集保持私有 · 接口只返回已保存的观察记录

让 AI 接入你的运营分析数据

01 · 快速开始

02 · 认证与权限

03 · 接口目录 · 25 个

04 · 分页、筛选与增量

05 · 分析时必须保留的口径

06 · 错误处理

07 · Python 分页读取示例

让 AI 接入你的
运营分析数据