# 美国签证预约系统 (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)
```