Chips

Endpoints pra criar, parear, listar, reconectar e excluir chips. Todos exigem admin key.

Estados

pairing → connected → (disconnected ↔ connected) → logged_out | banned

• pairing — chip criado, aguardando QR ser escaneado / pairing code digitado
• connected — socket Baileys ativo
• disconnected — caiu, mas pode reconectar (transient)
• logged_out — usuario removeu o aparelho do WhatsApp OU sessao corrompida
• banned — detector automatico identificou ban

POST /v1/chips

Cria chip e inicia pareamento.

POST /v1/chips
Authorization: Bearer ADMIN_KEY
Content-Type: application/json

{ "label": "Chip Vendas SP" }

201 Created:

{
  "id": "01HZTQCHIP01...",
  "label": "Chip Vendas SP",
  "status": "pairing",
  "qr_url": "/v1/chips/01HZTQCHIP01.../qr"
}

GET /v1/chips

Lista todos (sem paginacao — tipico ate centenas de chips).

{
  "data": [
    {
      "id": "...",
      "label": "Chip Vendas",
      "phone_number": "5511999998888",
      "status": "connected",
      "last_connected_at": "2026-04-30T10:00:00Z",
      "last_disconnected_at": null,
      "disconnect_reason": null,
      "daily_message_limit": 200,
      "messages_sent_today": 47,
      "is_active": true,
      "created_at": "...",
      "updated_at": "..."
    }
  ]
}

GET /v1/chips/:id

Mesmo schema do item da lista.

GET /v1/chips/:id/qr

Pega QR codes pra parear. So funciona em chip com status=pairing (409 caso contrario).

{
  "qr": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2026-04-30T10:01:00Z"
}

QR atualiza a cada 20s automaticamente. Se voce fizer refresh do GET, retorna o QR mais recente (mesmo expires_at se nao expirou ainda).

POST /v1/chips/:id/pair-code

Gera codigo de 8 chars (ABCD-EFGH) pra parear no proprio celular sem precisar de QR — alternativa pratica quando voce esta sem PC.

POST /v1/chips/01HZTQ.../pair-code
Authorization: Bearer ADMIN_KEY
Content-Type: application/json

{ "phone_number": "5511999998888" }

200 OK:

{
  "code": "ABCD-EFGH",
  "phone_number": "5511999998888",
  "expires_at": "2026-04-30T10:01:00Z"
}

No celular: WhatsApp → Aparelhos conectados → Conectar com numero de telefone → digita o codigo. ADR 014.

POST /v1/chips/:id/reconnect

Reabre o socket Baileys reusando a sessao existente. Nao apaga creds. Use quando o socket ficou em estado fantasma (kill -9 anterior, hub reiniciado sem graceful shutdown).

200 OK retorna o chip apos reconnect (status provavelmente ainda connected ou pairing).

POST /v1/chips/:id/repair

Apaga sessao Baileys do disco/MinIO e gera novo QR. Preserva:

• ID do chip
• label
• Vinculos app_chip_access
• Historico de messages
• Trilha de audit_events
• Eventos chip_events

Usar quando reconnect nao funciona (sessao realmente corrompida) ou voce quer trocar o numero pareado.

202 Accepted:

{
  "id": "...",
  "label": "...",
  "status": "pairing",
  "qr_url": "/v1/chips/.../qr"
}

DELETE /v1/chips/:id

Logout + apaga chip do DB (cascade em mensagens, eventos, vinculos).

Irreversivel. Audita em audit_events antes de remover.

204 No Content.

Tabela rapida

Metodo	Path	Status final	Quando usar
POST	/v1/chips	201	criar novo chip
GET	/v1/chips	200	listar
GET	/v1/chips/:id	200	detalhe
GET	/v1/chips/:id/qr	200 | 409	pegar QR (so em pairing)
POST	/v1/chips/:id/pair-code	200 | 409	codigo de pareamento
POST	/v1/chips/:id/reconnect	200	reabrir socket
POST	/v1/chips/:id/repair	202	apagar sessao + QR novo
DELETE	/v1/chips/:id	204	excluir