L2TP切换接口 API 文档

接口概述

接口地址: /api/l2tp/switch
请求方法: POST
功能说明: 允许用户切换已分配端口的代理出口，支持设备原配置切换和指定地区两种模式
api接口地址 https://byjsgateway.vpsnb.net

认证参数

请求参数

基础参数（必填）

位置/网络参数（可选）

packet_loss和rtt 越低，出口当不满足要求的时就会自动原地区切换，如果需求是出口ip尽量不变动，这两个参数请不要传。

操作模式

模式1：保持上一次配置出口切换

触发条件: 仅传入 gateway_ip 和 l2tp_usernames 参数

如果上一次配置或者开通的时候没有指定地区，则本次切换依然是随机，如果上一次配置指定了地区，则本地切换只在该地区。

模式2：指定地区切换

触发条件: 传入任意一个地区参数

请求示例

示例1：保持上一次配置出口切换（网关是IP地址）

{
  "orderId": "test_user",
  "timestamp": "1750173159",
  "sign": "abc123def456",
  "gateway_ip": "192.168.1.100",
  "l2tp_usernames": ["user001", "user002"]
}

示例2：保持上一次配置出口切换（网关是域名）

{
  "orderId": "test_user",
  "timestamp": "1750173159",
  "sign": "abc123def456",
  "gateway_ip": "gateway1.example.com",
  "l2tp_usernames": ["user001", "user002"]
}

示例3：指定地区切换

{
  "orderId": "test_user",
  "timestamp": "1750173159", 
  "sign": "abc123def456",
  "gateway_ip": "192.168.1.100",
  "l2tp_usernames": ["user001"],
  "province": "广东",
  "city": "深圳",
  "isp": "电信",
  "packet_loss": 10,
  "rtt": 100
}

响应格式

成功响应

{
  "code": 0,
  "msg": "所有L2TP账户切换成功: 共2个账户",
  "data": {
    "gateway": "gateway1.example.com",
    "gateway_ip": "192.168.1.100",
    "total_l2tp_accounts": 2,
    "successful_l2tp_accounts": 2,
    "failed_l2tp_accounts": 0,
    "mode": "device_switch",
    "results": [
      {
        "l2tp_username": "user001",
        "success": true,
        "message": "代理重新配置成功"
      },
      {
        "l2tp_username": "user002",
        "success": true,
        "message": "代理重新配置成功"
      }
    ]
  }
}

部分成功响应

{
  "code": 206,
  "msg": "部分L2TP账户切换成功: 成功1个，失败1个",
  "data": {
    "gateway_ip": "192.168.1.100",
    "total_l2tp_accounts": 2,
    "successful_l2tp_accounts": 1,
    "failed_l2tp_accounts": 1,
    "mode": "location_config",
    "results": [
      {
        "l2tp_username": "user001",
        "success": true,
        "message": "L2TP配置更新成功"
      },
      {
        "l2tp_username": "user002",
        "success": false,
        "message": "网关API请求失败: HTTP 500"
      }
    ]
  }
}

错误响应

{
  "code": 400,
  "msg": "以下L2TP用户名无效: L2TP用户名 user001 不存在或未分配给当前用户; L2TP用户名 user002 已过期"
}

响应字段说明

错误码说明

使用场景

1. 保持上一次配置出口切换: 用户需要更换使用代理的出口【如果上一次配置或者开通的时候没有指定地区，则本次切换依然是随机，如果上一次配置指定了地区，则本地切换只在该地区】
2. 指定地区切换: 用户需要切换代理的地理位置或网络特性时
3. 批量操作: 同时切换同一个网关下多个账户的配置

注意事项

1. 支持批量操作，但建议单次请求不超过10个账户