跳转到正文
使用文档
简
English简体中文繁體中文
工作空间
指南API 参考API v1
OpenAPI 参考 · 简体中文下载 OpenAPI ↓

请求使用你的 API 密钥并发送至所选服务器。购买和续费请求会从钱包扣款。

v1.1.0
OpenAPI 3.1.0

客户 API

通过自己的应用管理代理、流量和账单。

使用工作空间 API 密钥作为 Bearer 令牌发送请求。每个接口都列出了所需权限。确认购买或续费后，系统会从钱包扣款。

从指南开始 · 了解重试规则

服务器:https://portal.migoip.com

工作空间 API

客户端库
Shell Curl

账户

​
账户 操作

查看工作空间钱包余额

​

所需权限: wallet:read.

返回与门户一致的钱包数据。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/balance
curl https://portal.migoip.com/api/customer/v1/balance \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "tenant_id": "string",
  "balance_fen": "string"
}

钱包余额

确认已认证的工作空间

​

所需权限: account:read.

需要 account:read。根据 API 密钥返回所属工作空间、创建人、基础访问权限和显式权限列表（旧版密钥为 null）。身份由密钥确定，响应省略秘密值。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/account
curl https://portal.migoip.com/api/customer/v1/account \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "tenant_id": "string",
  "user_id": "string",
  "permission": "read",
  "scopes": [
    "account:read"
  ]
}

确认已认证的工作空间

静态代理价格

​
静态代理价格 操作

查看工作空间可用价格

​

所需权限: catalog:read.

使用与门户一致的价格解析规则：产品类型 → 国家或地区 → 位置，返回精确的周期与价格。内部价格来源信息保持私有。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/catalog
curl https://portal.migoip.com/api/customer/v1/catalog \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "location_kind": "city",
      "id": "string",
      "product": "static_residential",
      "country": "string",
      "location_id": "string",
      "location_name": "string",
      "location_subdivision": "string",
      "period": "string",
      "days": 1,
      "base_fen": "string",
      "optimization_fen": "string",
      "optimization_enabled": true,
      "optimization_supported": true,
      "supported_protocols": [],
      "supply_mode": "string"
    }
  ],
  "total": 0
}

可用价格列表

创建购买报价

​

所需权限: orders:write.

需要写入访问权限。按请求数量与协议固定有效单价和总价。响应仅包含客户所需的报价数据，模拟场景及内部供应信息保持私有。未知请求字段（包括 tenant_id 和 scenario）返回 422。price_id 必须对应具体位置的可购买项。国家或产品级规则以及仅含国家的合成 ID 返回 422 LOCATION_REQUIRED。

请求体·

必填
application/json

包含 tenant_id 和 scenario 在内的未知字段会返回 422。

  • price_id
    类型: string
    最小长度:  
    1
    最大长度:  
    128
    必填
  • quantity
    类型: integer
    最小值:  
    1
    最大值:  
    20
    必填

    整数。

  • access_optimized
    类型: boolean

    选择按 IP 独立计价的接入优化附加服务。当前方案必须支持此服务。

  • auto_renew_enabled
    类型: boolean

    为本次购买启用钱包自动续费，调度任务执行续费时才会扣款。

  • coupon_code
    类型: string
    最小长度:  
    3
    最大长度:  
    64

    每次购买可选一张百分比优惠券。服务器会去除代码首尾空白并转为大写。

  • note
    类型: string
    最大长度:  
    200

    可选的实例纯文本备注，最多 200 个 Unicode 字符。购买多个 IP 时，每个实例会附加其固定订单项序号。

  • protocol
    枚举

    首选连接格式。

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/quotes
curl https://portal.migoip.com/api/customer/v1/quotes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "price_id": "",
  "quantity": 1,
  "protocol": "http",
  "access_optimized": false,
  "note": "",
  "auto_renew_enabled": false,
  "coupon_code": ""
}'

{
  "purchase_kind": "purchase",
  "service_id": "string",
  "service_expires_at": "2026-10-26T05:45:59.177Z",
  "id": "string",
  "tenant_id": "string",
  "price_id": "string",
  "product": "static_residential",
  "country": "string",
  "location_id": "string",
  "location_name": "string",
  "location_subdivision": "string",
  "period": "string",
  "days": 1,
  "quantity": 1,
  "protocol": "http",
  "access_optimized": true,
  "optimization_fen": "string",
  "unit_fen": "string",
  "subtotal_fen": "string",
  "discount_fen": "string",
  "total_fen": "string",
  "coupon": {
    "id": "string",
    "code": "string",
    "name": "string",
    "discount_bps": 1
  },
  "created_at": "2026-10-26T05:45:59.177Z",
  "expires_at": "2026-10-26T05:45:59.177Z",
  "note": "string",
  "auto_renew_enabled": true
}

已固定的报价

订单

​
订单 操作

确认报价并创建订单

​

所需权限: orders:write, wallet:spend.

需要写入访问权限。在同一事务中扣除钱包余额并创建一个开通任务。必须提供 Idempotency-Key；相同请求重试返回原订单和任务，钱包仅扣款一次，并发重复请求合并为同一订单。缺少具体位置的报价在扣款前返回 422 LOCATION_REQUIRED。

请求头

  • Idempotency-Key
    类型: string
    最小长度:  
    8
    最大长度:  
    128
    必填

    重复提交完全相同的请求会返回原结果，且只扣款一次。请求正文发生变化会返回冲突。

请求体

必填
application/json
  • quote_id
    类型: string
    最小长度:  
    1
    最大长度:  
    128
    必填

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/orders
curl https://portal.migoip.com/api/customer/v1/orders \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "quote_id": ""
}'

{
  "order": {
    "purchase_kind": "purchase",
    "service_id": "string",
    "id": "string",
    "tenant_id": "string",
    "quote_id": "string",
    "subtotal_fen": "string",
    "discount_fen": "string",
    "total_fen": "string",
    "coupon": {
      "id": "string",
      "code": "string",
      "name": "string",
      "discount_bps": 1
    },
    "status": "provisioning",
    "created_at": "2026-10-26T05:45:59.177Z"
  },
  "operations": [
    {
      "id": "string",
      "order_id": "string",
      "kind": "string",
      "state": "queued",
      "error_code": "string",
      "attempt_count": 0,
      "created_at": "2026-10-26T05:45:59.177Z",
      "updated_at": "2026-10-26T05:45:59.177Z"
    }
  ]
}

已接受或重复返回的订单及其排队任务

列出工作空间订单

​

所需权限: orders:read.

按时间倒序返回，分页大小受限。

查询参数

  • page
    类型: integer
    最小值:  
    1
    最大值:  
    100000

    整数。

  • page_size
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/orders
curl 'https://portal.migoip.com/api/customer/v1/orders?page=1&page_size=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "purchase_kind": "purchase",
      "service_id": "string",
      "id": "string",
      "tenant_id": "string",
      "quote_id": "string",
      "subtotal_fen": "string",
      "discount_fen": "string",
      "total_fen": "string",
      "coupon": {
        "id": "string",
        "code": "string",
        "name": "string",
        "discount_bps": 1
      },
      "status": "provisioning",
      "created_at": "2026-10-26T05:45:59.177Z"
    }
  ],
  "total": 0,
  "page": 1,
  "page_size": 1
}

订单分页结果

查看订单详情与处理进度

​

所需权限: orders:read.

其他工作空间或未知的订单 ID 返回 404。仅可查看当前工作空间的记录。

路径参数

  • id
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/orders/{id}
curl 'https://portal.migoip.com/api/customer/v1/orders/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "order": {
    "purchase_kind": "purchase",
    "service_id": "string",
    "id": "string",
    "tenant_id": "string",
    "quote_id": "string",
    "subtotal_fen": "string",
    "discount_fen": "string",
    "total_fen": "string",
    "coupon": {
      "id": "string",
      "code": "string",
      "name": "string",
      "discount_bps": 1
    },
    "status": "provisioning",
    "created_at": "2026-10-26T05:45:59.177Z"
  },
  "quote": {
    "purchase_kind": "purchase",
    "service_id": "string",
    "service_expires_at": "2026-10-26T05:45:59.177Z",
    "id": "string",
    "tenant_id": "string",
    "price_id": "string",
    "product": "static_residential",
    "country": "string",
    "location_id": "string",
    "location_name": "string",
    "location_subdivision": "string",
    "period": "string",
    "days": 1,
    "quantity": 1,
    "protocol": "http",
    "access_optimized": true,
    "optimization_fen": "string",
    "unit_fen": "string",
    "subtotal_fen": "string",
    "discount_fen": "string",
    "total_fen": "string",
    "coupon": {
      "id": "string",
      "code": "string",
      "name": "string",
      "discount_bps": 1
    },
    "created_at": "2026-10-26T05:45:59.177Z",
    "expires_at": "2026-10-26T05:45:59.177Z",
    "note": "string",
    "auto_renew_enabled": true
  },
  "items": [
    {
      "id": "string",
      "ordinal": 1,
      "amount_fen": "string"
    }
  ],
  "operations": [
    {
      "id": "string",
      "order_id": "string",
      "kind": "string",
      "state": "queued",
      "error_code": "string",
      "attempt_count": 0,
      "created_at": "2026-10-26T05:45:59.177Z",
      "updated_at": "2026-10-26T05:45:59.177Z"
    }
  ],
  "services": [
    {
      "id": "string",
      "order_id": "string",
      "operation_id": "string",
      "ip": "string",
      "hostname": "string",
      "product": "static_residential",
      "country": "string",
      "location_id": "string",
      "location_name": "string",
      "location_subdivision": "string",
      "refunded_at": "2026-10-26T05:45:59.177Z",
      "protocol": "http",
      "activated_at": "2026-10-26T05:45:59.177Z",
      "expires_at": "2026-10-26T05:45:59.177Z",
      "term_state": "active",
      "connection_available": true,
      "direct_connection_available": true,
      "optimized_connection_available": true,
      "supported_protocols": [],
      "renewable": true,
      "simulated": true,
      "provenance": "provider",
      "optimization": {
        "selected": true,
        "state": "pending",
        "bandwidth": {
          "upload": {
            "bytes_per_second": "string",
            "burst_bytes": "string"
          },
          "download": {
            "bytes_per_second": "string",
            "burst_bytes": "string"
          }
        }
      },
      "lifecycle": {
        "supported": true,
        "renewal_supported": true,
        "revoke_supported": true,
        "access_state": "string",
        "expires_at": "2026-10-26T05:45:59.177Z",
        "can_renew": true,
        "renewal_block_reason": "string",
        "latest_renewal": {
          "id": "string",
          "service_id": "string",
          "quote_id": "string",
          "branch": "extend",
          "amount_fen": "string",
          "state": "queued",
          "error_code": "string",
          "term_start": null,
          "expires_at": null,
          "created_at": "2026-10-26T05:45:59.177Z",
          "updated_at": "2026-10-26T05:45:59.177Z"
        },
        "prices": [
          {
            "id": "string",
            "product": "static_residential",
            "country": "string",
            "location_id": "string",
            "location_name": "string",
            "location_subdivision": "string",
            "period": "string",
            "days": 1,
            "base_fen": "string"
          }
        ]
      },
      "note": "string",
      "settings_version": 1,
      "auto_renew_enabled": true,
      "auto_renew_period": "string",
      "auto_renew_state": "off",
      "auto_renew_next_attempt_at": "2026-10-26T05:45:59.177Z"
    }
  ]
}

订单详情

查询开通任务状态

​

所需权限: orders:read.

仅返回任务 ID、类型、状态、尝试次数和时间戳。内部标识、租约、模式和原始错误码保持私有。内部处理失败统一显示为 OPERATION_NEEDS_ATTENTION。

路径参数

  • id
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/operations/{id}
curl 'https://portal.migoip.com/api/customer/v1/operations/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "string",
  "order_id": "string",
  "kind": "string",
  "state": "queued",
  "error_code": "string",
  "attempt_count": 0,
  "created_at": "2026-10-26T05:45:59.177Z",
  "updated_at": "2026-10-26T05:45:59.177Z"
}

任务状态

查看统一订单历史

​

所需权限: orders:read.

需要 orders:read。包含静态订单、优化升级、续费和动态流量购买。

查询参数

  • page
    类型: integer
    最小值:  
    1
    最大值:  
    100000

    整数。

  • page_size
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

  • q
    类型: string
  • status
    类型: string
  • product
    类型: "static_residential" or "static_datacenter" or "dynamic_residential"枚举
  • from
    类型: string

    UTC 起始时间，包含边界，格式为 RFC3339 或 YYYY-MM-DD。

  • to
    类型: string

    UTC 结束时间，不含边界，格式为 RFC3339 或 YYYY-MM-DD，必须晚于 from。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/order-history
curl 'https://portal.migoip.com/api/customer/v1/order-history?page=1&page_size=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "kind": "static",
      "purchase_kind": "purchase",
      "service_id": "string",
      "product": "static_residential",
      "country": "string",
      "location_name": "string",
      "period": "string",
      "days": 0,
      "quantity": 0,
      "traffic_bytes": "string",
      "total_fen": "string",
      "status": "provisioning",
      "created_at": "2026-10-26T05:45:59.177Z"
    }
  ],
  "total": 0,
  "page": 1,
  "page_size": 1
}

查看统一订单历史

静态代理

​
静态代理 操作

列出静态代理及续费、到期状态

​

所需权限: proxies:read.

支持有限分页、可选产品与有效期状态筛选、文字搜索（包含备注）和精确 IP 筛选。每条记录包含生命周期规则与实例设置（备注、并发版本和自动续费状态）。缺少设置的旧记录返回空备注、版本 1 和关闭的自动续费状态。

查询参数

  • page
    类型: integer
    最小值:  
    1
    最大值:  
    100000

    整数。

  • page_size
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

  • product
    枚举
  • term_state
    枚举

    根据已记录日期判断；实际连接截止状态以实时服务状态为准

  • q
    类型: string
    最大长度:  
    128

    按原文进行不区分大小写的搜索，包含实例备注

  • ips
    类型: string
    最大长度:  
    4096

    逗号分隔的标准化 IPv4/IPv6 地址，逐项精确匹配

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/proxies
curl 'https://portal.migoip.com/api/customer/v1/proxies?page=1&page_size=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "id": "string",
      "order_id": "string",
      "operation_id": "string",
      "ip": "string",
      "hostname": "string",
      "product": "static_residential",
      "country": "string",
      "location_id": "string",
      "location_name": "string",
      "location_subdivision": "string",
      "refunded_at": "2026-10-26T05:45:59.177Z",
      "protocol": "http",
      "activated_at": "2026-10-26T05:45:59.177Z",
      "expires_at": "2026-10-26T05:45:59.177Z",
      "term_state": "active",
      "connection_available": true,
      "direct_connection_available": true,
      "optimized_connection_available": true,
      "supported_protocols": [],
      "renewable": true,
      "simulated": true,
      "provenance": "provider",
      "optimization": {
        "selected": true,
        "state": "pending",
        "bandwidth": {
          "upload": {
            "bytes_per_second": "string",
            "burst_bytes": "string"
          },
          "download": {
            "bytes_per_second": "string",
            "burst_bytes": "string"
          }
        }
      },
      "lifecycle": {
        "supported": true,
        "renewal_supported": true,
        "revoke_supported": true,
        "access_state": "string",
        "expires_at": "2026-10-26T05:45:59.177Z",
        "can_renew": true,
        "renewal_block_reason": "string",
        "latest_renewal": {
          "id": "string",
          "service_id": "string",
          "quote_id": "string",
          "branch": "extend",
          "amount_fen": "string",
          "state": "queued",
          "error_code": "string",
          "term_start": null,
          "expires_at": null,
          "created_at": "2026-10-26T05:45:59.177Z",
          "updated_at": "2026-10-26T05:45:59.177Z"
        },
        "prices": [
          {
            "id": "string",
            "product": "static_residential",
            "country": "string",
            "location_id": "string",
            "location_name": "string",
            "location_subdivision": "string",
            "period": "string",
            "days": 1,
            "base_fen": "string"
          }
        ]
      },
      "note": "string",
      "settings_version": 1,
      "auto_renew_enabled": true,
      "auto_renew_period": "string",
      "auto_renew_state": "off",
      "auto_renew_next_attempt_at": "2026-10-26T05:45:59.177Z"
    }
  ],
  "total": 0,
  "page": 1,
  "page_size": 1
}

实例分页结果

导出当前可用连接的纯文本

​

所需权限: proxies:read, credentials:read.

返回 text/plain，每行是一个以 LF 结尾的 host:port:username:password，使用明确指定的单一 protocol，最多 page_size 行。IPv6 主机使用方括号。仅导出当前可用连接；已到期或没有可用凭据的实例跳过。没有可导出连接时返回 200 和空文本正文。读取失败会使整个请求失败。分页信息位于响应头。请勿记录导出值。access_mode 默认 preferred；明确选择 direct 或 optimized 时仅使用对应路由。ips 精确筛选与产品、有效期和文字筛选同时生效。

查询参数

  • access_mode
    类型: "preferred" or "direct" or "optimized"枚举

    明确选择连接路由；对应路由不可用时跳过该实例

  • ips
    类型: string

    逗号分隔的精确 IPv4/IPv6 地址，标准化后最多 100 个不同地址。空项、无效地址和重复的 ips 参数均被拒绝。

  • protocol
    枚举
    必填

    HTTP 对应已保存的 HTTPS/CONNECT 连接格式

  • page
    类型: integer
    最小值:  
    1
    最大值:  
    100000

    整数。

  • page_size
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

  • product
    枚举
  • term_state
    枚举
  • q
    类型: string
    最大长度:  
    128

响应

  • text/plain
  • application/json
Request Example for get/api/customer/v1/proxies/export
curl 'https://portal.migoip.com/api/customer/v1/proxies/export?access_mode=preferred&protocol=http&page=1&page_size=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

203.0.113.10:8443:acme-user:secret

一页数量受限的纯文本连接，每行一条。此页没有符合协议要求的可用连接时，返回空正文。

查看实例及获准访问的连接凭据

​

所需权限: proxies:read, credentials:read.

返回实例及获准访问的各协议连接数据。到期实例的可用连接为空。其他工作空间或未知的 ID 返回 404。

路径参数

  • id
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/proxies/{id}
curl 'https://portal.migoip.com/api/customer/v1/proxies/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "service": {
    "id": "string",
    "order_id": "string",
    "operation_id": "string",
    "ip": "string",
    "hostname": "string",
    "product": "static_residential",
    "country": "string",
    "location_id": "string",
    "location_name": "string",
    "location_subdivision": "string",
    "refunded_at": "2026-10-26T05:45:59.177Z",
    "protocol": "http",
    "activated_at": "2026-10-26T05:45:59.177Z",
    "expires_at": "2026-10-26T05:45:59.177Z",
    "term_state": "active",
    "connection_available": true,
    "direct_connection_available": true,
    "optimized_connection_available": true,
    "supported_protocols": [],
    "renewable": true,
    "simulated": true,
    "provenance": "provider",
    "optimization": {
      "selected": true,
      "state": "pending",
      "bandwidth": {
        "upload": {
          "bytes_per_second": "string",
          "burst_bytes": "string"
        },
        "download": {
          "bytes_per_second": "string",
          "burst_bytes": "string"
        }
      }
    },
    "lifecycle": {
      "supported": true,
      "renewal_supported": true,
      "revoke_supported": true,
      "access_state": "string",
      "expires_at": "2026-10-26T05:45:59.177Z",
      "can_renew": true,
      "renewal_block_reason": "string",
      "latest_renewal": {
        "id": "string",
        "service_id": "string",
        "quote_id": "string",
        "branch": "extend",
        "amount_fen": "string",
        "state": "queued",
        "error_code": "string",
        "term_start": null,
        "expires_at": null,
        "created_at": "2026-10-26T05:45:59.177Z",
        "updated_at": "2026-10-26T05:45:59.177Z"
      },
      "prices": [
        {
          "id": "string",
          "product": "static_residential",
          "country": "string",
          "location_id": "string",
          "location_name": "string",
          "location_subdivision": "string",
          "period": "string",
          "days": 1,
          "base_fen": "string"
        }
      ]
    },
    "note": "string",
    "settings_version": 1,
    "auto_renew_enabled": true,
    "auto_renew_period": "string",
    "auto_renew_state": "off",
    "auto_renew_next_attempt_at": "2026-10-26T05:45:59.177Z"
  },
  "connections": [
    {
      "protocol": "http",
      "host": "string",
      "port": 1,
      "username": "string",
      "password": "string",
      "simulated": true
    }
  ],
  "direct_connections": [
    {
      "protocol": "http",
      "host": "string",
      "port": 1,
      "username": "string",
      "password": "string",
      "simulated": true
    }
  ],
  "optimized_connections": [
    {
      "protocol": "http",
      "host": "string",
      "port": 1,
      "username": "string",
      "password": "string",
      "simulated": true
    }
  ]
}

实例详情

更新实例备注与自动续费设置

​

所需权限: proxies:write.

需要写入访问权限。提交预期版本及可选的备注或自动续费设置，以乐观并发控制更新。省略的字段保持原值。备注最多 200 个 Unicode 字符。开启自动续费要求工作空间已验证，实例处于活动状态、尚未到期、未退款、支持续费且保留原购买周期。关闭自动续费或仅修改备注可独立执行。开启设置后，实际扣款由调度任务执行，届时工作空间仍需有效且已验证，授权成员关系仍需有效。版本过旧返回 409，其他工作空间或未知的 ID 返回 404。

路径参数

  • id
    类型: string
    必填

请求体·

必填
application/json

使用乐观并发控制更新实例设置。省略的 note 或 auto_renew_enabled 保持原值；过期的 expected_version 会返回冲突。

  • expected_version
    类型: integer
    最小值:  
    1
    必填

    上次读取的实例 settings_version。

  • auto_renew_enabled
    类型: boolean

    新的自动续费选项，调度任务执行续费时才会扣款。

  • note
    类型: string
    最大长度:  
    200

    新的备注内容。

响应

  • application/json
  • application/json
Request Example for patch/api/customer/v1/proxies/{id}/settings
curl 'https://portal.migoip.com/api/customer/v1/proxies/{id}/settings' \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "expected_version": 1,
  "note": "",
  "auto_renew_enabled": true
}'

{
  "service": {
    "id": "string",
    "order_id": "string",
    "operation_id": "string",
    "ip": "string",
    "hostname": "string",
    "product": "static_residential",
    "country": "string",
    "location_id": "string",
    "location_name": "string",
    "location_subdivision": "string",
    "refunded_at": "2026-10-26T05:45:59.177Z",
    "protocol": "http",
    "activated_at": "2026-10-26T05:45:59.177Z",
    "expires_at": "2026-10-26T05:45:59.177Z",
    "term_state": "active",
    "connection_available": true,
    "direct_connection_available": true,
    "optimized_connection_available": true,
    "supported_protocols": [],
    "renewable": true,
    "simulated": true,
    "provenance": "provider",
    "optimization": {
      "selected": true,
      "state": "pending",
      "bandwidth": {
        "upload": {
          "bytes_per_second": "string",
          "burst_bytes": "string"
        },
        "download": {
          "bytes_per_second": "string",
          "burst_bytes": "string"
        }
      }
    },
    "lifecycle": {
      "supported": true,
      "renewal_supported": true,
      "revoke_supported": true,
      "access_state": "string",
      "expires_at": "2026-10-26T05:45:59.177Z",
      "can_renew": true,
      "renewal_block_reason": "string",
      "latest_renewal": {
        "id": "string",
        "service_id": "string",
        "quote_id": "string",
        "branch": "extend",
        "amount_fen": "string",
        "state": "queued",
        "error_code": "string",
        "term_start": null,
        "expires_at": null,
        "created_at": "2026-10-26T05:45:59.177Z",
        "updated_at": "2026-10-26T05:45:59.177Z"
      },
      "prices": [
        {
          "id": "string",
          "product": "static_residential",
          "country": "string",
          "location_id": "string",
          "location_name": "string",
          "location_subdivision": "string",
          "period": "string",
          "days": 1,
          "base_fen": "string"
        }
      ]
    },
    "note": "string",
    "settings_version": 1,
    "auto_renew_enabled": true,
    "auto_renew_period": "string",
    "auto_renew_state": "off",
    "auto_renew_next_attempt_at": "2026-10-26T05:45:59.177Z"
  },
  "connections": [
    {
      "protocol": "http",
      "host": "string",
      "port": 1,
      "username": "string",
      "password": "string",
      "simulated": true
    }
  ],
  "direct_connections": [
    {
      "protocol": "http",
      "host": "string",
      "port": 1,
      "username": "string",
      "password": "string",
      "simulated": true
    }
  ],
  "optimized_connections": [
    {
      "protocol": "http",
      "host": "string",
      "port": 1,
      "username": "string",
      "password": "string",
      "simulated": true
    }
  ]
}

更新后的实例详情；设置更新响应省略连接凭据

创建续费报价

​

所需权限: orders:write.

需要写入访问权限。报价固定服务修订版本、有效价格版本及从已记录到期时间延长的精确计算结果。此操作只读取数据。实例已到期、不支持续费或属于手动导入且不可续费时，返回对应规则错误。

路径参数

  • id
    类型: string
    必填

请求体

必填
application/json
  • price_id
    类型: string
    最小长度:  
    1
    最大长度:  
    128
    必填

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/proxies/{id}/renewal-quotes
curl 'https://portal.migoip.com/api/customer/v1/proxies/{id}/renewal-quotes' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "price_id": ""
}'

{
  "id": "string",
  "service_id": "string",
  "branch": "extend",
  "price_id": "string",
  "product": "static_residential",
  "country": "string",
  "location_id": "string",
  "location_name": "string",
  "location_subdivision": "string",
  "period": "string",
  "days": 1,
  "optimization_selected": true,
  "base_fen": "string",
  "optimization_fen": "string",
  "total_fen": "string",
  "old_expires_at": "2026-10-26T05:45:59.177Z",
  "proposed_expires_at": null,
  "created_at": "2026-10-26T05:45:59.177Z",
  "expires_at": "2026-10-26T05:45:59.177Z"
}

续费报价快照

确认并支付续费

​

所需权限: orders:write, wallet:spend.

需要写入访问权限。必须提供 Idempotency-Key，确保只扣款一次。钱包扣款与续费记录在同一事务中提交，报价绑定付款操作人。相同请求重试返回原续费记录；已使用的报价或变更后的请求内容触发冲突并终止扣款。实际续费由后台任务处理。

路径参数

  • id
    类型: string
    必填

请求头

  • Idempotency-Key
    类型: string
    最小长度:  
    8
    最大长度:  
    128
    必填

    重复提交完全相同的请求会返回原结果，且只扣款一次。请求正文发生变化会返回冲突。

请求体

必填
application/json
  • quote_id
    类型: string
    最小长度:  
    1
    最大长度:  
    128
    必填

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/proxies/{id}/renewals
curl 'https://portal.migoip.com/api/customer/v1/proxies/{id}/renewals' \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "quote_id": ""
}'

{
  "renewal": {
    "id": "string",
    "service_id": "string",
    "quote_id": "string",
    "branch": "extend",
    "amount_fen": "string",
    "state": "queued",
    "error_code": "string",
    "term_start": null,
    "expires_at": null,
    "created_at": "2026-10-26T05:45:59.177Z",
    "updated_at": "2026-10-26T05:45:59.177Z"
  }
}

已接受或重复返回的续费

查询续费状态

​

所需权限: orders:read.

仅可查看密钥所属工作空间的续费。

路径参数

  • id
    类型: string
    必填
  • renewal
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/proxies/{id}/renewals/{renewal}
curl 'https://portal.migoip.com/api/customer/v1/proxies/{id}/renewals/{renewal}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "renewal": {
    "id": "string",
    "service_id": "string",
    "quote_id": "string",
    "branch": "extend",
    "amount_fen": "string",
    "state": "queued",
    "error_code": "string",
    "term_start": null,
    "expires_at": null,
    "created_at": "2026-10-26T05:45:59.177Z",
    "updated_at": "2026-10-26T05:45:59.177Z"
  }
}

续费状态

获取现有静态 IP 的优化升级报价

​

所需权限: orders:write.

需要写入访问权限及 orders:write。通过 POST /orders 确认。现有服务的到期时间保持不变。升级暂不支持优惠券，使用时返回 COUPON_UNAVAILABLE。未知请求字段被拒绝。

路径参数

  • id
    类型: string
    必填

请求体

application/json
  • coupon_code
    类型: string

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/proxies/{id}/optimization-quotes
curl 'https://portal.migoip.com/api/customer/v1/proxies/{id}/optimization-quotes' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "coupon_code": ""
}'

{
  "purchase_kind": "purchase",
  "service_id": "string",
  "service_expires_at": "2026-10-26T05:45:59.177Z",
  "id": "string",
  "tenant_id": "string",
  "price_id": "string",
  "product": "static_residential",
  "country": "string",
  "location_id": "string",
  "location_name": "string",
  "location_subdivision": "string",
  "period": "string",
  "days": 1,
  "quantity": 1,
  "protocol": "http",
  "access_optimized": true,
  "optimization_fen": "string",
  "unit_fen": "string",
  "subtotal_fen": "string",
  "discount_fen": "string",
  "total_fen": "string",
  "coupon": {
    "id": "string",
    "code": "string",
    "name": "string",
    "discount_bps": 1
  },
  "created_at": "2026-10-26T05:45:59.177Z",
  "expires_at": "2026-10-26T05:45:59.177Z",
  "note": "string",
  "auto_renew_enabled": true
}

获取现有静态 IP 的优化升级报价

创建批量续费报价

​

所需权限: orders:write.

需要写入访问权限及 orders:write。接受 1–100 个不同的自有服务 ID 及其精确续费价格 ID。任一项目不符合条件时，整份报价被拒绝。

请求体·

必填
application/json
  • items
    类型: array of object 1…100
    必填
    属性：2

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/proxies/batch-renewal-quotes
curl https://portal.migoip.com/api/customer/v1/proxies/batch-renewal-quotes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "items": [
    {
      "service_id": "",
      "price_id": ""
    }
  ]
}'

{
  "id": "string",
  "tenant_id": "string",
  "actor_id": "string",
  "total_fen": "string",
  "created_at": "2026-10-26T05:45:59.177Z",
  "expires_at": "2026-10-26T05:45:59.177Z",
  "quotes": [
    {
      "id": "string",
      "service_id": "string",
      "branch": "extend",
      "price_id": "string",
      "product": "static_residential",
      "country": "string",
      "location_id": "string",
      "location_name": "string",
      "location_subdivision": "string",
      "period": "string",
      "days": 1,
      "optimization_selected": true,
      "base_fen": "string",
      "optimization_fen": "string",
      "total_fen": "string",
      "old_expires_at": "2026-10-26T05:45:59.177Z",
      "proposed_expires_at": null,
      "created_at": "2026-10-26T05:45:59.177Z",
      "expires_at": "2026-10-26T05:45:59.177Z"
    }
  ]
}

创建批量续费报价

确认批量续费

​

所需权限: orders:write, wallet:spend.

需要写入访问权限及 orders:write、wallet:spend。在单一事务中完成钱包扣款，随后每个 IP 独立处理续费结果。重试相同请求时复用 Idempotency-Key。

请求头

  • Idempotency-Key
    类型: string
    最小长度:  
    8
    最大长度:  
    128
    必填

    重复提交完全相同的请求会返回原结果，且只扣款一次。请求正文发生变化会返回冲突。

请求体

必填
application/json
  • quote_id
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/proxies/batch-renewals
curl https://portal.migoip.com/api/customer/v1/proxies/batch-renewals \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "quote_id": ""
}'

{
  "id": "string",
  "tenant_id": "string",
  "quote_id": "string",
  "total_fen": "string",
  "created_at": "2026-10-26T05:45:59.177Z",
  "renewals": [
    {
      "id": "string",
      "service_id": "string",
      "quote_id": "string",
      "branch": "extend",
      "amount_fen": "string",
      "state": "queued",
      "error_code": "string",
      "term_start": null,
      "expires_at": null,
      "created_at": "2026-10-26T05:45:59.177Z",
      "updated_at": "2026-10-26T05:45:59.177Z"
    }
  ]
}

确认批量续费

查看批量续费

​

所需权限: orders:read.

需要 orders:read。其他工作空间或未知的 ID 返回 404。内部失败统一返回 OPERATION_NEEDS_ATTENTION。

路径参数

  • batch
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/proxies/batch-renewals/{batch}
curl 'https://portal.migoip.com/api/customer/v1/proxies/batch-renewals/{batch}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "string",
  "tenant_id": "string",
  "quote_id": "string",
  "total_fen": "string",
  "created_at": "2026-10-26T05:45:59.177Z",
  "renewals": [
    {
      "id": "string",
      "service_id": "string",
      "quote_id": "string",
      "branch": "extend",
      "amount_fen": "string",
      "state": "queued",
      "error_code": "string",
      "term_start": null,
      "expires_at": null,
      "created_at": "2026-10-26T05:45:59.177Z",
      "updated_at": "2026-10-26T05:45:59.177Z"
    }
  ]
}

查看批量续费

动态代理

​
动态代理 操作

查看动态代理配置与流量包

​

所需权限: dynamic:read.

需要 dynamic:read。国家或地区、协议与粘性会话时长依据实际配置。已停用产品的可销售流量包为空。按 kind 选择 standard 或 optimization。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/dynamic/config
curl https://portal.migoip.com/api/customer/v1/dynamic/config \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "tenant_id": "string",
  "ready": true,
  "ready_reason": "string",
  "capabilities": {
    "usage_analytics": {
      "breakdowns": [
        "overview"
      ],
      "intervals": [
        "hour"
      ],
      "max_window_days": 0,
      "bucket_timezone": "string",
      "balance_reporting": true
    },
    "supported_countries": [
      "string"
    ],
    "protocols": [
      "http"
    ],
    "modes": [
      "rotating"
    ],
    "sticky_session_minutes": [
      1
    ],
    "sticky_default_minutes": 0
  },
  "packs": [
    {
      "id": "string",
      "label": "string",
      "kind": "standard",
      "bytes": "string",
      "price_fen": "string",
      "version": 1
    }
  ]
}

查看动态代理配置与流量包

查看标准与优化流量余额

​

所需权限: dynamic:read.

需要 dynamic:read。标准流量的总量、已用量及剩余量来自 Residential/Usage 的只读快照。此查询保持钱包及流量额度不变。按时间范围统计的分析数据用于趋势，累计计费用量以余额快照为准。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/dynamic/account
curl https://portal.migoip.com/api/customer/v1/dynamic/account \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "tenant_id": "string",
  "usage_status": "reported",
  "purchased_bytes": "string",
  "adjustment_bytes": "string",
  "balance_status": "reported",
  "balance_source": "local",
  "balance_observed_at": "2026-10-26T05:45:59.177Z",
  "total_bytes": "string",
  "used_bytes": "string",
  "remaining_bytes": "string",
  "status": "none",
  "last_usage_at": "2026-10-26T05:45:59.177Z",
  "optimization": {
    "purchased_bytes": "string",
    "adjustment_bytes": "string",
    "consumed_bytes": "string",
    "reserved_bytes": "string",
    "uncertain_bytes": "string",
    "available_bytes": "string",
    "remaining_bytes": "string",
    "usable_bytes": "string",
    "pending_node_bytes": "string",
    "status": "none",
    "availability_reason": "none"
  }
}

查看标准与优化流量余额

查看指定时间范围的动态流量分析

​

所需权限: dynamic:read.

需要 dynamic:read。默认查询截至当前 UTC 分钟的最近 24 小时。最大范围为 30 天，或配置允许的更小范围。缺少地理归属时标记为未知国家或地区。报告冷却期间返回 429 DYNAMIC_USAGE_RATE_LIMITED 和 Retry-After。

查询参数

  • from
    类型: string格式: date-time

    起始时间，包含边界。

  • to
    类型: string格式: date-time

    结束时间，不含边界，最多允许比当前时间晚一分钟。

  • breakdown
    枚举
    值
    overviewtrendcountrieshosts
  • interval
    枚举
  • limit
    类型: integer
    最小值:  
    1
    最大值:  
    100

    目标主机排行榜的最大行数。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/dynamic/usage
curl 'https://portal.migoip.com/api/customer/v1/dynamic/usage?breakdown=overview&interval=hour&limit=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "tenant_id": "string",
  "status": "reported",
  "from": "2026-10-26T05:45:59.177Z",
  "to": "2026-10-26T05:45:59.177Z",
  "breakdown": "overview",
  "interval": "hour",
  "bucket_timezone": "string",
  "observed_at": "2026-10-26T05:45:59.177Z",
  "totals": {
    "request_count": "string",
    "limited_count": "string",
    "error_count": "string",
    "upload_bytes": "string",
    "download_bytes": "string",
    "total_bytes": "string"
  },
  "rows": [
    {
      "request_count": "string",
      "limited_count": "string",
      "error_count": "string",
      "upload_bytes": "string",
      "download_bytes": "string",
      "total_bytes": "string",
      "bucket_start": "2026-10-26T05:45:59.177Z",
      "country": "string",
      "host": "string"
    }
  ],
  "capabilities": {
    "breakdowns": [
      "overview"
    ],
    "intervals": [
      "hour"
    ],
    "max_window_days": 0,
    "bucket_timezone": "string",
    "balance_reporting": true
  }
}

查看指定时间范围的动态流量分析

创建动态流量包报价

​

所需权限: dynamic:write.

需要写入访问权限及 dynamic:write。使用当前工作空间的有效流量包价格，可附加符合条件的优惠券。

请求体

必填
application/json
  • pack_id
    类型: string
    必填
  • coupon_code
    类型: string
    最大长度:  
    64

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/dynamic/quotes
curl https://portal.migoip.com/api/customer/v1/dynamic/quotes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "pack_id": "",
  "coupon_code": ""
}'

{
  "id": "string",
  "tenant_id": "string",
  "pack_id": "string",
  "pack_label": "string",
  "kind": "standard",
  "bytes": "string",
  "price_version": 1,
  "subtotal_fen": "string",
  "discount_fen": "string",
  "total_fen": "string",
  "coupon": {
    "id": "string",
    "code": "string",
    "name": "string",
    "discount_bps": 1
  },
  "created_at": "2026-10-26T05:45:59.177Z",
  "expires_at": "2026-10-26T05:45:59.177Z"
}

创建动态流量包报价

购买流量包

​

所需权限: dynamic:write, wallet:spend.

需要写入访问权限及 dynamic:write、wallet:spend。提交 config 中的 pack_id、price_version 和 expected_total_fen，或携带 quote_id 并原样提交报价中的流量包、版本及总价。建议先创建报价以固定价格并使用优惠券。相同请求重试返回原收据，扣款与流量发放均只执行一次。流量发放返回 502 时，响应包含购买记录；请查询其状态或联系支持处理该购买。

请求头

  • Idempotency-Key
    类型: string
    最小长度:  
    8
    最大长度:  
    128
    必填

    重复提交完全相同的请求会返回原结果，且只扣款一次。请求正文发生变化会返回冲突。

请求体

必填
application/json
  • expected_total_fen
    类型:
    必填

    人民币分，以整数表示，确保金额精确。

  • pack_id
    类型: string
    必填
  • price_version
    类型: integer
    最小值:  
    1
    必填

    整数。

  • quote_id
    类型: string

响应

  • application/json
  • application/json
  • application/json
Request Example for post/api/customer/v1/dynamic/purchases
curl https://portal.migoip.com/api/customer/v1/dynamic/purchases \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "pack_id": "",
  "price_version": 1,
  "expected_total_fen": "",
  "quote_id": ""
}'

{
  "purchase": {
    "id": "string",
    "tenant_id": "string",
    "pack_id": "string",
    "pack_label": "string",
    "quote_id": "string",
    "kind": "standard",
    "bytes": "string",
    "price_fen": "string",
    "subtotal_fen": "string",
    "discount_fen": "string",
    "coupon": {
      "id": "string",
      "code": "string",
      "name": "string",
      "discount_bps": 1
    },
    "price_version": 1,
    "status": "string",
    "created_at": "2026-10-26T05:45:59.177Z"
  }
}

购买流量包

列出动态流量购买记录

​

所需权限: dynamic:read.

需要 dynamic:read。默认包含两种流量，可通过筛选限定类型。

查询参数

  • page
    类型: integer
    最小值:  
    1
    最大值:  
    100000

    整数。

  • page_size
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

  • kind
    类型: "standard" or "optimization"枚举

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/dynamic/purchases
curl 'https://portal.migoip.com/api/customer/v1/dynamic/purchases?page=1&page_size=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "pack_id": "string",
      "pack_label": "string",
      "quote_id": "string",
      "kind": "standard",
      "bytes": "string",
      "price_fen": "string",
      "subtotal_fen": "string",
      "discount_fen": "string",
      "coupon": {
        "id": "string",
        "code": "string",
        "name": "string",
        "discount_bps": 1
      },
      "price_version": 1,
      "status": "string",
      "created_at": "2026-10-26T05:45:59.177Z"
    }
  ],
  "total": 0,
  "page": 1,
  "page_size": 1
}

列出动态流量购买记录

查询动态流量购买状态

​

所需权限: dynamic:read.

需要 dynamic:read。未知或其他工作空间的 ID 返回 404。开通重试、取消与钱包退款由运营人员处理。

路径参数

  • id
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/dynamic/purchases/{id}
curl 'https://portal.migoip.com/api/customer/v1/dynamic/purchases/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "string",
  "tenant_id": "string",
  "pack_id": "string",
  "pack_label": "string",
  "quote_id": "string",
  "kind": "standard",
  "bytes": "string",
  "price_fen": "string",
  "subtotal_fen": "string",
  "discount_fen": "string",
  "coupon": {
    "id": "string",
    "code": "string",
    "name": "string",
    "discount_bps": 1
  },
  "price_version": 1,
  "status": "string",
  "created_at": "2026-10-26T05:45:59.177Z"
}

查询动态流量购买状态

列出已保存的动态连接

​

所需权限: dynamic:read.

需要 dynamic:read。按时间倒序返回直连和优化配置。列表受已保存配置数量上限约束，connection 始终为 null。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/dynamic/profiles
curl https://portal.migoip.com/api/customer/v1/dynamic/profiles \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "tenant_id": "string",
  "optimization_available": true,
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "country": "string",
      "mode": "rotating",
      "duration_minutes": 1,
      "state": "string",
      "version": 1,
      "created_at": "2026-10-26T05:45:59.177Z",
      "access_optimized": true,
      "connection": {
        "username": "string",
        "password": "string",
        "endpoints": {
          "http": {
            "host": "string",
            "port": 1
          },
          "socks5": {
            "host": "string",
            "port": 1
          }
        }
      }
    }
  ]
}

列出已保存的动态连接

生成或复用动态连接

​

所需权限: dynamic:write, credentials:read.

需要写入访问权限及 dynamic:write、credentials:read。country 为必填项；config 声明支持全部国家或地区时可使用 *。选择 rotating 或 sticky 模式，粘性会话使用支持的时长。相同有效配置会复用已保存的连接，包括使用新的幂等键时。优化接入要求有可用额度、网关及已分配的健康节点。包含连接凭据的响应属于敏感信息。

请求头

  • Idempotency-Key
    类型: string
    最小长度:  
    8
    最大长度:  
    128
    必填

    重复提交完全相同的请求会返回原结果，且只扣款一次。请求正文发生变化会返回冲突。

请求体

必填
application/json
  • country
    类型: string
    必填

    config 返回的 ISO 国家或地区代码，或代表全部可用国家或地区的 *。

  • mode
    类型: "rotating" or "sticky"枚举
    必填
  • access_optimized
    类型: boolean
  • duration_minutes
    类型: integer
    最小值:  
    1

    整数。

  • protocol
    枚举

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/dynamic/profiles
curl https://portal.migoip.com/api/customer/v1/dynamic/profiles \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "country": "",
  "protocol": "http",
  "mode": "rotating",
  "duration_minutes": 1,
  "access_optimized": false
}'

{
  "profile": {
    "id": "string",
    "tenant_id": "string",
    "country": "string",
    "mode": "rotating",
    "duration_minutes": 1,
    "state": "string",
    "version": 1,
    "created_at": "2026-10-26T05:45:59.177Z",
    "access_optimized": true,
    "connection": {
      "username": "string",
      "password": "string",
      "endpoints": {
        "http": {
          "host": "string",
          "port": 1
        },
        "socks5": {
          "host": "string",
          "port": 1
        }
      }
    }
  }
}

生成或复用动态连接

查看动态连接

​

所需权限: dynamic:read, credentials:read.

需要 dynamic:read、credentials:read。仅对已就绪、获授权且有服务使用权限的配置返回连接凭据。未知或其他工作空间的 ID 返回 404。

路径参数

  • id
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/dynamic/profiles/{id}
curl 'https://portal.migoip.com/api/customer/v1/dynamic/profiles/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "profile": {
    "id": "string",
    "tenant_id": "string",
    "country": "string",
    "mode": "rotating",
    "duration_minutes": 1,
    "state": "string",
    "version": 1,
    "created_at": "2026-10-26T05:45:59.177Z",
    "access_optimized": true,
    "connection": {
      "username": "string",
      "password": "string",
      "endpoints": {
        "http": {
          "host": "string",
          "port": 1
        },
        "socks5": {
          "host": "string",
          "port": 1
        }
      }
    }
  }
}

查看动态连接

移除已保存的动态连接

​

所需权限: dynamic:write.

需要写入访问权限及 dynamic:write。移除操作可安全重试。删除直连配置仅移除保存的设置；已复制的共享凭据及已购流量保持原状态。

路径参数

  • id
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for delete/api/customer/v1/dynamic/profiles/{id}
curl 'https://portal.migoip.com/api/customer/v1/dynamic/profiles/{id}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "revoked": true
}

移除已保存的动态连接

钱包

​
钱包 操作

查看钱包汇总

​

所需权限: wallet:read.

需要 wallet:read。已入账余额、本月支出及最近充值使用与门户一致的数据快照。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/wallet/summary
curl https://portal.migoip.com/api/customer/v1/wallet/summary \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "tenant_id": "string",
  "balance_fen": "string",
  "spent_month_fen": "string",
  "month_start": "2026-10-26T05:45:59.177Z",
  "month_end": "2026-10-26T05:45:59.177Z",
  "last_recharge": {
    "id": "string",
    "amount_fen": "string",
    "channel": "manual",
    "created_at": "2026-10-26T05:45:59.177Z"
  }
}

查看钱包汇总

列出已入账的钱包流水

​

所需权限: wallet:read.

需要 wallet:read。待支付意图单独列在充值记录中。

查询参数

  • page
    类型: integer
    最小值:  
    1
    最大值:  
    100000

    整数。

  • page_size
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

  • q
    类型: string
  • kind
    类型: string
  • from
    类型: string

    UTC 起始时间，包含边界，格式为 RFC3339 或 YYYY-MM-DD。

  • to
    类型: string

    UTC 结束时间，不含边界，格式为 RFC3339 或 YYYY-MM-DD，必须晚于 from。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/wallet/ledger
curl 'https://portal.migoip.com/api/customer/v1/wallet/ledger?page=1&page_size=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "kind": "recharge",
      "channel": "manual",
      "direction": "credit",
      "amount_fen": "string",
      "wallet_delta_fen": "string",
      "reason": "string",
      "reference_id": "string",
      "created_at": "2026-10-26T05:45:59.177Z"
    }
  ],
  "total": 0,
  "page": 1,
  "page_size": 1
}

列出已入账的钱包流水

支付

​
支付 操作

查看可用充值方式

​

所需权限: recharges:read.

需要 recharges:read。可用性与精确费用遵循当前支付策略，请同时检查方式是否启用。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/recharges/config
curl https://portal.migoip.com/api/customer/v1/recharges/config \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "tenant_id": "string",
  "currency": "CNY",
  "mock": true,
  "allow_unverified": false,
  "can_create": true,
  "eligibility_reason": "",
  "channels": [
    {
      "channel": "card",
      "enabled": true,
      "policy_revision": "string",
      "flat_fee_fen": "string",
      "fee_bps": "string",
      "fee_rounding": "up",
      "min_amount_fen": "string",
      "max_amount_fen": "string",
      "validity_seconds": 1
    }
  ],
  "disabled_channels": [
    "usdt"
  ]
}

查看可用充值方式

列出支付意图

​

所需权限: recharges:read.

需要 recharges:read。仅接受 limit、offset 和 state，各参数只出现一次。列表省略可执行的支付指令。

查询参数

  • limit
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

  • offset
    类型: integer
    最小值:  
    0
    最大值:  
    1000000

    整数。

  • state
    类型: string枚举
    值
    queuedrunningwaitingneeds_attentionsucceeded

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/recharges
curl 'https://portal.migoip.com/api/customer/v1/recharges?limit=20&offset=0' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "actor_id": "string",
      "state": "queued",
      "version": 1,
      "credited": true,
      "mock": true,
      "channel": "card",
      "currency": "CNY",
      "policy_revision": "string",
      "amount_fen": "string",
      "gross_fen": "string",
      "fee_fen": "string",
      "credit_fen": "string",
      "flat_fee_fen": "string",
      "fee_bps": "string",
      "fee_rounding": "up",
      "instructions": {
        "kind": "mock",
        "reference": "string",
        "payment_url": "string"
      },
      "expires_at": "2026-10-26T05:45:59.177Z",
      "created_at": "2026-10-26T05:45:59.177Z"
    }
  ],
  "total": 0,
  "limit": 1,
  "offset": 0
}

列出支付意图

创建充值支付意图

​

所需权限: recharges:write.

需要写入访问权限及 recharges:write。创建支付要求钱包充值策略已启用。钱包在确认到账后入账。相同请求重试时复用 Idempotency-Key。旧版 asset_units 仅用于已有 USDT 收据的重复请求；新建 USDT 支付保持关闭。

请求头

  • Idempotency-Key
    类型: string
    最小长度:  
    8
    最大长度:  
    128
    必填

    重复提交完全相同的请求会返回原结果，且只扣款一次。请求正文发生变化会返回冲突。

请求体

必填
application/json

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/recharges
curl https://portal.migoip.com/api/customer/v1/recharges \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "channel": "card",
  "amount_fen": "",
  "policy_revision": "",
  "expected_fee_fen": "",
  "expected_credit_fen": ""
}'

{
  "id": "string",
  "tenant_id": "string",
  "actor_id": "string",
  "state": "queued",
  "version": 1,
  "credited": true,
  "mock": true,
  "channel": "card",
  "currency": "CNY",
  "policy_revision": "string",
  "amount_fen": "string",
  "gross_fen": "string",
  "fee_fen": "string",
  "credit_fen": "string",
  "flat_fee_fen": "string",
  "fee_bps": "string",
  "fee_rounding": "up",
  "instructions": {
    "kind": "mock",
    "reference": "string",
    "payment_url": "string"
  },
  "expires_at": "2026-10-26T05:45:59.177Z",
  "created_at": "2026-10-26T05:45:59.177Z"
}

创建充值支付意图

查看支付意图及支付指令

​

所需权限: recharges:read.

需要 recharges:read。支付指令仅在意图仍可操作时向所属操作人显示，适用时包含银行卡 client_secret。这些信息用于执行单次支付，到账结果以确认结算为准。

路径参数

  • id
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/recharges/{id}
curl 'https://portal.migoip.com/api/customer/v1/recharges/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "string",
  "tenant_id": "string",
  "actor_id": "string",
  "state": "queued",
  "version": 1,
  "credited": true,
  "mock": true,
  "channel": "card",
  "currency": "CNY",
  "policy_revision": "string",
  "amount_fen": "string",
  "gross_fen": "string",
  "fee_fen": "string",
  "credit_fen": "string",
  "flat_fee_fen": "string",
  "fee_bps": "string",
  "fee_rounding": "up",
  "instructions": {
    "kind": "mock",
    "reference": "string",
    "payment_url": "string"
  },
  "expires_at": "2026-10-26T05:45:59.177Z",
  "created_at": "2026-10-26T05:45:59.177Z"
}

查看支付意图及支付指令

查看充值与手动调整历史

​

所需权限: recharges:read.

需要 recharges:read。已过期且未入账的支付向客户显示为 closed；随后确认到账时仍可变为成功。

查询参数

  • page
    类型: integer
    最小值:  
    1
    最大值:  
    100000

    整数。

  • page_size
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

  • q
    类型: string
  • state
    类型: string
  • channel
    类型: string

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/recharge-history
curl 'https://portal.migoip.com/api/customer/v1/recharge-history?page=1&page_size=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "kind": "gateway",
      "channel": "manual",
      "direction": "credit",
      "amount_fen": "string",
      "credit_fen": "string",
      "state": "queued",
      "reason": "string",
      "created_at": "2026-10-26T05:45:59.177Z"
    }
  ],
  "total": 0,
  "page": 1,
  "page_size": 1
}

查看充值与手动调整历史

用量与日志

​
用量与日志 操作

查看工作空间指标

​

所需权限: metrics:read.

需要 metrics:read。仅统计优化转发节点观测到的流量。空结果、未启用、过时和不可用分别返回对应状态。时间范围与样本数受限。其他工作空间的 IP ID 在查询指标前返回 404。

查询参数

  • start
    类型: string格式: date-time

    RFC3339 格式的 UTC 时间下限。

  • end
    类型: string格式: date-time

    RFC3339 格式的 UTC 时间上限。

  • step_seconds
    类型: integer
    最小值:  
    1
    最大值:  
    2592000

    请求的采样间隔，单位为秒。系统会按需增大间隔，使图表最多返回 720 个点。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/observability/metrics
curl https://portal.migoip.com/api/customer/v1/observability/metrics \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "status": "ready",
  "reason": "string",
  "observed_at": "2026-10-26T05:45:59.177Z",
  "start": "2026-10-26T05:45:59.177Z",
  "end": "2026-10-26T05:45:59.177Z",
  "step_seconds": 1,
  "coverage": "forwarder_only",
  "points": [
    {
      "timestamp": "2026-10-26T05:45:59.177Z",
      "upload_bps": 1,
      "download_bps": 1,
      "active_connections": 1
    }
  ],
  "totals": {
    "upload_bytes": 1,
    "download_bytes": 1
  }
}

查看工作空间指标

查看工作空间日志

​

所需权限: metrics:read.

需要 metrics:read。仅统计优化转发节点观测到的流量。空结果、未启用、过时和不可用分别返回对应状态。时间范围与样本数受限。其他工作空间的 IP ID 在查询指标前返回 404。

查询参数

  • start
    类型: string格式: date-time

    RFC3339 格式的 UTC 时间下限。

  • end
    类型: string格式: date-time

    RFC3339 格式的 UTC 时间上限。

  • limit
    类型: integer
    最小值:  
    1
    最大值:  
    100

    每页最多返回的事件数。

  • cursor
    类型: string
    最大长度:  
    4096

    与原查询范围绑定的不透明游标。

  • protocol
    类型: "http" or "connect" or "socks5"枚举

    精确匹配协议的筛选条件，仅支持完整值。

  • transport
    类型: "tcp" or "udp"枚举

    精确匹配传输协议。tcp 也包括添加该字段前的历史记录，当时的数据平面仅支持 TCP；udp 仅匹配明确标记为 udp 的记录。

  • outcome
    类型: string枚举

    精确匹配结果的筛选条件。

    值
    successerrorcancelledincomplete
  • source_ip
    类型: string
    最大长度:  
    45

    精确匹配客户端来源地址，必须是有效的 IPv4 或 IPv6 地址。

  • destination_host
    类型: string
    最大长度:  
    255

    精确匹配目标主机的筛选条件。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/observability/logs
curl 'https://portal.migoip.com/api/customer/v1/observability/logs?limit=50' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "status": "ready",
  "reason": "string",
  "observed_at": "2026-10-26T05:45:59.177Z",
  "items": [
    {
      "schema_version": 1,
      "event_id": "string",
      "timestamp": "2026-10-26T05:45:59.177Z",
      "event_type": "connection_open",
      "node_id": "string",
      "connection_id": "string",
      "request_id": "string",
      "tenant_id": "string",
      "instance_id": "string",
      "instance_ip": "string",
      "instance_note": "string",
      "assignment_id": "string",
      "source_ip": "string",
      "source_port": 1,
      "destination_host": "string",
      "destination_ip": "string",
      "destination_port": 1,
      "upstream_host": "string",
      "upstream_port": 1,
      "protocol": "http",
      "transport": "tcp",
      "upload_bytes": 1,
      "download_bytes": 1,
      "duration_ms": 1,
      "outcome": "success",
      "failure_stage": "string",
      "close_reason": "string",
      "http_method": "string",
      "http_status": 1
    }
  ],
  "next_cursor": "string",
  "coverage": "forwarder_only"
}

查看工作空间日志

查看单个 IP 的指标

​

所需权限: metrics:read.

需要 metrics:read。仅统计优化转发节点观测到的流量。空结果、未启用、过时和不可用分别返回对应状态。时间范围与样本数受限。其他工作空间的 IP ID 在查询指标前返回 404。

路径参数

  • id
    类型: string
    必填

查询参数

  • start
    类型: string格式: date-time

    RFC3339 格式的 UTC 时间下限。

  • end
    类型: string格式: date-time

    RFC3339 格式的 UTC 时间上限。

  • step_seconds
    类型: integer
    最小值:  
    1
    最大值:  
    2592000

    请求的采样间隔，单位为秒。系统会按需增大间隔，使图表最多返回 720 个点。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/proxies/{id}/observability/metrics
curl 'https://portal.migoip.com/api/customer/v1/proxies/{id}/observability/metrics' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "status": "ready",
  "reason": "string",
  "observed_at": "2026-10-26T05:45:59.177Z",
  "start": "2026-10-26T05:45:59.177Z",
  "end": "2026-10-26T05:45:59.177Z",
  "step_seconds": 1,
  "coverage": "forwarder_only",
  "points": [
    {
      "timestamp": "2026-10-26T05:45:59.177Z",
      "upload_bps": 1,
      "download_bps": 1,
      "active_connections": 1
    }
  ],
  "totals": {
    "upload_bytes": 1,
    "download_bytes": 1
  }
}

查看单个 IP 的指标

查看单个 IP 的日志

​

所需权限: metrics:read.

需要 metrics:read。仅统计优化转发节点观测到的流量。空结果、未启用、过时和不可用分别返回对应状态。时间范围与样本数受限。其他工作空间的 IP ID 在查询指标前返回 404。

路径参数

  • id
    类型: string
    必填

查询参数

  • start
    类型: string格式: date-time

    RFC3339 格式的 UTC 时间下限。

  • end
    类型: string格式: date-time

    RFC3339 格式的 UTC 时间上限。

  • limit
    类型: integer
    最小值:  
    1
    最大值:  
    100

    每页最多返回的事件数。

  • cursor
    类型: string
    最大长度:  
    4096

    与原查询范围绑定的不透明游标。

  • protocol
    类型: "http" or "connect" or "socks5"枚举

    精确匹配协议的筛选条件，仅支持完整值。

  • transport
    类型: "tcp" or "udp"枚举

    精确匹配传输协议。tcp 也包括添加该字段前的历史记录，当时的数据平面仅支持 TCP；udp 仅匹配明确标记为 udp 的记录。

  • outcome
    类型: string枚举

    精确匹配结果的筛选条件。

    值
    successerrorcancelledincomplete
  • source_ip
    类型: string
    最大长度:  
    45

    精确匹配客户端来源地址，必须是有效的 IPv4 或 IPv6 地址。

  • destination_host
    类型: string
    最大长度:  
    255

    精确匹配目标主机的筛选条件。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/proxies/{id}/observability/logs
curl 'https://portal.migoip.com/api/customer/v1/proxies/{id}/observability/logs?limit=50' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "status": "ready",
  "reason": "string",
  "observed_at": "2026-10-26T05:45:59.177Z",
  "items": [
    {
      "schema_version": 1,
      "event_id": "string",
      "timestamp": "2026-10-26T05:45:59.177Z",
      "event_type": "connection_open",
      "node_id": "string",
      "connection_id": "string",
      "request_id": "string",
      "tenant_id": "string",
      "instance_id": "string",
      "instance_ip": "string",
      "instance_note": "string",
      "assignment_id": "string",
      "source_ip": "string",
      "source_port": 1,
      "destination_host": "string",
      "destination_ip": "string",
      "destination_port": 1,
      "upstream_host": "string",
      "upstream_port": 1,
      "protocol": "http",
      "transport": "tcp",
      "upload_bytes": 1,
      "download_bytes": 1,
      "duration_ms": 1,
      "outcome": "success",
      "failure_stage": "string",
      "close_reason": "string",
      "http_method": "string",
      "http_status": 1
    }
  ],
  "next_cursor": "string",
  "coverage": "forwarder_only"
}

查看单个 IP 的日志

推荐计划

​
推荐计划 操作

查看推荐计划汇总

​

所需权限: referrals:read.

需要 referrals:read。仅返回当前工作空间的推荐计划及经过脱敏的受邀人信息。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/referrals
curl https://portal.migoip.com/api/customer/v1/referrals \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "tenant_id": "string",
  "program_enabled": true,
  "can_generate_link": true,
  "link": {
    "token": "string",
    "enabled": true,
    "version": 1,
    "created_at": "2026-10-26T05:45:59.177Z"
  },
  "first_order_bps": 1,
  "subsequent_order_bps": 1,
  "invited_users": 0,
  "qualifying_orders": 0,
  "earned_fen": "string",
  "reversed_fen": "string",
  "outstanding_recovery_fen": "string"
}

查看推荐计划汇总

列出受邀人

​

所需权限: referrals:read.

需要 referrals:read。归属、身份脱敏及奖励金额由服务器确定。

查询参数

  • page
    类型: integer
    最小值:  
    1
    最大值:  
    100000

    整数。

  • page_size
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/referrals/invitees
curl 'https://portal.migoip.com/api/customer/v1/referrals/invitees?page=1&page_size=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "id": "string",
      "display_label": "string",
      "registered_at": "2026-10-26T05:45:59.177Z",
      "created_workspace_count": 0,
      "qualifying_orders": 0,
      "earned_fen": "string",
      "reversed_fen": "string"
    }
  ],
  "total": 0,
  "page": 1,
  "page_size": 1
}

列出受邀人

列出推荐奖励

​

所需权限: referrals:read.

需要 referrals:read。归属、身份脱敏及奖励金额由服务器确定。

查询参数

  • page
    类型: integer
    最小值:  
    1
    最大值:  
    100000

    整数。

  • page_size
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/referrals/rewards
curl 'https://portal.migoip.com/api/customer/v1/referrals/rewards?page=1&page_size=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "id": "string",
      "invitee_label": "string",
      "source_kind": "static_purchase",
      "source_reference": "string",
      "attribution_source": "workspace_creator",
      "rate_bps": 0,
      "eligible_paid_fen": "string",
      "earned_fen": "string",
      "reversed_fen": "string",
      "outstanding_recovery_fen": "string",
      "created_at": "2026-10-26T05:45:59.177Z",
      "updated_at": "2026-10-26T05:45:59.177Z"
    }
  ],
  "total": 0,
  "page": 1,
  "page_size": 1
}

列出推荐奖励

Webhook

​
Webhook 操作

列出 Webhook 订阅

​

所需权限: webhooks:read.

需要 webhooks:read。包含已停用及已删除的订阅，以供查看投递历史。响应省略签名密钥。

查询参数

  • page
    类型: integer
    最小值:  
    1
    最大值:  
    100000

    整数。

  • page_size
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/webhooks
curl 'https://portal.migoip.com/api/customer/v1/webhooks?page=1&page_size=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "name": "string",
      "url": "https://example.com",
      "event_types": [
        "fulfillment.updated"
      ],
      "enabled": true,
      "wallet_low_balance_threshold_fen": null,
      "id": "string",
      "version": 1,
      "created_at": "2026-10-26T05:45:59.177Z",
      "updated_at": "2026-10-26T05:45:59.177Z",
      "disabled_at": null
    }
  ],
  "total": 0,
  "page": 1,
  "page_size": 1
}

列出 Webhook 订阅

创建 Webhook 订阅

​

所需权限: webhooks:write.

需要写入访问权限及 webhooks:write。每个工作空间最多启用 10 个订阅。必须提供 Idempotency-Key，相同请求重试返回原订阅。请安全保存返回的签名密钥。订阅捕获创建后提交的事件，历史事件保持原状。

请求头

  • Idempotency-Key
    类型: string
    最小长度:  
    8
    最大长度:  
    128
    必填

    重复提交完全相同的请求会返回原结果，且只扣款一次。请求正文发生变化会返回冲突。

请求体·

必填
application/json
  • enabled
    类型: boolean
    必填
  • event_types
    类型: array of string 1… 唯一!枚举
    必填
    值
    fulfillment.updatedrenewal.updatedrefund.completedwallet.low_balancedynamic.purchase.updated
  • name
    类型: string
    最小长度:  
    1
    最大长度:  
    80
    必填
  • url
    类型: string
    最大长度:  
    2048    格式: uri
    必填

    仅支持 HTTPS 和 443 端口，URL 必须省略用户凭据和片段。每次投递都会解析并固定公网地址；私有地址、特殊地址和混合公网与私网的 DNS 结果会被拒绝。

  • wallet_low_balance_threshold_fen
    类型: string | null

    精确的人民币分金额；选择 wallet.low_balance 时必填，否则为 null。最大为 9007199254740992。

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/webhooks
curl https://portal.migoip.com/api/customer/v1/webhooks \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "",
  "url": "",
  "event_types": [
    "fulfillment.updated"
  ],
  "enabled": true,
  "wallet_low_balance_threshold_fen": null
}'

{
  "webhook": {
    "name": "string",
    "url": "https://example.com",
    "event_types": [
      "fulfillment.updated"
    ],
    "enabled": true,
    "wallet_low_balance_threshold_fen": null,
    "id": "string",
    "version": 1,
    "created_at": "2026-10-26T05:45:59.177Z",
    "updated_at": "2026-10-26T05:45:59.177Z",
    "disabled_at": null
  },
  "secret": "string"
}

创建 Webhook 订阅

查看 Webhook 订阅

​

所需权限: webhooks:read.

需要 webhooks:read。其他工作空间的 ID 返回 404。

路径参数

  • id
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/webhooks/{id}
curl 'https://portal.migoip.com/api/customer/v1/webhooks/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "webhook": {
    "name": "string",
    "url": "https://example.com",
    "event_types": [
      "fulfillment.updated"
    ],
    "enabled": true,
    "wallet_low_balance_threshold_fen": null,
    "id": "string",
    "version": 1,
    "created_at": "2026-10-26T05:45:59.177Z",
    "updated_at": "2026-10-26T05:45:59.177Z",
    "disabled_at": null
  }
}

查看 Webhook 订阅

更新 Webhook 订阅

​

所需权限: webhooks:write.

需要写入访问权限及 webhooks:write。提交当前 version，版本过旧返回 409。省略的字段保持原值。移除 wallet.low_balance 时需同时将阈值设为 null。已删除订阅无法重新启用。

路径参数

  • id
    类型: string
    必填

请求体·

必填
application/json
  • version
    类型: integer
    最小值:  
    1
    必填

    整数。

  • enabled
    类型: boolean
  • event_types
    类型: array of string 1… 唯一!枚举
    值
    fulfillment.updatedrenewal.updatedrefund.completedwallet.low_balancedynamic.purchase.updated
  • name
    类型: string
    最小长度:  
    1
    最大长度:  
    80
  • url
    类型: string
    最大长度:  
    2048    格式: uri

    仅支持 HTTPS 和 443 端口，URL 必须省略用户凭据和片段。每次投递都会解析并固定公网地址；私有地址、特殊地址和混合公网与私网的 DNS 结果会被拒绝。

  • wallet_low_balance_threshold_fen
    类型: string | null

    精确的人民币分金额；选择 wallet.low_balance 时必填，否则为 null。最大为 9007199254740992。

响应

  • application/json
  • application/json
Request Example for patch/api/customer/v1/webhooks/{id}
curl 'https://portal.migoip.com/api/customer/v1/webhooks/{id}' \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "",
  "url": "",
  "event_types": [
    "fulfillment.updated"
  ],
  "enabled": true,
  "wallet_low_balance_threshold_fen": null,
  "version": 1
}'

{
  "webhook": {
    "name": "string",
    "url": "https://example.com",
    "event_types": [
      "fulfillment.updated"
    ],
    "enabled": true,
    "wallet_low_balance_threshold_fen": null,
    "id": "string",
    "version": 1,
    "created_at": "2026-10-26T05:45:59.177Z",
    "updated_at": "2026-10-26T05:45:59.177Z",
    "disabled_at": null
  }
}

更新 Webhook 订阅

删除 Webhook 订阅

​

所需权限: webhooks:write.

需要写入访问权限及 webhooks:write。软删除保留历史并取消待投递事件。重复删除可安全执行。已经发出的网络请求仍可能到达。

路径参数

  • id
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for delete/api/customer/v1/webhooks/{id}
curl 'https://portal.migoip.com/api/customer/v1/webhooks/{id}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "webhook": {
    "name": "string",
    "url": "https://example.com",
    "event_types": [
      "fulfillment.updated"
    ],
    "enabled": true,
    "wallet_low_balance_threshold_fen": null,
    "id": "string",
    "version": 1,
    "created_at": "2026-10-26T05:45:59.177Z",
    "updated_at": "2026-10-26T05:45:59.177Z",
    "disabled_at": null
  }
}

删除 Webhook 订阅

轮换 Webhook 签名密钥

​

所需权限: webhooks:write.

需要写入访问权限及 webhooks:write。返回新密钥，后续投递使用新密钥。此操作每次都会轮换密钥；响应不确定时请人工确认后操作。正在发送的事件仍可能携带旧签名。响应丢失时，请明确再次轮换并安装此次返回的新密钥。

路径参数

  • id
    类型: string
    必填

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/webhooks/{id}/rotate-secret
curl 'https://portal.migoip.com/api/customer/v1/webhooks/{id}/rotate-secret' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "webhook": {
    "name": "string",
    "url": "https://example.com",
    "event_types": [
      "fulfillment.updated"
    ],
    "enabled": true,
    "wallet_low_balance_threshold_fen": null,
    "id": "string",
    "version": 1,
    "created_at": "2026-10-26T05:45:59.177Z",
    "updated_at": "2026-10-26T05:45:59.177Z",
    "disabled_at": null
  },
  "secret": "string"
}

轮换 Webhook 签名密钥

查看投递历史

​

所需权限: webhooks:read.

需要 webhooks:read。事件采用至少一次投递，顺序可能变化；请按 event_id 去重。每轮最多尝试 8 次，失败后自动停止，最多允许 3 轮手动重试。

路径参数

  • id
    类型: string
    必填

查询参数

  • page
    类型: integer
    最小值:  
    1
    最大值:  
    100000

    整数。

  • page_size
    类型: integer
    最小值:  
    1
    最大值:  
    100

    整数。

响应

  • application/json
  • application/json
Request Example for get/api/customer/v1/webhooks/{id}/deliveries
curl 'https://portal.migoip.com/api/customer/v1/webhooks/{id}/deliveries?page=1&page_size=20' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "id": "string",
      "event_id": "string",
      "event_type": "fulfillment.updated",
      "state": "pending",
      "attempts": 1,
      "max_attempts": 1,
      "manual_retries": 0,
      "attempt_budget": 1,
      "next_attempt_at": null,
      "last_attempt_at": null,
      "last_status_code": null,
      "last_error_code": "string",
      "delivered_at": null,
      "created_at": "2026-10-26T05:45:59.177Z",
      "payload": {
        "service_id": "string",
        "status": "fulfilled",
        "expires_at": null,
        "activated_at": "2026-10-26T05:45:59.177Z",
        "order_id": null
      }
    }
  ],
  "total": 0,
  "page": 1,
  "page_size": 1
}

查看投递历史

重试失败的投递

​

所需权限: webhooks:write.

需要写入访问权限及 webhooks:write。仅已启用订阅中的失败投递可重试。必须提供 Idempotency-Key，相同请求重试保持原结果。新增一轮次数受限的投递，沿用原事件 ID。

路径参数

  • id
    类型: string
    必填
  • delivery
    类型: string
    必填

请求头

  • Idempotency-Key
    类型: string
    最小长度:  
    8
    最大长度:  
    128
    必填

    重复提交完全相同的请求会返回原结果，且只扣款一次。请求正文发生变化会返回冲突。

响应

  • application/json
  • application/json
Request Example for post/api/customer/v1/webhooks/{id}/deliveries/{delivery}/retry
curl 'https://portal.migoip.com/api/customer/v1/webhooks/{id}/deliveries/{delivery}/retry' \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "delivery": {
    "id": "string",
    "event_id": "string",
    "event_type": "fulfillment.updated",
    "state": "pending",
    "attempts": 1,
    "max_attempts": 1,
    "manual_retries": 0,
    "attempt_budget": 1,
    "next_attempt_at": null,
    "last_attempt_at": null,
    "last_status_code": null,
    "last_error_code": "string",
    "delivered_at": null,
    "created_at": "2026-10-26T05:45:59.177Z",
    "payload": {
      "service_id": "string",
      "status": "fulfilled",
      "expires_at": null,
      "activated_at": "2026-10-26T05:45:59.177Z",
      "order_id": null
    }
  }
}

重试失败的投递

模型

​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
使用文档Esc · 关闭