# Configurar proxy do telefone na nuvem

Vincula um proxy a um ou mais Cloud Phones.
- **Pré-requisitos**: informe pelo menos um entre `ids` e `uniqueIds`. Os telefones precisam pertencer à sua equipe; **não** é necessário que estejam ligados. Se você informar um `proxyId`, ele precisa existir; caso contrário a chamada é rejeitada.
- **Efeito**: quando `proxyId` é omitido ou é `0`, um proxy existente com dados de conexão idênticos é reutilizado e **um novo registro de proxy é criado na sua equipe se nenhum corresponder**. O estado de verificação do proxy é redefinido e o proxy anterior fica registrado.
- **Conclusão**: sincrônica. **Telefones ligados recebem o novo proxy imediatamente: não é preciso reiniciar**; telefones desligados o adotam na próxima inicialização.
- **Nova tentativa**: revincular um `proxyId` existente é idempotente, mas repetir uma chamada que carrega dados de conexão brutos pode criar outro registro de proxy a cada vez que a deduplicação não encontrar correspondência.

Erros de negócio documentados: `33300`, `33303`, `33320`, `14023`. Consulte [Error Codes](../Getting%20Started/error-codes.md) para o significado de cada código. Qualquer operação também pode retornar os códigos comuns.

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

## Request fields (application/json):

  - `ids` (array)
    Lista de IDs de ambientes de telefones na nuvem
    Example: ["1558968155668507"]

  - `uniqueIds` (array)
    Lista de números de sequência exibidos dos ambientes de telefones na nuvem (usada como correspondência se envIds não for informado)
    Example: [1001]

  - `proxy` (object)

  - `proxy.proxyId` (string)
    ID da configuração de proxy (se o valor for maior que 0, reutiliza uma configuração de proxy existente; se vazio ou <=0, usa os parâmetros detalhados seguintes para criar/atualizar o proxy)
    Example: 10002

  - `proxy.proxyIp` (string, required)
    Endereço IP do servidor proxy
    Example: 192.168.1.100

  - `proxy.proxyPort` (integer, required)
    Porta do servidor proxy
    Example: 8080

  - `proxy.proxyName` (string)
    Nome/descrição da configuração de proxy
    Example: test_proxy_01

  - `proxy.proxyProvider` (integer, required)
    Tipo de proxy 0:http, 1:https, 2:socks5
    Example: 2

  - `proxy.username` (string)
    Usuário de autenticação do proxy
    Example: admin

  - `proxy.password` (string)
    Senha de autenticação do proxy
    Example: pwd123

  - `proxy.refreshUrl` (string)
    URL da API para atualizar o IP do proxy dinâmico
    Example: http://api.proxy.com/refresh

  - `proxy.country` (string)
    Código do país da localização do proxy (por exemplo, CN, US)
    Example: US

  - `proxy.state` (string)
    Estado/Província da localização do proxy
    Example: California

  - `proxy.city` (string)
    Cidade da localização do proxy
    Example: Los Angeles

## Response 200:

  - `200` (unknown)
    Sucesso. `data` é sempre null nesta operação; o resultado é informado por `code`.

## Response 200 fields (application/json):

  - `code` (integer)
    Código de resposta: 0 = sucesso, >0 = erro

  - `data` (null)

  - `msg` (string | null)
    Mensagem; preenchida se code > 0

  - `requestId` (string)
    Identificador único da solicitação; informe-o ao contatar o suporte