跳至內文
使用文件
繁
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 · 關閉