Fingerprint uTLS Pool (Superadmin)

17.W Fingerprint uTLS Pool (Superadmin)#

Pool de profiles uTLS atribuidos somente a instâncias novas. Instâncias já pareadas nunca são mutadas (sticky-from-creation); a fonte de verdade em runtime continua sendo o campo tenant fingerprint_utls_spec. Built-ins entram como staging; WA Probe e o único gate que promove um profile para active.

GET/v1/admin/fingerprint-pool/profiles#

Retorna todos os profiles uTLS do master DB com status, peso, último probe e estado de burn.

Auth: Superadmin

Resposta 200:

json 
{
  "profiles": [
    {
      "id": 1,
      "name": "safari-mac-17",
      "utls_spec": "HelloSafari_Auto",
      "ja4_hash": "t13d2014h2_a09f3c656075_874d27d7ca63",
      "peetprint_hash": "b2bafdc69377086c3416be278fd21121",
      "user_agent": "Mozilla/5.0 (Macintosh; ...) Safari/605.1.15",
      "status": "active",
      "weight": 10,
      "last_probe_at": "2026-05-08T12:00:00Z",
      "last_probe_result": "ok",
      "last_probe_signal": "qr_emitted",
      "burn_count": 0,
      "created_at": "2026-05-08T00:00:00Z",
      "updated_at": "2026-05-08T12:00:00Z"
    }
  ]
}

Erros: 401 UNAUTHORIZED (sem JWT de superadmin), 503 SERVICE_UNAVAILABLE (tenant manager indisponível), 500 INTERNAL.

PATCH/v1/admin/fingerprint-pool/profiles/{profileName}#

Atualiza campos operacionais de um profile. Permite weight entre 0 e 1000 e status igual a staging, deprecated ou burned. active não e aceito neste endpoint: WA Probe continua sendo o único gate de promoção para active.

Auth: Superadmin

Body:

json 
{
  "status": "deprecated",
  "weight": 3
}

Resposta 200: { "profile": { ...FingerprintUTLSProfile atualizado... } }

Erros:

  • 400 INVALID_FINGERPRINT_PROFILE — nome de profile desconhecido ou legacy
  • 400 ACTIVE_REQUIRES_WA_PROBE — tentou definir status=active (WA Probe e o único gate)
  • 400 INVALID_FINGERPRINT_STATUS — status fora de staging|deprecated|burned
  • 400 INVALID_FINGERPRINT_WEIGHT — weight fora de 0..1000
  • 400 BAD_REQUEST — body sem campos para atualizar
  • 404 FINGERPRINT_PROFILE_NOT_FOUND — profile não existe no master DB
  • 401 UNAUTHORIZED, 503 SERVICE_UNAVAILABLE, 500 INTERNAL

POST/v1/admin/fingerprint-pool/profiles/seed-builtins#

Seed idempotente dos profiles compilados no binario atual. Builtins entram em status staging. Em 2026-05-08 os builtins disponíveis são safari-mac-17, chrome-mac-147 e chrome-win-147.

Auth: Superadmin

Resposta 200: { "ok": true }

Erros: 401 UNAUTHORIZED, 503 SERVICE_UNAVAILABLE, 500 INTERNAL.

POST/v1/admin/fingerprint-pool/profiles/{profileName}/wa-probe/{proxyId}#

Executa um WhatsApp QR Probe descartavel através do proxy selecionado usando o profile uTLS escolhido. Não pareia instância de cliente.

Auth: Superadmin

Path params: profileName (nome do profile uTLS), proxyId (id do IP do pool a usar como egress).

Body: nenhum.

Resposta 200:

json 
{
  "result": { "verdict": "ok", "signal": "qr_emitted", "latency_ms": 9420 },
  "profile": { "...": "FingerprintUTLSProfile atualizado" }
}

verdict=ok em um profile staging promove o profile para active automaticamente (WA Probe e o único gate de promoção). verdict=burned incrementa burn_count.

Erros:

  • 400 INVALID_FINGERPRINT_PROFILE — nome desconhecido ou legacy
  • 400 INVALID_ID — proxyId inválido
  • 404 FINGERPRINT_PROFILE_NOT_FOUND — profile não existe no master DB
  • 409 WA_PROBE_IN_FLIGHT — já existe um WA probe rodando para esse proxy
  • 502 WA_PROBE_FAILED — RPC do probe falhou
  • 503 WA_PROBE_DISABLED — RPC de probe de profile não wired
  • 401 UNAUTHORIZED, 503 SERVICE_UNAVAILABLE, 500 INTERNAL

Metricas relacionadas: biazap_fingerprint_utls_pool_active_size, biazap_fingerprint_utls_assignments_total, biazap_fingerprint_utls_probe_total, biazap_fingerprint_utls_burn_total.

POST/v1/admin/instances/{instanceId}/warmup/bypass#

Concede um bypass temporario do warmup v2 para uma instância especifica. O worker passa a ignorar os gates de warmup_phase, daily cap e janela horaria enquanto a chave Redis do bypass estiver válida.

Auth: Superadmin

Body JSON:

json 
{
  "reason": "sla unblock",
  "ticket_id": "SUP-123",
  "auto_expire_at": "2026-04-22T12:00:00Z"
}

Campos:

  • reason obrigatório.
  • ticket_id obrigatório.
  • auto_expire_at opcional. Quando omitido, a API usa TTL padrão de 24h.

Resposta 200:

json 
{
  "instance_id": "84c2e480-...",
  "token": "0f3f6f15-3fa2-46f0-b7a7-d7790f9e5e36",
  "expires_at": "2026-04-22T12:00:00Z"
}

Notas:

  • O grant grava uma linha em stealth_audit_events com event_type = "warmup.bypass_granted".
  • O bypass e rate-limited por instância no Redis para evitar uso repetitivo sem triagem humana.
  • O valor retornado em token e apenas auditoria/operação; o gate do worker válida a chave Redis por instância.