usa_visa_api.md 17 KB

美国签证预约系统 (USVisaScheduling) 核心调度与预约 API 逆向解析

本文档详细记录基于 page3.txt(美签预约与改约页面)逆向分析得出的完整接口链路。涵盖了从查询领事馆可用日期、选定日期查询可用时间场次到选定时间最终提交预约(改约)的完整生命周期、参数生成逻辑、Token 状态流转与响应结构。


目录

  1. 通用通信机制与上下文架构
  2. 步骤一:查询日历有效日期 (get-family-consular-schedule-days)
  3. 步骤二:选定日期查询时间场次 (get-family-consular-schedule-entries)
  4. 步骤三:选定时间最终提交改约/预约 (reschedule-consular-appointments-for-family)
  5. Token 链条流转与安全校验机制
  6. 前置依赖接口 (Context APIs)
  7. Python / 爬虫自动化调用实践指南

一、通用通信机制与上下文架构

USVisaScheduling 基于微软 PowerPages / Dynamics 365 门户构建,所有业务接口均通过统一的代理网关 custom-actions 进行转发。

1. 通用 URL 格式

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 字符串:

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)

{
  "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. 响应结果结构

{
  "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)

{
  "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. 响应结果结构

{
  "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": "<br>"
}

4. 逻辑解析与状态转移

  1. 返回时间场次列表:ScheduleEntries 返回当天所有开放的时间槽。
    • Time: 时间文本(如 "08:00")。
    • EntriesAvailable: 该场次当前剩余可约配额数(如 65)。
    • Num: 场次递增序号(1, 2, ...)。
  2. UI 渲染:前端将每个条目渲染为一个单选框 <input type="radio" value="Num">。用户点击单选框时,将该单选框的 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)

{
  "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. 响应结果结构

成功响应:

{
  "HasError": false,
  "AllScheduled": true,
  "RedirectStub": "appointment-confirmation/",
  "Errors": {
    "m_StringValue": ""
  }
}
  • 成功标志:HasError === false 且 AllScheduled === true。
  • 跳转页面:客户端收到响应后,自动跳转至 /zh-CN/appointment-confirmation/ 查看预约确认单。

常见失败响应与错误码:

{
  "HasError": true,
  "Errors": {
    "m_StringValue": "PSE0612"
  }
}
  • PSE0601: 预约选择无效(场次已被抢占或日期过期)。
  • PSE0602: 缺失关键信息或请求的更改不允许,需要关闭申请后重开。
  • PSE0612: 重新安排预约失败,需要联系客服中心。
  • PSE0610: 系统未知异常。

五、Token 链条流转与安全校验机制

系统通过不可伪造的服务端加密 Token 实现了严格的时序防御,其流转全生命周期如下:

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
  • 请求参数:

    { "applicationId": "e048e82b-b998-f111-a3d0-001dd811d743" }
    
  • 作用: 动态获取该类别申请允许预约的领事馆列表(返回各城市的 Id 与 Name),填充 #post_select。


七、Python / 爬虫自动化调用实践指南

在编写自动化爬虫(如基于 DrissionPage / Playwright / Selenium)时,推荐采用“浏览器内直发 API 请求 (run_js)”的方式,兼顾稳定性和速度:

示例:在当前会话直接查询日期 (直发 API)

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)

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)

示例:极速提交改约预定

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)