Proxy

Configurar ou alterar o proxy

POSThttps://api.nodinfra.com.br/instance/proxy

URL completa: https://api.nodinfra.com.br/instance/proxy

Define explicitamente um dos três estados aceitos:

mode=custom: usa um proxy próprio informado em proxy_url;
mode=internal: usa a infraestrutura interna; ou
mode=none: conexão direta, permitida apenas com confirm_no_proxy=true.

Importante: POST /instance/proxy confirma que a configuração foi salva, não que o proxy já foi comprovado em uso. A validação operacional principal acontece no próximo ciclo real de conexão da instância.

Em termos práticos:

200 OK aqui = configuração persistida com sucesso;
falhas reais de conectividade podem aparecer depois; e
para observar o estado real, consulte GET /instance/proxy e leia:
- effective_mode
- effective_detail
- fallback.active
- last_test_error
- validation_error

Quando mode=custom, você também pode definir a contingência via proxy_fallback:

internal: tenta a infraestrutura interna e, se ainda assim falhar, pode usar direto como último recurso;
never: não usa contingência; ou
uma URL de proxy de contingência controlada pelo próprio cliente.

Quando mode=internal, rotate_now: true troca imediatamente o proxy interno persistido. Se houver mais de uma origem interna disponível, a plataforma escolhe outra origem sem expor o fornecedor. Se houver apenas uma origem, troca apenas o proxy/IP dentro dessa origem.

Protocolos aceitos em URLs de proxy customizado:

http://usuario:senha@host:porta
https://usuario:senha@host:porta
socks5://usuario:senha@host:porta
socks5h://usuario:senha@host:porta

O esquema socks:// genérico não é aceito. Para proxies SOCKS, use socks5:// ou socks5h://.

Corpo da requisição

modestringopcional

Campo canônico para definir a estratégia de proxy.

valores:custominternalnone

proxy_urlstringopcional

Obrigatório quando `mode=custom`. Protocolos aceitos: `http://`, `https://`, `socks5://` e `socks5h://`. O esquema `socks://` genérico não é suportado; use `socks5://` ou `socks5h://`.

exemplo: http://usuario:senha@ip:porta

proxy_fallbackstringopcional

Política de contingência para `mode=custom`. Aceita `internal`, `never` ou uma URL de proxy de contingência usando `http://`, `https://`, `socks5://` ou `socks5h://`.

confirm_no_proxybooleanopcional

Obrigatório quando `mode=none`.

rotate_nowbooleanopcional

Quando `true` com `mode=internal`, troca imediatamente o proxy interno persistido sem expor o fornecedor usado.

exemplo: false

Exemplo

Proxy customizado com fallback interno

{
  "mode": "custom",
  "proxy_url": "http://usuario:senha@proxy-do-cliente.example:8080",
  "proxy_fallback": "internal"
}

Respostas

200Proxy configurado com sucesso

400Payload inválido ou falha na validação do proxy

401Token inválido ou expirado

409Não há proxy alternativo disponível para rotação interna

500Erro interno do servidor ao configurar o proxy

curl -X POST 'https://api.nodinfra.com.br/instance/proxy' \ -H 'token: SEU_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "mode": "custom", "proxy_url": "http://usuario:senha@proxy-do-cliente.example:8080", "proxy_fallback": "internal" }'