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 umidpúblico. O campoproxyda instância passou a ser{ id, city, city_code, masked_ip, assigned_at }(ip_addresseispsó em respostas de superadmin);idsó existe para proxy da própria empresa. O mesmo vale para o blocoproxydeGET /v1/instances/{id}/health. O evento legadoinstance.proxy_changed(rotação de IP gerido pela plataforma) ainda carregaold_ip/new_ipcompletos 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).
{
"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:
{
"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. Amessagediz qual dos dois.
GET/v1/proxies#
{
"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 (amessagediz 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 campoproxy_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.