# 优剪运营数据 API v1

Base URL: https://uream.yingbei365.com/api/v1
OpenAPI: https://uream.yingbei365.com/openapi.json
Documentation: https://uream.yingbei365.com/api-docs

认证：Authorization: Bearer <API_KEY>
密钥后台：https://uream.yingbei365.com/api-settings

所有接口 GET 只读，60 次/分钟/密钥。limit=1..500，page=1..10000；按 hasMore/nextPage 读取所有页面。ID/qid 始终作为字符串。

- GET /cities: 地区与城市目录; scope=directory:read; fields=id,name,province,region,officialStoreCount
- GET /stores: 门店目录; scope=directory:read; fields=id,name,city,province,region,address,phone,hours,haircutPrice,coloringPrice,readAt,openedOn,openingSource,firstSeenAt,lastSeenAt,lastCheckedAt,openStatus,district,catalogState,isBaseline
- GET /store-directory-events: 门店新增与目录变化; scope=directory:read; fields=eventKey,storeId,eventType,observedAt,beforeValue,afterValue
- GET /store-directory-runs: 每日门店目录监控; scope=operations:read; fields=runId,finishedAt,status,expectedCities,succeededCities,officialStores,returnedStores,newStores,missingStores,errorCode,nextCheckAt
- GET /hairdressers: 去重理发师名册; scope=staff:read; fields=id,name,readAt,storeIds
- GET /hairdresser-stores: 理发师与门店归属; scope=staff:read; fields=personId,storeId,readAt
- GET /staff-states: 最近在岗快照; scope=staff:read; fields=personId,storeId,activeStatus,waitingCount,status,workState,observedAt,fresh
- GET /queue-records: 逐条取号与最后观察状态; scope=queues:read; fields=qid,storeId,craftsmanId,queuedStatus,sourceTimeText,firstObservedAt,lastObservedAt,firstServiceObservedAt,isBooking,assignmentChanged,currentStatusKnown
- GET /queue-events: 取号状态变化事件; scope=queues:read; fields=eventKey,qid,storeId,craftsmanId,queuedStatus,observedAt
- GET /store-queues: 门店排队快照; scope=queues:read; fields=storeId,queuedCount,waitingText,observedAt,fresh
- GET /store-queue-history: 门店排队历史; scope=queues:read; fields=storeId,queuedCount,waitingText,observedAt,roundId
- GET /confirmations: 确认服务单明细; scope=orders:read; fields=qid,storeId,craftsmanId,confirmedObservedAt
- GET /confirmed-daily: 每人每日确认量; scope=analytics:read; fields=date,storeId,craftsmanId,confirmedOrders
- GET /confirmed-hourly: 每人每小时确认量; scope=analytics:read; fields=date,hour,storeId,craftsmanId,confirmedOrders
- GET /observed-daily: 按首次取号观察日统计; scope=analytics:read; fields=date,storeId,craftsmanId,observedQueueRecords,observedServiceRecords
- GET /observed-hourly: 按首次取号观察小时统计; scope=analytics:read; fields=date,hour,storeId,craftsmanId,observedQueueRecords,observedServiceRecords
- GET /store-rankings: 整店确认观察量排行; scope=analytics:read; fields=storeId,name,city,confirmedOrders,observedHairdressers,lastConfirmedObservedAt,rank,share
- GET /live-summary: 当前人员活动与覆盖汇总; scope=staff:read + queues:read; fields=roster,working,off,unknown,servingObserved,available,eating,resting,paused,awaiting,activityUnknown,queueCoveredStores,queuedCount,detailCoveredStores,detailCoveredPeople
- GET /coverage: 采集窗口与覆盖; scope=operations:read; fields=diagnostics,progress,counts
- GET /roster-coverage: 逐店名册覆盖; scope=operations:read; fields=storeId,readAt,peopleCount
- GET /monitor-runs: 采集运行记录; scope=operations:read; fields=runId,phase,deadlineAt,endedAt,elapsedSeconds,successfulResponses,failedResponses,unavailableResponses,hairdressersObserved
- GET /directory-differences: 目录差异; scope=operations:read; fields=city,expected,actualNonTest,rawReturned,testRecords,checkedAt
- GET /interruptions: 采集中断记录; scope=operations:read; fields=id,lastObservedBefore,restartObservedAt,resumedAt,reason
- GET /excluded-stores: 已排除的测试门店; scope=operations:read; fields=storeId,city,testStatus
- GET /logs: 非敏感采集日志; scope=operations:read; fields=id,observedAt,message

## 增量与分析
updatedSince 仅限明细/快照/目录，包含边界。分页时实时数据仍会变化，请保留重叠窗口，按主键 upsert；不能只凭分页结束宣称无遗漏。聚合统计用 from/to 重读并替换，不能每次累加。每个接口的参数以 OpenAPI 为准，未定义参数会返回 400。401 停止调用并申请新密钥；403 核对 scopes/门店范围；429 等待 Retry-After；503 保留最近有效数据，有限重试。

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

meta.snapshotAt/diagnosticsAt 为 null 时同步尚未齐备，不能报告完整覆盖或零值。没有确认观察的时段无统计行。所有接口不返回顾客身份、顾客手机号、登录会话、私钥与采集凭证。不要在 URL、聊天、代码仓库或日志中展示密钥。