# Thiết lập proxy điện thoại đám mây

Gán proxy cho một hoặc nhiều cloud phone.
- **Điều kiện tiên quyết**: cung cấp ít nhất một trong `ids` hoặc `uniqueIds`. Các cloud phone phải thuộc nhóm của bạn; chúng **không** cần đang bật. Nếu bạn truyền `proxyId`, nó phải tồn tại, nếu không lệnh gọi sẽ bị từ chối.
- **Tác động**: khi `proxyId` được bỏ trống hoặc bằng `0`, một proxy hiện có với thông tin kết nối giống hệt sẽ được dùng lại, và **nếu không có proxy nào khớp thì một bản ghi proxy mới được tạo trong nhóm của bạn**. Trạng thái kiểm tra proxy được đặt lại và proxy trước đó được ghi nhớ.
- **Hoàn tất**: đồng bộ. **Các cloud phone đang bật nhận proxy mới ngay lập tức — không cần khởi động lại**; máy đang tắt sẽ áp dụng nó ở lần khởi động kế tiếp.
- **Thử lại**: gán lại một `proxyId` đã có là idempotent, nhưng gọi lại một yêu cầu mang thông tin kết nối thô có thể tạo thêm một bản ghi proxy mỗi lần cơ chế chống trùng không khớp được.

Các mã lỗi nghiệp vụ đã ghi nhận: `33300`, `33303`, `33320`, `14023`. Xem [Error Codes](../Getting%20Started/error-codes.md) để biết ý nghĩa từng mã. Mọi thao tác cũng có thể trả về các mã dùng chung.

Endpoint: POST /api/cloudphone/setProxy
Version: 2026-09-05

## Request fields (application/json):

  - `ids` (array)
    Danh sách ID môi trường Cloud Phone
    Example: ["1558968155668507"]

  - `uniqueIds` (array)
    Danh sách số thứ tự hiển thị của các môi trường Cloud Phone (dùng để đối chiếu nếu không cung cấp envIds)
    Example: [1001]

  - `proxy` (object)

  - `proxy.proxyId` (string)
    ID cấu hình proxy (giá trị lớn hơn 0 nghĩa là dùng lại cấu hình proxy hiện có; nếu rỗng hoặc <=0 thì dùng các tham số chi tiết phía sau để tạo/cập nhật proxy)
    Example: 10002

  - `proxy.proxyIp` (string, required)
    Địa chỉ IP của máy chủ proxy
    Example: 192.168.1.100

  - `proxy.proxyPort` (integer, required)
    Cổng của máy chủ proxy
    Example: 8080

  - `proxy.proxyName` (string)
    Tên/mô tả cấu hình proxy
    Example: test_proxy_01

  - `proxy.proxyProvider` (integer, required)
    Loại proxy 0:http, 1:https, 2:socks5
    Example: 2

  - `proxy.username` (string)
    Tên người dùng xác thực proxy
    Example: admin

  - `proxy.password` (string)
    Mật khẩu xác thực proxy
    Example: pwd123

  - `proxy.refreshUrl` (string)
    URL API để làm mới IP của proxy động
    Example: http://api.proxy.com/refresh

  - `proxy.country` (string)
    Mã quốc gia nơi đặt proxy (ví dụ: CN, US)
    Example: US

  - `proxy.state` (string)
    Tỉnh/Thành nơi đặt proxy
    Example: California

  - `proxy.city` (string)
    Thành phố nơi đặt proxy
    Example: Los Angeles

## Response 200:

  - `200` (unknown)
    Thành công. `data` luôn là null với thao tác này; kết quả được thể hiện qua `code`.

## Response 200 fields (application/json):

  - `code` (integer)
    Mã phản hồi: 0 = thành công, >0 = lỗi

  - `data` (null)

  - `msg` (string | null)
    Thông báo; có giá trị khi code > 0

  - `requestId` (string)
    Định danh yêu cầu duy nhất; hãy cung cấp khi liên hệ hỗ trợ