# 美国签证预约系统 (USVisaScheduling) 核心调度与预约 API 逆向解析 本文档详细记录基于 [page3.txt](file:///Users/hujiarui/workspace/coordinate/page3.txt)(美签预约与改约页面)逆向分析得出的完整接口链路。涵盖了从**查询领事馆可用日期**、**选定日期查询可用时间场次**到**选定时间最终提交预约(改约)**的完整生命周期、参数生成逻辑、Token 状态流转与响应结构。 --- ## 目录 1. [通用通信机制与上下文架构](#一通用通信机制与上下文架构) 2. [步骤一:查询日历有效日期 (get-family-consular-schedule-days)](#二步骤一查询日历有效日期-get-family-consular-schedule-days) 3. [步骤二:选定日期查询时间场次 (get-family-consular-schedule-entries)](#三步骤二选定日期查询时间场次-get-family-consular-schedule-entries) 4. [步骤三:选定时间最终提交改约/预约 (reschedule-consular-appointments-for-family)](#四步骤三选定时间最终提交改约预约-reschedule-consular-appointments-for-family) 5. [Token 链条流转与安全校验机制](#五token-链条流转与安全校验机制) 6. [前置依赖接口 (Context APIs)](#六前置依赖接口-context-apis) 7. [Python / 爬虫自动化调用实践指南](#七python--爬虫自动化调用实践指南) --- ## 一、通用通信机制与上下文架构 USVisaScheduling 基于微软 PowerPages / Dynamics 365 门户构建,所有业务接口均通过统一的代理网关 `custom-actions` 进行转发。 ### 1. 通用 URL 格式 ```http POST https://www.usvisascheduling.com/zh-CN/custom-actions/?route={route}&appd={contactId}&cacheString={timestamp} ``` - **`route`**: 目标后端 REST API 路径(如 `/api/v1/schedule-group/...`),需要经过 URL 编码。 - **`appd`**: 当前登录用户的 Dynamics 365 唯一联系人 ID(`contactId`,例如 `1ffaaf70-b798-f111-b8dc-001dd8084c2e`)。由服务端 Liquid 模板在页面加载时注入到 `window.Microsoft.Dynamic365.Portal.User.contactId`。 - **`cacheString`**: 客户端当前毫秒级时间戳 `new Date().getTime()`,用于防浏览器 HTTP 缓存。 ### 2. 通用请求头规范 - **`Content-Type`**: `application/x-www-form-urlencoded; charset=UTF-8` - **`Accept`**: `application/json, text/javascript, */*; q=0.01` - **`X-Requested-With`**: `XMLHttpRequest` - **`Cookie`**: 必须包含有效的 `.AspNet.ApplicationCookie`、`ASP.NET_SessionId` 以及 Cloudflare 凭证 `cf_clearance`、`__cf_bm`。 ### 3. 通用请求体格式 请求体不是标准的 raw JSON,而是 URL 表单格式,包含单一字段 `parameters`,其值为序列化后的 JSON 字符串: ```http parameters={"primaryId":"...","postId":"..."} ``` --- ## 二、步骤一:查询日历有效日期 (get-family-consular-schedule-days) 当用户在页面选择领事馆下拉框(触发 `onPostChange` -> `getScheduleDays`)时调用。 ### 1. 接口信息 - **Route**: `/api/v1/schedule-group/get-family-consular-schedule-days` - **Method**: `POST` - **URL 示例**: `https://www.usvisascheduling.com/zh-CN/custom-actions/?route=/api/v1/schedule-group/get-family-consular-schedule-days&appd=1ffaaf70-b798-f111-b8dc-001dd8084c2e&cacheString=1788279318000` ### 2. 请求参数 (`parameters` JSON) ```json { "primaryId": "e048e82b-b998-f111-a3d0-001dd811d743", "applications": [ "e048e82b-b998-f111-a3d0-001dd811d743" ], "postId": "a26af614-b0db-ec11-a7b4-001dd80234f6", "isReschedule": "true" } ``` | 字段 | 类型 | 说明 | | :--- | :--- | :--- | | `primaryId` | string | 主申请人的申请 GUID | | `applications` | array[string] | 本组参与预约的所有申请人 ApplicationID 列表 | | `postId` | string | 目标领事馆 ID(如广州 `a26af614-b0db-ec11-a7b4-001dd80234f6`) | | `isReschedule` | string | 是否为重新预约/改约。改约传 `"true"`,首约无此字段 | ### 3. 响应结果结构 ```json { "ScheduleDays": [ { "Date": "2027-04-06T00:00:00.000Z", "ID": null }, { "Date": "2027-04-13T00:00:00.000Z", "ID": null } ], "Token": "vh1NDnyPCFtEY1v6DUeVr6JmX8xZiugeSoWa5IejTM3uf4NymCUhXduPuuG3Kr+SG0Kbj70MsO5ZVz8Z...", "LocalizedGenericErrorMessage": null, "HasError": false, "ErrorCount": 0, "Errors": { "m_StringValue": "" } } ``` ### 4. 逻辑解析与状态转移 1. **返回有效日期**:`ScheduleDays` 包含所有有号的日期列表(格式为 ISO 字符串)。前端 jQuery UI Datepicker 利用该列表将有效日期高亮标记为绿色(`greenday`),其余日期置灰禁选(`redday`)。 2. **签发阶段性 Token(Token-1)**:返回由服务端生成的超长加密签名 `data.Token`。前端将其暂存在全局变量 `token` 和 `sd` 中。**下一步查询具体时间必须携带此 Token。** 3. 接口调用成功后,前端执行 `delete jsdata["isReschedule"]`,将其从全局对象中清理。 --- ## 三、步骤二:选定日期查询时间场次 (get-family-consular-schedule-entries) 当用户在日历上点击某个具体日期(触发 Datepicker `onSelect` -> `getScheduleEntries`)时调用。 ### 1. 接口信息 - **Route**: `/api/v1/schedule-group/get-family-consular-schedule-entries` - **Method**: `POST` - **URL 示例**: `https://www.usvisascheduling.com/zh-CN/custom-actions/?route=/api/v1/schedule-group/get-family-consular-schedule-entries&appd=1ffaaf70-b798-f111-b8dc-001dd8084c2e&cacheString=1788279602440` ### 2. 请求参数 (`parameters` JSON) ```json { "primaryId": null, "applications": null, "scheduleDayId": null, "scheduleEntryId": "", "postId": null, "Token": "vh1NDnyPCFtEY1v6DUeVr6JmX8xZiugeSoWa5IejTM3uf4NymCUhXduPuuG3Kr+SG0Kbj70MsO5ZVz8Z...", "Date": "2027-04-13T00:00:00.000Z", "isReschedule": "true" } ``` | 字段 | 类型 | 说明 | | :--- | :--- | :--- | | `Token` | string | **步骤一所返回的 `Token`**(必须原样带回,否则服务端无法校验上下文) | | `Date` | string | 选中的目标日期,前端代码强制转换成了 **UTC 时间格式的 ISO 8601 字符串** | | `postId` | null | **前端代码显式重置为 `null`**(由于已包含在 Token 加密体中) | | `primaryId` | null | **前端代码显式重置为 `null`** | | `applications` | null | **前端代码显式重置为 `null`** | | `scheduleDayId` | null | 选中日期对象中的 ID(改约中 `ScheduleDays[i].ID` 原生为 `null`) | | `scheduleEntryId`| string | 默认传空字符串 `""` | | `isReschedule` | string | 改约传 `"true"` | ### 3. 响应结果结构 ```json { "ScheduleDays": null, "ScheduleEntries": [ { "ID": null, "EntriesAvailable": 65, "Time": "08:00", "Num": 1 }, { "ID": null, "EntriesAvailable": 10, "Time": "08:15", "Num": 2 } ], "CategoryID": "00000000-0000-0000-0000-000000000000", "Token": "vh1NDnyPCFtEY1v6DUeVr9hrexujYVBF52kp3AQ9ZKKtM+OLs8L6VxN7zGa2imaTZU4+A4PiMT/19fgosSVAiw2S9mV1G1+FTWnWpIwShet0U/0E2Vnn3RfHpZFOe5Lo...", "LocalizedGenericErrorMessage": null, "HasError": false, "ErrorCount": 0, "Errors": { "m_StringValue": "" }, "ErrorString": "
" } ``` ### 4. 逻辑解析与状态转移 1. **返回时间场次列表**:`ScheduleEntries` 返回当天所有开放的时间槽。 - `Time`: 时间文本(如 `"08:00"`)。 - `EntriesAvailable`: 该场次当前剩余可约配额数(如 `65`)。 - `Num`: 场次递增序号(`1`, `2`, ...)。 2. **UI 渲染**:前端将每个条目渲染为一个单选框 ``。用户点击单选框时,将该单选框的 value 赋值给 `jsdata.Num`。 3. **升级签发最终预约 Token(Token-2)**:服务端在响应中返回了全新的 `data.Token`。该 Token 已经绑定了前一步选择的 `Date` 且包含了最新的时间槽校验信息。前端更新全局变量 `token = data.Token;`。 --- ## 四、步骤三:选定时间最终提交改约/预约 (reschedule-consular-appointments-for-family) 当用户勾选了某个单选框(如 08:00 对应 `Num=1`)并点击“提交预约”按钮(触发 `onClickSubmit`)时调用。 ### 1. 接口信息 - **Route**: `/api/v1/schedule-group/reschedule-consular-appointments-for-family` - **Method**: `POST` - **URL 示例**: `https://www.usvisascheduling.com/zh-CN/custom-actions/?route=/api/v1/schedule-group/reschedule-consular-appointments-for-family&appd=1ffaaf70-b798-f111-b8dc-001dd8084c2e&cacheString=1788279318091` ### 2. 请求参数 (`parameters` JSON) ```json { "primaryId": null, "applications": null, "scheduleDayId": null, "scheduleEntryId": "", "postId": null, "Token": "vh1NDnyPCFtEY1v6DUeVr9hrexujYVBF52kp3AQ9ZKKtM+OLs8L6VxN7zGa2imaTZU4+A4PiMT...", "Date": "2027-04-13T00:00:00.000Z", "Num": "1" } ``` | 字段 | 类型 | 说明 | | :--- | :--- | :--- | | `Token` | string | **步骤二返回的最终预约 `Token`** | | `Date` | string | 选中的目标日期(UTC ISO 字符串,与步骤二保持一致) | | `Num` | string | 选中的具体时间场次编号(来自选中的 Radio 的 value,如 `"1"`) | | `primaryId` / `postId` / `applications` | null | 保持为 `null` | | `scheduleDayId` | null | 保持为 `null` | | `scheduleEntryId`| string | 保持为空字符串 `""` | ### 3. 响应结果结构 #### 成功响应: ```json { "HasError": false, "AllScheduled": true, "RedirectStub": "appointment-confirmation/", "Errors": { "m_StringValue": "" } } ``` - **成功标志**:`HasError === false` 且 `AllScheduled === true`。 - **跳转页面**:客户端收到响应后,自动跳转至 `/zh-CN/appointment-confirmation/` 查看预约确认单。 #### 常见失败响应与错误码: ```json { "HasError": true, "Errors": { "m_StringValue": "PSE0612" } } ``` - **`PSE0601`**: 预约选择无效(场次已被抢占或日期过期)。 - **`PSE0602`**: 缺失关键信息或请求的更改不允许,需要关闭申请后重开。 - **`PSE0612`**: 重新安排预约失败,需要联系客服中心。 - **`PSE0610`**: 系统未知异常。 --- ## 五、Token 链条流转与安全校验机制 系统通过不可伪造的服务端加密 Token 实现了严格的时序防御,其流转全生命周期如下: ```mermaid sequenceDiagram autonumber participant Client as 客户端浏览器 participant Gateway as custom-actions 网关 participant Backend as 预约系统后端 Note over Client,Backend: 阶段一:查询领事馆排期日历 Client->>Gateway: POST get-family-consular-schedule-days (带 postId, primaryId, applications) Gateway->>Backend: 校验用户权限与领事馆 Backend-->>Gateway: 返回 ScheduleDays + 签发 Token-1 (日期级凭证) Gateway-->>Client: 返回包含 ScheduleDays 和 Token-1 的 JSON Note over Client,Backend: 阶段二:选定日期获取具体时间槽 Client->>Gateway: POST get-family-consular-schedule-entries (带 Date + Token-1) Gateway->>Backend: 验证 Token-1 合法性及请求频率 Backend-->>Gateway: 返回 ScheduleEntries (各场次Num与余票) + 签发 Token-2 (场次级凭证) Gateway-->>Client: 返回包含时间场次和 Token-2 的 JSON Note over Client,Backend: 阶段三:选定时间槽最终提交占位 Client->>Gateway: POST reschedule-consular-appointments-for-family (带 Date + Num + Token-2) Gateway->>Backend: 校验 Token-2,原子性扣减配额并写入预约 Backend-->>Gateway: 返回 AllScheduled: true, RedirectStub: appointment-confirmation/ Gateway-->>Client: 改约成功,跳转确认页 ``` ### 核心安全机制: 1. **防跳步验证**:如果不先调步骤一,就无法获得 `Token-1`;没有 `Token-1`,步骤二直接报错 400/403;没有步骤二返回的 `Token-2`,直接调用步骤三会导致签名校验失败。 2. **单次消费(Nonce 特性)**:`Token-2` 一旦被步骤三消费,便立即作废,无法重复提交。 3. **参数置空设计**:在步骤二和步骤三中,`postId`、`primaryId`、`applications` 被前端代码置为 `null`,因为这些敏感实体在步骤一生成 `Token` 时已被服务端哈希并加密在 Token 密文中,避免客户端篡改申请人 ID。 --- ## 六、前置依赖接口 (Context APIs) 在进入日期查询之前,页面通过以下两个接口加载基础上下文: ### 1. 查询家庭成员与申请人列表 (`queryFamilyMembers`) - **Route**: 由前端在 `onVisaClassSelectChange` 中触发。 - **作用**: 提取同组所有申请人的 `ApplicationID`(对应全局 `applications` 数组)和姓名,填充页面 `#gm_select`。 ### 2. 查询可选领事馆列表 (`query-consular-posts`) - **Route**: `/api/v1/schedule-group/query-consular-posts` - **Method**: `POST` - **请求参数**: ```json { "applicationId": "e048e82b-b998-f111-a3d0-001dd811d743" } ``` - **作用**: 动态获取该类别申请允许预约的领事馆列表(返回各城市的 `Id` 与 `Name`),填充 `#post_select`。 --- ## 七、Python / 爬虫自动化调用实践指南 在编写自动化爬虫(如基于 DrissionPage / Playwright / Selenium)时,推荐采用**“浏览器内直发 API 请求 (`run_js`)”**的方式,兼顾稳定性和速度: ### 示例:在当前会话直接查询日期 (直发 API) ```python def fetch_available_dates_via_js(page, post_id: str, appd: str) -> dict: js_code = """ const post_id = arguments[0]; const appd = arguments[1]; const cacheString = new Date().getTime(); const route = "/api/v1/schedule-group/get-family-consular-schedule-days"; // 复用页面已就绪的 jsdata 上下文 jsdata['postId'] = post_id; jsdata['isReschedule'] = "true"; return new Promise((resolve) => { $.ajax({ url: "/zh-CN/custom-actions/?route=" + encodeURI(route) + "&appd=" + appd + "&cacheString=" + cacheString, type: "POST", data: "parameters=" + JSON.stringify(jsdata), contentType: "application/x-www-form-urlencoded; charset=UTF-8", dataType: "json", success: (data) => resolve({ success: true, data: data }), error: (xhr) => resolve({ success: false, status: xhr.status, text: xhr.responseText }) }); }); """ return page.run_js(js_code, post_id, appd) ``` ### 示例:在当前会话直接拉取时间场次 (直发 API) ```python def fetch_time_slots_via_js(page, selected_date: str, token_1: str, appd: str) -> dict: js_code = """ const selectedDate = arguments[0]; const token1 = arguments[1]; const appd = arguments[2]; const cacheString = new Date().getTime(); const route = "/api/v1/schedule-group/get-family-consular-schedule-entries"; // 构造请求参数,置空 ID const payload = { primaryId: null, applications: null, scheduleDayId: null, scheduleEntryId: "", postId: null, Token: token1, Date: new Date(selectedDate).toISOString(), isReschedule: "true" }; return new Promise((resolve) => { $.ajax({ url: "/zh-CN/custom-actions/?route=" + encodeURI(route) + "&appd=" + appd + "&cacheString=" + cacheString, type: "POST", data: "parameters=" + JSON.stringify(payload), contentType: "application/x-www-form-urlencoded; charset=UTF-8", dataType: "json", success: (data) => resolve({ success: true, data: data }), error: (xhr) => resolve({ success: false, status: xhr.status, text: xhr.responseText }) }); }); """ return page.run_js(js_code, selected_date, token_1, appd) ``` ### 示例:极速提交改约预定 ```python def submit_reschedule_via_js(page, selected_date: str, slot_num: int, token_2: str, appd: str) -> dict: js_code = """ const selectedDate = arguments[0]; const slotNum = String(arguments[1]); const token2 = arguments[2]; const appd = arguments[3]; const cacheString = new Date().getTime(); const route = "/api/v1/schedule-group/reschedule-consular-appointments-for-family"; const payload = { primaryId: null, applications: null, scheduleDayId: null, scheduleEntryId: "", postId: null, Token: token2, Date: new Date(selectedDate).toISOString(), Num: slotNum }; return new Promise((resolve) => { $.ajax({ url: "/zh-CN/custom-actions/?route=" + encodeURI(route) + "&appd=" + appd + "&cacheString=" + cacheString, type: "POST", data: "parameters=" + JSON.stringify(payload), contentType: "application/x-www-form-urlencoded; charset=UTF-8", dataType: "json", success: (data) => resolve({ success: true, data: data }), error: (xhr) => resolve({ success: false, status: xhr.status, text: xhr.responseText }) }); }); """ return page.run_js(js_code, selected_date, slot_num, token_2, appd) ```