Pareamento

Esta página mostra o pareamento do lado do app: rotas, estados e eventos. O lado do provedor (WAHA com GOWS, sessões, proxies, código por número) está em Instances → Pareamento.

Antes de parearCopy Anchor Link

O pareamento só abre quando tudo isto vale (assertPairingAllowed e startPairing):

GET /seats/{uid}/consent responde pairingAllowed e blockedBy antes de você tentar. GET /seats/{uid}/channels lista os canais da vaga com o pareamento de cada um.

Dois caminhosCopy Anchor Link

1. Código no celular da pessoa (D3, o caminho principal). Depois do sim, a própria página de consentimento chama POST /consent-requests/{token}/pairing e mostra um código de 8 caracteres. A pessoa digita em WhatsApp → Aparelhos conectados → Conectar com número de telefone. O código nunca aparece pros responsáveis: no app deles, o desafio chega como { kind: "code_on_dependent_phone", expiresAt }, e a tela diz que a pessoa está digitando o código. A página da pessoa acompanha por GET /consent-requests/{token}/events (veja Tempo real).

2. QR na tela do responsável. Pra quando estão juntos:

• POST /seats/{uid}/pairing com { method: "qr" } abre um pareamento novo (só owner);
• POST /seats/{uid}/pairing/challenge?method=qr assume um pareamento que estava no código da pessoa: mesma sessão, QR nesta tela, e o código para de valer. Depois que alguém já digitou ou escaneou, responde 422 PAIRING_NOT_SWITCHABLE.

Sem ?method, a mesma rota busca um QR ou código novo sob demanda. Os workers também renovam sozinhos e empurram por SSE (pairing.challenge). O { method: "code" } do responsável ainda existe (mostra o código pra ele), mas o redesign não usa.

EstadosCopy Anchor Link

stateDiagram-v2
  [*] --> starting
  starting --> challenge: QR ou código chegou
  challenge --> passkey: WhatsApp pede pra conferir o número
  passkey --> challenge: desafio novo
  challenge --> connecting: código digitado ou QR lido
  passkey --> connecting: a pessoa disse que bate
  connecting --> paired: número confirmado
  connecting --> cancelled: outro número conectou
  passkey --> cancelled: a pessoa disse que não bate
  challenge --> cancelled: códigos esgotados ou recomeço
  challenge --> disconnected: o desafio falhou
  paired --> degraded: caiu
  degraded --> paired: reconectou
  degraded --> disconnected: a 3ª tentativa falhou
  paired --> revoked: desvinculado, parada ou reset
  cancelled --> [*]
  disconnected --> [*]
  revoked --> [*]

Qualquer pareamento aberto também pode terminar em revoked (desvincular, parada pela pessoa, reset no backoffice); o diagrama mostra só a partir de paired pra não poluir.

Quando cai, o worker tenta de novo três vezes, esperando mais a cada vez. A 3ª tentativa sai cerca de 12 min e meio depois da queda; se ela também falhar, o pareamento vai pra disconnected e o responsável recebe a notificação crítica:

GET /seats/{uid}/pairing devolve o pareamento aberto. Depois de conectar, GET /seats/{uid}/pairing/avatar serve a foto de perfil da própria pessoa (bytes, 404 se não houver: use as iniciais). Foto de contato nunca é servida, porque essas pessoas não consentiram.

const { data: pairing } = await api(
  `/seats/${seatUid}/pairing`,
  {
    method: "POST",
    body: JSON.stringify({ channel: "whatsapp", method: "qr" }),
  },
  token,
);
render(pairing.challenge); // pode vir null: o QR chega por SSE

source.addEventListener("event", (e) => {
  const ev = JSON.parse(e.data);
  if (ev.seatUid !== seatUid) return;
  if (ev.type === "pairing.challenge") render(ev.payload.challenge);
  if (ev.type === "pairing.paired") done();
  if (ev.type === "pairing.status")
    showStatus(ev.payload.status, ev.payload.nextRetryAt);
});

FontesCopy Anchor Link

• backend/src/http/routes/channels/pairing.route.ts, enable.route.ts, schemas.ts
• backend/src/http/routes/consents/pairing.route.ts
• backend/src/domains/channels/use-cases/start-pairing.ts, dependent-pairing.ts, refresh-challenge.ts, confirm-passkey.ts, apply-provider-state.ts, cancel-pairing.ts, capture-avatar.ts
• backend/src/domains/subscriptions/use-cases/start-trial.ts
• Notas da frente k-pairing (k-pairing-api.md)
• .specs/features/redesign/api-gaps.md (G-23, G-26)
• AD-010, AD-019 (D3)