本文档为 Coordinate 管理系统的前端接口规范,包含 服务商模板管理(Provider) 与 节点任务配置管理(Node Configuration: booker / sentinel / standalone) 的所有接口定义、字段说明及 JSON 示例。
/api (例如 http://127.0.0.1:8888/api)请求头: 除公共登录接口外,所有请求均须携带 Bearer Token:
Authorization: Bearer <token>
Content-Type: application/json
统一响应格式:
{
"code": 0,
"message": "success",
"data": {}
}
code === 0 表示请求成功;code !== 0 表示业务异常,此时 message 包含人类可读的错误提示信息。| code | HTTP 状态 | 说明 |
|---|---|---|
0 |
200 | 成功 |
40000 |
400 | 参数校验失败 / 掩码占位符拦截 / 删除最后一条未确认 |
40101 |
401 | 未登录或 Token 无效/已过期 |
40301 |
403 | 权限不足 (非管理员) |
40400 |
404 | 目标资源不存在 |
40900 |
409 | Provider 名称已被占用 |
40902 |
409 | 标识符冲突 (同节点下 node_id + identifier 已存在) |
42200 |
422 | 请求 Body 结构或数据类型非法 |
GET /api/providersenabled_only (boolean, 可选, 默认 false): 设为 true 时仅返回已启用的服务商(适用于向导新建下拉框)。响应示例 (code: 0):
{
"code": 0,
"message": "success",
"data": [
{
"id": 1,
"name": "vfs",
"enabled": 1,
"plugin_config": {
"lib_path": "plugins",
"plugin_name": "vfs_plugin",
"plugin_bin": "vfs_plugin.py",
"plugin_proto": "IVSPlg"
},
"role_templates": {
"booker": {
"proxy_cd": 300,
"session_max_life": 1800,
"booker.account_cd": 10800,
"booker.target_instances": 1
},
"sentinel": {
"sentinel.signal_ttl": 30,
"sentinel.query_wait.mode": "Random"
}
},
"version": 1,
"updated_by": "admin",
"created_at": "2026-08-23T20:00:00",
"updated_at": "2026-08-23T20:00:00"
}
]
}
GET /api/providers/{name}name (string, 必填): 服务商唯一标识/名称(如 vfs, tls, bls)。响应示例 (code: 0):
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"name": "vfs",
"enabled": 1,
"plugin_config": {
"lib_path": "plugins",
"plugin_name": "vfs_plugin",
"plugin_bin": "vfs_plugin.py",
"plugin_proto": "IVSPlg"
},
"role_templates": {
"booker": {
"proxy_cd": 300,
"session_max_life": 1800,
"booker.account_cd": 10800
},
"sentinel": {
"sentinel.signal_ttl": 30
}
},
"version": 1,
"updated_by": "admin",
"created_at": "2026-08-23T20:00:00",
"updated_at": "2026-08-23T20:00:00"
}
}
POST /api/providersname (string, 必填): 服务商唯一标识/名称(如 vfs, tls, bls 等)。enabled (boolean, 可选, 默认 true): 是否启用。plugin_config (object, 可选): 默认插件加载配置。role_templates (object, 可选): 角色配置模板(键仅允许 sentinel / booker / standalone,值为点路径平铺字典)。请求示例:
{
"name": "tls",
"enabled": true,
"plugin_config": {
"lib_path": "plugins",
"plugin_name": "tls_plugin",
"plugin_bin": "tls_plugin.py",
"plugin_proto": "IVSPlg"
},
"role_templates": {
"standalone": {
"login_interval": 1800,
"session_max_life": 3600
}
}
}
响应示例 (code: 0):
{
"code": 0,
"message": "Provider created successfully",
"data": {
"id": 2,
"name": "tls",
"enabled": 1,
"plugin_config": { ... },
"role_templates": { ... },
"version": 1,
"updated_by": "admin",
"created_at": "2026-08-23T20:05:00",
"updated_at": "2026-08-23T20:05:00"
}
}
PUT /api/providers/{name}name):
enabled (boolean, 可选): 启用状态。plugin_config (object, 可选): 插件配置对象。role_templates (object, 可选): 角色配置模板(覆盖更新)。请求示例:
{
"enabled": true,
"plugin_config": {
"lib_path": "plugins",
"plugin_name": "tls_plugin_v2",
"plugin_bin": "tls_plugin.py",
"plugin_proto": "IVSPlg"
}
}
响应示例 (code: 0): 返回更新后的 Provider 完整对象。
DELETE /api/providers/{name}响应示例 (code: 0):
{
"code": 0,
"message": "Provider deleted successfully",
"data": true
}
entry_type说明: 所有端点中的{entry_type}统一取值为:
booker(Booker 占位/出票角色)sentinel(Sentinel 监控/扫位角色)standalone(Standalone 独立一体化抢签任务)
GET /api/node-configurations/{entry_type}page (integer, 可选, 默认 1): 页码。pageSize (integer, 可选, 默认 20): 每页条数(最大 100)。identifier (string, 可选): 任务标识模糊搜索(如 vfs)。node_id (string, 可选): 节点唯一标识精确搜索(如 node01)。order_id (string, 可选, 仅 standalone 有效): 关联订单 ID 精确搜索。响应示例 (code: 0):
{
"code": 0,
"message": "success",
"data": {
"total": 1,
"page": 1,
"page_size": 20,
"items": [
{
"id": 101,
"node_id": "node01",
"identifier": "vfs.ie.nl",
"enable": 0,
"debug": 0,
"need_account": 1,
"need_proxy": 1,
"proxy_pool": ["proxy-cheap"],
"proxy_cd": 300,
"session_max_life": 1800,
"active_time_start": "00:00",
"active_time_end": "23:59",
"website": "https://visa.vfsglobal.com/irl/en/nld/login",
"booker": {
"account_source": "built-in",
"account_pool_id": "ie.nl.booker",
"account_cd": 10800,
"target_instances": 1
},
"plugin_config": {
"lib_path": "plugins",
"plugin_name": "vfs_plugin",
"plugin_bin": "vfs_plugin.py",
"plugin_proto": "IVSPlg"
},
"appointment_types": [
{
"weight": 10,
"routing_key": "slot.dub.nl.tourist",
"city": "Dublin",
"visa_type": "Tourist",
"country": "Netherlands"
}
],
"free_config": {
"mission_code": "nld",
"country_code": "irl"
},
"version": 1,
"updated_by": "admin",
"created_at": "2026-08-23T20:10:00",
"updated_at": "2026-08-23T20:10:00"
}
]
}
}
GET /api/node-configurations/{entry_type}/{entry_id}entry_type (string, 必填): booker | sentinel | standaloneentry_id (integer, 必填): 配置条目主键 ID响应示例 (code: 0): 返回该配置条目的全字段对象。
POST /api/node-configurations/{entry_type}enable = 0);同一节点下 (node_id, identifier) 冲突时返回 40902。{
"node_id": "node01",
"identifier": "vfs.ie.nl",
"website": "https://visa.vfsglobal.com/irl/en/nld/login",
"need_account": 1,
"need_proxy": 1,
"proxy_pool": ["proxy-cheap"],
"proxy_cd": 300,
"session_max_life": 1800,
"active_time_start": "00:00",
"active_time_end": "23:59",
"booker": {
"account_source": "built-in",
"account_pool_id": "ie.nl.booker",
"target_instances": 1,
"account_cd": 10800,
"booking_cooldown": 300,
"max_bookings_per_account": 8
},
"plugin_config": {
"lib_path": "plugins",
"plugin_name": "vfs_plugin",
"plugin_bin": "vfs_plugin.py",
"plugin_proto": "IVSPlg"
},
"appointment_types": [
{
"weight": 10,
"routing_key": "slot.dub.nl.tourist",
"city": "Dublin",
"visa_type": "Tourist",
"country": "Netherlands"
}
],
"free_config": {
"mission_code": "nld",
"country_code": "irl"
}
}
{
"node_id": "node01",
"identifier": "vfs.ie.nl",
"website": "https://visa.vfsglobal.com/irl/en/nld/login",
"sentinel": {
"account_source": "built-in",
"account_pool_id": "ie.nl.sentinel",
"target_instances": 1,
"signal_ttl": 30,
"query_wait": {
"mode": "Random",
"fixed_wait": 10,
"random_min": 60,
"random_max": 300
}
},
"plugin_config": { ... },
"appointment_types": [ ... ],
"free_config": { ... }
}
{
"node_id": "node01",
"order_id": "ORD-20260823-001",
"identifier": "tls.shanghai.fr",
"account": {
"username": "user@example.com",
"password": "Password123"
},
"proxy_pool": ["proxy-cheap"],
"query_wait": {
"mode": "Random",
"fixed_wait": 10,
"random_min": 55,
"random_max": 65
},
"login_interval": 1800,
"session_max_life": 3600,
"user_preferences": {
"support_pta": false,
"expected_start_date": "2026-09-01",
"expected_end_date": "2026-09-20"
},
"plugin_config": { ... },
"appointment_types": [ ... ],
"free_config": { ... }
}
响应示例 (code: 0): 返回新生成的配置对象(初始 enable: 0, version: 1)。
PUT /api/node-configurations/{entry_type}/{entry_id}set:支持顶级字段(如 proxy_cd)与多层 JSON 点路径更新(如 booker.account_cd、sentinel.query_wait.random_min)。clear:显式将字段清空重置为默认空值(如 website 重置为空串、account 重置为空对象)。version 版本号自增 +1。请求示例:
{
"set": {
"proxy_cd": 600,
"booker.account_cd": 9000,
"booker.target_instances": 2
},
"clear": [
"website"
]
}
响应示例 (code: 0):
{
"code": 0,
"message": "Node configuration updated successfully",
"data": {
"id": 101,
"node_id": "node01",
"identifier": "vfs.ie.nl",
"proxy_cd": 600,
"website": "",
"booker": {
"account_source": "built-in",
"account_pool_id": "ie.nl.booker",
"account_cd": 9000,
"target_instances": 2
},
"version": 2,
"updated_by": "admin",
"created_at": "2026-08-23T20:10:00",
"updated_at": "2026-08-23T20:15:00"
}
}
PUT /api/node-configurations/{entry_type}/{entry_id}/enableenable (boolean, 必填): true 为启用 (1),false 为停用 (0)。请求示例:
{
"enable": true
}
响应示例 (code: 0):
{
"code": 0,
"message": "Node configuration status toggled",
"data": {
"id": 101,
"enable": 1,
"version": 3,
"updated_by": "admin",
...
}
}
DELETE /api/node-configurations/{entry_type}/{entry_id}confirm_purge (boolean, 可选, 默认 false): 删除保护守卫。当当前角色的配置在数据库中仅剩最后 1 条时,若不传 confirm_purge=true 会拦截并返回 40000(提示需二次确认);有多条数据时可直接删除。请求示例:
DELETE /api/node-configurations/booker/101?confirm_purge=true
响应示例 (code: 0):
{
"code": 0,
"message": "Node configuration deleted successfully",
"data": true
}
GET /api/node-configurations/{entry_type}/{entry_id}/revisions响应示例 (code: 0):
{
"code": 0,
"message": "success",
"data": [
{
"id": 15,
"entry_type": "booker",
"entry_id": 101,
"version": 3,
"action": "enable",
"snapshot": { ... },
"updated_by": "admin",
"created_at": "2026-08-23T20:20:00"
},
{
"id": 14,
"entry_type": "booker",
"entry_id": 101,
"version": 2,
"action": "update",
"snapshot": { ... },
"updated_by": "admin",
"created_at": "2026-08-23T20:15:00"
},
{
"id": 13,
"entry_type": "booker",
"entry_id": 101,
"version": 1,
"action": "create",
"snapshot": { ... },
"updated_by": "admin",
"created_at": "2026-08-23T20:10:00"
}
]
}
POST /api/node-configurations/{entry_type}/{entry_id}/rollbackrevision_id (integer, 必填): 目标历史快照的 ID(来自 2.7 节)。请求示例:
{
"revision_id": 13
}
响应示例 (code: 0):
{
"code": 0,
"message": "Node configuration rolled back successfully",
"data": {
"id": 101,
"enable": 0,
"version": 4,
"updated_by": "admin",
...
}
}