Criar e parear uma instância

Criar

curl -X POST -H "Authorization: Bearer <ADMIN_TOKEN>" -H "Content-Type: application/json" \
  -d '{"name":"minha-instancia"}' \
  https://sua-instancia.exemplo/instance/init

Devolve a instância criada com o token — esse token só aparece aqui (ou numa rotação futura, POST /instance/{id}/rotate-token). Guarde-o: nenhuma listagem devolve segredo.

Um admin pode passar "ownerId" para já criar em nome de outro usuário; um usuário comum que criar para si mesmo está sujeito à própria cota (users.maxInstances) — ultrapassar o limite falha.

Parear por QR

curl -X POST -H "Authorization: Bearer <ADMIN_TOKEN>" \
  https://sua-instancia.exemplo/instance/{id}/connect

curl -H "Authorization: Bearer <ADMIN_TOKEN>" \
  https://sua-instancia.exemplo/instance/{id}/qr.png -o qr.png

connect pareia (primeira vez) ou reconecta (sessão já existente). qr.png devolve o QR atual como imagem PNG — confirmado ao vivo: enquanto a instância já está conectada, a rota devolve 404 (não há QR pendente); ela só tem conteúdo durante a janela de pareamento.

Consultar status

curl -H "Authorization: Bearer <ADMIN_TOKEN>" \
  https://sua-instancia.exemplo/instance/{id}/status

Shape real (confirmado contra uma instância conectada):

{
  "id": "1e28a49b-...",
  "name": "minha-instancia",
  "status": "connected",
  "desiredState": "connected",
  "deviceJid": "55...@s.whatsapp.net",
  "mode": "sandbox",
  "allowlist": ["55..."],
  "minIntervalS": 60,
  "dailyCap": 15,
  "createdAt": "2026-10-21T13:29:53Z"
}

deviceJid só aparece depois de parear. GET /instance/all devolve a mesma forma para todas as instâncias que o chamador enxerga (admin vê todas; usuário comum só as próprias) — sempre exige autenticação apesar do nome “sem token” no changelog interno referir-se a “a resposta nunca inclui o token da instância”, não a dispensar login.

Encerrar sessão

curl -X POST -H "Authorization: Bearer <ADMIN_TOKEN>" \
  https://sua-instancia.exemplo/instance/{id}/logout

Desloga do WhatsApp mas mantém o registro da instância (ela continua existindo, só sem sessão ativa — pode reconectar depois). Para apagar a instância de vez, DELETE /instance/{id} (soft delete).

Quem pode acessar qual instância

Toda rota com :id exige dono ou admin. Quem não é nem dono nem admin recebe 404, nunca 403 — isso é deliberado: devolver 403 confirmaria que a instância existe, mesmo sem acesso a ela (anti-enumeração). Confirmado ao vivo: pedir o status de um id que não existe no banco também devolve 404 — o mesmo código, então não dá para distinguir de fora “não existe” de “existe mas não é seu”.