{
  "info": {
    "_postman_id": "4f6c2b1e-8a37-4d5e-9c1a-7b2e3d4f5a60",
    "name": "优时开放平台 v1",
    "description": "优时开放平台对外接口。\n\n1. 在集合变量里填写 base_url、appid、secret、sign_key；\n2. 集合的 Pre-request Script 会自动获取 token、给每个请求签名（X-Timestamp / X-Nonce / X-Sign）；\n3. 按目录顺序调用，门店、服务、预约、号码 ID 会自动保存到变量里。\n\n签名规则见 examples/sign/README.md。",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{access_token}}",
        "type": "string"
      }
    ]
  },
  "event": [
    {
      "listen": "prerequest",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// 优时开放平台 · 集合级 Pre-request Script：对集合内每个请求（获取 token 除外）自动续期 token 并签名。",
          "// 签名串 = METHOD + \"\\n\" + path + \"\\n\" + X-Timestamp + \"\\n\" + X-Nonce + \"\\n\" + sha256_hex(body)",
          "// X-Sign = lower_hex(HMAC-SHA256(sign_key, 签名串))；path 不含域名和查询参数，body 是实际发送的原始请求体",
          "const path = pm.variables.replaceIn(pm.request.url.getPath());",
          "",
          "if (path !== '/oauth/token') {",
          "  // 1. 每个请求生成新的单号，请求体里用 {{request_no}} 引用。",
          "  //    不要在请求体里用 {{$timestamp}}、{{$randomInt}} 等动态变量：发送时会重新取值，导致签名对不上。",
          "  pm.variables.set('request_no', 'PM' + Date.now() + Math.floor(Math.random() * 1000));",
          "",
          "  // 2. 签名：body 取变量替换之后的原始文本（就是 Postman 实际发送的内容）",
          "  const method = pm.request.method.toUpperCase();",
          "  let body = '';",
          "  if (pm.request.body && !pm.request.body.disabled && pm.request.body.mode === 'raw' && pm.request.body.raw) {",
          "    body = pm.variables.replaceIn(pm.request.body.raw);",
          "  }",
          "  const timestamp = String(Math.floor(Date.now() / 1000));",
          "  const nonce = CryptoJS.lib.WordArray.random(16).toString(CryptoJS.enc.Hex);",
          "  const bodyHash = CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);",
          "  const stringToSign = [method, path, timestamp, nonce, bodyHash].join('\\n');",
          "  const sign = CryptoJS.HmacSHA256(stringToSign, pm.variables.get('sign_key') || '').toString(CryptoJS.enc.Hex);",
          "  pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });",
          "  pm.request.headers.upsert({ key: 'X-Nonce', value: nonce });",
          "  pm.request.headers.upsert({ key: 'X-Sign', value: sign });",
          "",
          "  // 3. token 为空或快过期时自动获取（集合的 Authorization 使用 Bearer {{access_token}}）",
          "  const token = pm.collectionVariables.get('access_token');",
          "  const expiresAt = Number(pm.collectionVariables.get('access_token_expires_at') || 0);",
          "  if (!token || Date.now() / 1000 >= expiresAt) {",
          "    pm.sendRequest({",
          "      url: pm.variables.replaceIn('{{base_url}}') + '/oauth/token',",
          "      method: 'POST',",
          "      header: { 'Content-Type': 'application/json' },",
          "      body: {",
          "        mode: 'raw',",
          "        raw: JSON.stringify({",
          "          appid: pm.variables.get('appid'),",
          "          secret: pm.variables.get('secret'),",
          "          grant_type: 'client_credential',",
          "        }),",
          "      },",
          "    }, (err, res) => {",
          "      if (err) {",
          "        console.error('自动获取 token 失败', err);",
          "        return;",
          "      }",
          "      const json = res.json();",
          "      if (json.code !== 0) {",
          "        console.error('自动获取 token 失败', json.code, json.msg, json.request_id);",
          "        return;",
          "      }",
          "      pm.collectionVariables.set('access_token', json.data.access_token);",
          "      // 提前 5 分钟刷新",
          "      pm.collectionVariables.set('access_token_expires_at', String(Math.floor(Date.now() / 1000) + json.data.expires_in - 300));",
          "      // 不需要手动设置 Authorization：Postman 在脚本执行完之后才解析 {{access_token}}",
          "    });",
          "  }",
          "}"
        ]
      }
    },
    {
      "listen": "test",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// 集合级 Tests：所有接口统一返回 {code, msg, data, request_id}",
          "let json = null;",
          "try {",
          "  json = pm.response.json();",
          "} catch (e) {",
          "  // 非 JSON（例如网关错误页），下面的断言会失败",
          "}",
          "pm.test('返回统一格式', () => pm.expect(json).to.be.an('object').that.has.all.keys('code', 'msg', 'data', 'request_id'));",
          "if (json && json.code !== 0) {",
          "  console.warn(pm.info.requestName, 'code=' + json.code, json.msg, 'request_id=' + json.request_id);",
          "}"
        ]
      }
    }
  ],
  "item": [
    {
      "name": "认证",
      "item": [
        {
          "name": "获取 token",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{base_url}}/oauth/token",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "oauth",
                "token"
              ]
            },
            "description": "用 appid + secret 换取 access_token（有效期 2 小时）。成功后自动保存到集合变量 access_token。\n\n一般不用手动调用：集合的 Pre-request Script 会在 token 为空或快过期时自动获取。",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"appid\": \"{{appid}}\",\n  \"secret\": \"{{secret}}\",\n  \"grant_type\": \"client_credential\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "auth": {
              "type": "noauth"
            }
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('获取 token 成功', () => pm.expect(json.code).to.eql(0));",
                  "if (json.code === 0) {",
                  "  pm.collectionVariables.set('access_token', json.data.access_token);",
                  "  // 提前 5 分钟刷新",
                  "  pm.collectionVariables.set('access_token_expires_at', String(Math.floor(Date.now() / 1000) + json.data.expires_in - 300));",
                  "}"
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "name": "门店（store.read）",
      "item": [
        {
          "name": "门店列表",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/stores",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "stores"
              ]
            },
            "description": "所绑定商户的门店列表。自动把第一个门店保存到变量 store_id。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('查询门店成功', () => pm.expect(json.code).to.eql(0));",
                  "const value = json.code === 0 ? (json.data.items[0] || {}).store_id : null;",
                  "if (value) {",
                  "  pm.collectionVariables.set('store_id', value);",
                  "}"
                ]
              }
            }
          ]
        },
        {
          "name": "门店详情",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/stores/{{store_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "stores",
                "{{store_id}}"
              ]
            },
            "description": "名称、地址、营业时间、时区、是否开启排队和预约。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('查询成功', () => pm.expect(json.code).to.eql(0));"
                ]
              }
            }
          ]
        },
        {
          "name": "排队状态",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/stores/{{store_id}}/queue",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "stores",
                "{{store_id}}",
                "queue"
              ]
            },
            "description": "当前叫号、排队人数、预计等待时间。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('查询成功', () => pm.expect(json.code).to.eql(0));"
                ]
              }
            }
          ]
        },
        {
          "name": "服务项目",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/stores/{{store_id}}/services",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "stores",
                "{{store_id}}",
                "services"
              ]
            },
            "description": "服务项目列表。自动把第一个服务项目保存到变量 service_id。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('查询成功', () => pm.expect(json.code).to.eql(0));",
                  "const value = json.code === 0 ? (json.data.items[0] || {}).service_id : null;",
                  "if (value) {",
                  "  pm.collectionVariables.set('service_id', value);",
                  "}"
                ]
              }
            }
          ]
        },
        {
          "name": "可约时段",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/stores/{{store_id}}/slots?service_id={{service_id}}&date={{date}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "stores",
                "{{store_id}}",
                "slots"
              ],
              "query": [
                {
                  "key": "service_id",
                  "value": "{{service_id}}",
                  "description": "服务项目 ID（必填）"
                },
                {
                  "key": "date",
                  "value": "{{date}}",
                  "description": "日期 YYYY-MM-DD（必填，门店当地日期）"
                }
              ]
            },
            "description": "可约时段和剩余名额。date 按门店时区解释。\n\n自动把第一个还有名额的时段保存到变量 start_time。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('查询成功', () => pm.expect(json.code).to.eql(0));",
                  "const value = json.code === 0 ? (json.data.items.find((s) => s.remaining > 0) || {}).start_time : null;",
                  "if (value) {",
                  "  pm.collectionVariables.set('start_time', value);",
                  "}"
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "name": "预约（booking.read / booking.write）",
      "item": [
        {
          "name": "创建预约",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{base_url}}/v1/bookings",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "bookings"
              ]
            },
            "description": "out_booking_no 是你的单号（幂等键），超时重试时要用同一个单号；这里用每次自动生成的 {{request_no}}。\n\n成功后自动保存 booking_id。",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"out_booking_no\": \"{{request_no}}\",\n  \"store_id\": \"{{store_id}}\",\n  \"service_id\": \"{{service_id}}\",\n  \"date\": \"{{date}}\",\n  \"start_time\": \"{{start_time}}\",\n  \"user\": {\n    \"open_user_id\": \"u_8823\",\n    \"mobile\": \"13800000000\",\n    \"name\": \"张先生\"\n  },\n  \"remark\": \"靠窗的位置\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('创建预约成功', () => pm.expect(json.code).to.eql(0));",
                  "const value = json.code === 0 ? json.data.booking_id : null;",
                  "if (value) {",
                  "  pm.collectionVariables.set('booking_id', value);",
                  "}"
                ]
              }
            }
          ]
        },
        {
          "name": "查询预约",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/bookings/{{booking_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "bookings",
                "{{booking_id}}"
              ]
            },
            "description": "只能查询本应用创建的预约。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('查询成功', () => pm.expect(json.code).to.eql(0));"
                ]
              }
            }
          ]
        },
        {
          "name": "到店签到",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/bookings/{{booking_id}}/checkin",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "bookings",
                "{{booking_id}}",
                "checkin"
              ]
            },
            "description": "签到后返回预约和生成的号码。只有待到店（pending）的预约能签到，签到时间为时段开始前 60 分钟到开始后 15 分钟，否则返回 40903。没有请求体，按空字符串签名。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('签到成功', () => pm.expect(json.code).to.eql(0));"
                ]
              }
            }
          ]
        },
        {
          "name": "取消预约",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{base_url}}/v1/bookings/{{booking_id}}/cancel",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "bookings",
                "{{booking_id}}",
                "cancel"
              ]
            },
            "description": "reason 可选，最长 200 个字符。已取消时直接返回，便于重试。",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"reason\": \"用户主动取消\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('取消成功', () => pm.expect(json.code).to.eql(0));"
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "name": "号码（ticket.read / ticket.write）",
      "item": [
        {
          "name": "现场取号",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{base_url}}/v1/tickets",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "tickets"
              ]
            },
            "description": "out_ticket_no 是你的单号（幂等键）；service_id、user 可选。成功后自动保存 ticket_id。",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"out_ticket_no\": \"{{request_no}}\",\n  \"store_id\": \"{{store_id}}\",\n  \"service_id\": \"{{service_id}}\",\n  \"user\": {\n    \"open_user_id\": \"u_8823\",\n    \"mobile\": \"13800000000\",\n    \"name\": \"张先生\"\n  }\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('取号成功', () => pm.expect(json.code).to.eql(0));",
                  "const value = json.code === 0 ? json.data.ticket_id : null;",
                  "if (value) {",
                  "  pm.collectionVariables.set('ticket_id', value);",
                  "}"
                ]
              }
            }
          ]
        },
        {
          "name": "查询号码",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/tickets/{{ticket_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "tickets",
                "{{ticket_id}}"
              ]
            },
            "description": "号码状态和前面等待人数（只能查询本应用取的号）。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('查询成功', () => pm.expect(json.code).to.eql(0));"
                ]
              }
            }
          ]
        },
        {
          "name": "取消号码",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/tickets/{{ticket_id}}/cancel",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "tickets",
                "{{ticket_id}}",
                "cancel"
              ]
            },
            "description": "没有请求体，按空字符串签名。取消后不能再叫号：想按顺序体验叫号流程，可以先跳过这个请求。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('取消成功', () => pm.expect(json.code).to.eql(0));"
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "name": "叫号（call.write，门店自有系统）",
      "item": [
        {
          "name": "门店排队列表",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/stores/{{store_id}}/tickets?status=waiting,called",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "stores",
                "{{store_id}}",
                "tickets"
              ],
              "query": [
                {
                  "key": "status",
                  "value": "waiting,called",
                  "description": "状态过滤（可选）"
                },
                {
                  "key": "date",
                  "value": "{{date}}",
                  "description": "门店当地日期（可选，默认今天）",
                  "disabled": true
                }
              ]
            },
            "description": "门店当天完整排队列表（含其他渠道的号码）。**虽然是 GET，也必须签名**（call.write）。\n\nstatus 可逗号分隔多个：waiting、called、completed、skipped、cancelled；date 只能是门店当地今天或昨天，默认今天。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('查询成功', () => pm.expect(json.code).to.eql(0));"
                ]
              }
            }
          ]
        },
        {
          "name": "叫下一位",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/stores/{{store_id}}/call-next",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "stores",
                "{{store_id}}",
                "call-next"
              ]
            },
            "description": "不是幂等的：超时后先查看排队列表再决定是否重试。叫到号码时自动保存为 ticket_id；没有等待的号码时 data.ticket 为 null。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('叫号成功', () => pm.expect(json.code).to.eql(0));",
                  "const value = json.code === 0 ? (json.data.ticket || {}).ticket_id : null;",
                  "if (value) {",
                  "  pm.collectionVariables.set('ticket_id', value);",
                  "}"
                ]
              }
            }
          ]
        },
        {
          "name": "重新叫号",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/tickets/{{ticket_id}}/recall",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "tickets",
                "{{ticket_id}}",
                "recall"
              ]
            },
            "description": "没有请求体，按空字符串签名。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('操作成功', () => pm.expect(json.code).to.eql(0));"
                ]
              }
            }
          ]
        },
        {
          "name": "过号",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/tickets/{{ticket_id}}/skip",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "tickets",
                "{{ticket_id}}",
                "skip"
              ]
            },
            "description": "没有请求体，按空字符串签名。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('操作成功', () => pm.expect(json.code).to.eql(0));"
                ]
              }
            }
          ]
        },
        {
          "name": "完成",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{base_url}}/v1/tickets/{{ticket_id}}/finish",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "v1",
                "tickets",
                "{{ticket_id}}",
                "finish"
              ]
            },
            "description": "没有请求体，按空字符串签名。"
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const json = pm.response.json();",
                  "pm.test('操作成功', () => pm.expect(json.code).to.eql(0));"
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "variable": [
    {
      "key": "base_url",
      "value": "https://open-api.yours.xyz",
      "type": "string",
      "description": "只写协议和域名（可带端口），不要带 /v1"
    },
    {
      "key": "appid",
      "value": "",
      "type": "string",
      "description": "应用 appid（op_ 开头）"
    },
    {
      "key": "secret",
      "value": "",
      "type": "string",
      "description": "应用 secret"
    },
    {
      "key": "sign_key",
      "value": "",
      "type": "string",
      "description": "签名密钥"
    },
    {
      "key": "access_token",
      "value": "",
      "type": "string",
      "description": "自动维护"
    },
    {
      "key": "access_token_expires_at",
      "value": "0",
      "type": "string",
      "description": "自动维护（秒级时间戳，提前 5 分钟过期）"
    },
    {
      "key": "store_id",
      "value": "",
      "type": "string",
      "description": "「门店列表」自动保存"
    },
    {
      "key": "service_id",
      "value": "",
      "type": "string",
      "description": "「服务项目」自动保存"
    },
    {
      "key": "date",
      "value": "2026-11-18",
      "type": "string",
      "description": "预约 / 查询时段使用的日期（门店当地日期），请改成今天之后的日期"
    },
    {
      "key": "start_time",
      "value": "10:00",
      "type": "string",
      "description": "「可约时段」自动保存"
    },
    {
      "key": "booking_id",
      "value": "",
      "type": "string",
      "description": "「创建预约」自动保存"
    },
    {
      "key": "ticket_id",
      "value": "",
      "type": "string",
      "description": "「现场取号」或「叫下一位」自动保存"
    }
  ]
}
