Proxies do cliente

6.P Proxies do cliente#

No modelo por unidade (seção 23) cada empresa tem os seus próprios proxies: escolhe entre até três ofertas (São Paulo, Rio de Janeiro, Curitiba) e vincula as suas instâncias a eles. Uma instância usa um proxy; um proxy atende quantas instâncias da empresa ela quiser (1:N) — no trial, uma só (1:1).

Regras que valem para todas as rotas:

  • O endereço nunca é entregue completo a um tenant: só mascarado ("200.xxx.xxx.31") e por um id público. O campo proxy da instância passou a ser { id, city, city_code, masked_ip, assigned_at } (ip_address e isp só em respostas de superadmin); id só existe para proxy da própria empresa. O mesmo vale para o bloco proxy de GET /v1/instances/{id}/health. O evento legado instance.proxy_changed (rotação de IP gerido pela plataforma) ainda carrega old_ip/new_ip completos e não é emitido para proxy do cliente.
  • Instância pareada não troca de proxy. O endereço em que a sessão foi pareada é o endereço em que ela vive; para mudar é preciso desparear (logout) e parear de novo. Nada automático troca esse IP.
  • Um proxy só é alocado por intenção: quando a empresa o escolhe, ou automaticamente na primeira tentativa de pareamento (connect) de uma instância sem proxy, se houver vaga. Conta parada não consome IP.
  • Trial: um proxy sem nenhuma instância pareada por 24h é liberado (a empresa pode escolher de novo; o relógio do trial não para).
  • Conta desativada (trial encerrado ou suspensa por falta de pagamento) perde os proxies. Fatura vencida dentro dos 5 dias de tolerância não muda nada.
  • Ninguém além da própria empresa (ou a desativação da conta) libera um proxy dela: rotação automática, auditoria e recuperação por operador não agem sobre proxy do cliente.

Auth: Owner, Admin. Escolher e reservar exigem e-mail verificado.

GET/v1/proxies/offers#

Até uma oferta por cidade (cidade sem estoque não aparece; data pode vir vazio).

json
{
  "data": [
    { "offer_id": "MTIuNy4xNzk0…", "city": "São Paulo", "city_code": "sp", "masked_ip": "200.xxx.xxx.31", "price_cents": 5000 },
    { "offer_id": "MTMuNy4xNzk0…", "city": "Rio de Janeiro", "city_code": "rj", "masked_ip": "201.xxx.xxx.77", "price_cents": 5000 }
  ],
  "entitlement": { "max_proxies": 1, "owned": 0, "available_slots": 1 }
}

offer_id é opaco, vale 30 minutos e só para a empresa que o recebeu. available_slots é quantos proxies a empresa ainda pode escolher sem contratar outra unidade.

POST/v1/proxies/reserve#

Segura a oferta por 30 minutos enquanto a empresa paga a unidade de proxy (o PIX pode demorar). Body { "offer_id": "…" }.

Só para assinatura ativa comprando mais um proxy. A empresa segura uma oferta por vez (reservar outra solta a anterior) e a reserva dura no máximo 60 minutos no total, por mais que seja renovada.

Resposta 200: { "offer_id": "…", "reserved_until": "2026-11-15T19:10:00Z" } Erros: 400 INVALID_OFFER, 409 OFFER_GONE (outro já levou, o IP deixou de estar saudável, ou a reserva atingiu o teto), 409 PROXY_RESERVE_NOT_AVAILABLE (conta em trial ou sem assinatura paga; assinatura em atraso dentro da tolerância ainda pode reservar).

POST/v1/proxies#

A oferta vira um proxy da empresa. Body { "offer_id": "…" }.

Resposta 201:

json
{
  "id": "5b0f5d0e-6c7a-4f1e-9c53-0e3a6c1a2b44",
  "city": "São Paulo", "city_code": "sp", "masked_ip": "200.xxx.xxx.31",
  "health_ok": true, "owned_at": "2026-11-15T18:40:00Z", "instances": []
}

Erros:

  • 400 INVALID_OFFER — oferta malformada, vencida ou de outra empresa.
  • 402 PROXY_ENTITLEMENT_REQUIRED — sem vaga: contrate uma unidade de proxy (POST /v1/billing/subscriptions/{id}/units, seção 23) e tente de novo.
  • 409 OFFER_GONE — a oferta foi levada (ou o IP deixou de estar saudável); carregue as ofertas outra vez.
  • 503 TRIAL_PROXIES_UNAVAILABLE — todas as vagas de proxy para contas que ainda não pagaram estão em uso no momento (há um teto global para elas, e ele conta toda empresa que nunca teve um pagamento confirmado, em trial ou não). Tente mais tarde ou pague a primeira fatura. Não afeta quem já pagou.
  • 429 PROXY_CLAIM_LIMIT — a empresa já pegou 6 proxies nas últimas 24 horas (pegar e devolver também conta), ou ainda não pagou nenhuma fatura e já pegou os 3 proxies permitidos antes do primeiro pagamento. A message diz qual dos dois.

GET/v1/proxies#

json
{
  "data": [
    {
      "id": "5b0f5d0e-…", "city": "São Paulo", "city_code": "sp", "masked_ip": "200.xxx.xxx.31",
      "health_ok": true, "owned_at": "2026-11-15T18:40:00Z",
      "instances": [ { "id": "84c2e480-…", "name": "Vendas", "status": "CONNECTED", "paired": true } ]
    }
  ],
  "entitlement": { "max_proxies": 2, "owned": 1, "available_slots": 1 }
}

DELETE/v1/proxies/{proxyId}#

Devolve o proxy. Resposta 204. Não altera a cobrança: reduzir a unidade é DELETE /v1/billing/subscriptions/{id}/units.

Erros: 404 PROXY_NOT_FOUND, 409 PROXY_IN_USE (ainda tem instâncias).

PUT/v1/instances/{instanceId}/proxy#

Vincula a instância a um proxy da empresa (substitui o vínculo anterior). Body { "proxy_id": "5b0f5d0e-…" }. Resposta 200: o proxy, com as instâncias.

Erros:

  • 404 INSTANCE_NOT_FOUND / 404 PROXY_NOT_FOUND.
  • 409 INSTANCE_PAIRED — a instância está pareada; desconecte com logout para trocar.
  • 409 INSTANCE_CONNECTING — a instância está conectando, ou já iniciou uma conexão neste proxy e pode ter uma sessão do WhatsApp ligada a ele (a message diz qual dos dois). No primeiro caso, desconecte e espere parar. No segundo, desconectar não basta: a instância fica presa ao proxy desde a primeira conexão até um logout concluído com ela conectada (ou até ser apagada), porque um QR pode ter sido lido antes de o número aparecer. A instância informa esse estado no campo proxy_locked: true.
  • 409 INSTANCE_ON_PLATFORM_PROXY — a instância ainda usa um proxy gerido pela plataforma (criada antes de a empresa passar ao modelo por unidade). Apague-a e crie outra para usar um proxy escolhido.
  • 409 TRIAL_ONE_TO_ONE — no trial, o proxy já tem a sua instância.

DELETE/v1/instances/{instanceId}/proxy#

Remove o vínculo. Resposta 204. Mesmas recusas 409 do vínculo.

POST/v1/instances/{instanceId}/connect — proxy#

Para uma empresa no modelo por unidade, uma instância não pareada e sem proxy recebe um automaticamente: um proxy que a empresa já tem ou, havendo vaga, uma oferta disponível.

  • Sem proxy e sem vaga: 409 PROXY_REQUIRED.
  • Instância pareada sem proxy: 409 INSTANCE_PAIRED — nada é vinculado (uma sessão viva não muda de endereço); faça logout, escolha o proxy e pareie de novo.
  • Conta que ainda não pagou, com o teto global atingido: 503 TRIAL_PROXIES_UNAVAILABLE.
  • Limite diário de proxies da empresa atingido: 429 PROXY_CLAIM_LIMIT.

POST /v1/instances/{instanceId}/restart e a conexão feita pelo painel de administração passam pela mesma preparação e devolvem os mesmos erros.

Desde a primeira conexão a instância fica presa a esse proxy (INSTANCE_CONNECTING ao tentar trocar, proxy_locked: true na instância) até um logout concluído com ela conectada, ou até ser apagada.

A partir da primeira conexão o proxy é considerado usado: ao ser devolvido ele é desativado, nunca oferecido a outra empresa.