Consulte o estado da instância antes de enviar mensagens ou investigar uma falha. Na StackZap, a referência documenta GET /v1/instances/{id}/status. Substitua {id} pelo identificador da instância e autentique a chamada com a API Key do ambiente.

curl "$STACKZAP_API_URL/v1/instances/$STACKZAP_INSTANCE_ID/status" \
  -H "X-API-Key: $STACKZAP_API_KEY" \
  -H "Accept: application/json"

Estados durante a conexão

O fluxo pode passar por estados intermediários enquanto o pareamento é concluído. Na documentação da StackZap, qr_pending indica que o QR está aguardando leitura e connecting que o pareamento está em andamento; connected representa uma sessão estabelecida. Consulte a lista da sua versão para os demais estados e o significado exato.

Se a instância estiver aguardando QR, volte ao fluxo de conexão do painel e use um código atual. Se permanecer em conexão, aguarde a atualização e verifique novamente. Quando desconectada, siga a ação de reconectar documentada; evite excluir e recriar a instância sem verificar o impacto nos dados associados.

Use o estado na sua automação

Seu sistema pode fazer uma consulta pontual antes de uma operação importante ou escutar connection.update por webhook. Evite polling excessivo: use intervalos razoáveis e backoff em caso de falha. Diferencie o status HTTP da resposta do estado de negócio retornado no JSON.

Registre o identificador, o estado e o horário da consulta. Não registre API Keys, códigos de pareamento ou QR Code. Para obter a URL certa no Cloud, abra o ambiente correspondente em contas.stacklab.digital; cada ambiente tem endereço próprio.

Confira formatos de resposta e estados disponíveis na referência da API StackZap. Se precisar de ajuda com um caso no Cloud, use o widget de suporte do painel ou fale com a equipe StackZap.

O que o status responde — e o que não responde

O status é uma fotografia do estado reportado pela instância naquele momento. Ele ajuda a decidir se sua aplicação deve apresentar “pronto”, aguardar o pareamento ou iniciar um fluxo de recuperação. Ele não prova, isoladamente, que cada mensagem foi entregue ao aparelho, que uma pessoa leu a conversa ou que todos os serviços downstream estão saudáveis. Para acompanhar uma mensagem específica, use os identificadores e eventos documentados para esse fluxo.

Consulte o estado junto do contexto: ambiente, ID da instância, momento da leitura e operação pretendida. Uma resposta HTTP de sucesso informa que a consulta foi processada; o objeto JSON pode reportar um estado de conexão diferente. Separe esses conceitos na aplicação e mostre uma explicação acionável ao operador em vez de exibir apenas um código interno.

Polling ou webhook

Para uma tela administrativa, uma consulta pontual ao abrir os detalhes pode bastar. Para refletir mudanças contínuas, verifique se o evento de conexão da versão instalada pode ser recebido por webhook. Uma combinação comum é usar webhook para atualização rápida e consulta pontual para reconciliar o estado ao iniciar a aplicação ou após perder eventos.

Evite consultar a cada poucos milissegundos. Polling agressivo aumenta tráfego, ruído de logs e pode esbarrar em limites da API. Defina um intervalo adequado à experiência do produto, pare ou reduza consultas quando a tela não está ativa e aplique backoff em erros temporários. Indique o horário da última atualização para que o operador saiba se vê um estado recente.

Centralize a consulta no backend

async function consultarStatus({ baseUrl, apiKey, instanceId }) {
  const url = `${baseUrl}/v1/instances/${instanceId}/status`;
  const response = await fetch(url, {
    headers: { "X-API-Key": apiKey, "Accept": "application/json" },
    signal: AbortSignal.timeout(10000),
  });
  if (!response.ok) {
    throw new Error(`Falha ao consultar StackZap: HTTP ${response.status}`);
  }
  return response.json();
}

O timeout é uma decisão do cliente e deve se ajustar ao ambiente. Confirme nomes e formato dos campos retornados na documentação. Não exponha a API Key no navegador nem apresente a exceção técnica diretamente ao usuário final.

Apresente estados úteis

Se a API reportar que está aguardando QR, ofereça uma instrução para abrir o fluxo de pareamento. Se estiver conectando, mostre que há uma operação em andamento e atualize depois de um intervalo razoável. Se conectado, permita a operação prevista. Se desconectado ou em erro, explique que o envio pode falhar e ofereça diagnóstico, sem repetir a mesma chamada.

O mapeamento para rótulos deve ser conservador. Se surgir um estado desconhecido numa atualização, exiba “estado não reconhecido” e impeça ações que exijam conexão confirmada. Não traduza valor desconhecido para “conectado” por padrão. Preserve o valor original em log restrito e atualize a aplicação após confirmar o contrato da nova versão.

Armazene o histórico mínimo

Guardar mudanças pode ajudar a explicar oscilações: momento, estado anterior, estado novo, origem (consulta ou webhook) e identificador da instância. Evite armazenar resposta completa se ela contém campos desnecessários. Defina retenção e acesso para esses registros. Para auditoria, inclua ID de ambiente e evento, nunca credenciais.

Se recebe webhook e executa polling, os eventos podem chegar duplicados ou fora de ordem. Compare timestamps e use transições válidas. Uma consulta posterior pode confirmar o estado atual, mas não deve apagar o histórico de uma desconexão que causou falha. Separe o estado atual, que serve para a interface, do histórico de ocorrências.

Status desconectado: próximos passos

Confirme se o celular continua vinculado e se a sessão não foi encerrada no aplicativo. Consulte novamente após uma pausa, verifique a conexão de rede e examine o fluxo de reconexão. Se houver QR pendente, gere um código atual e conclua o pareamento. Se o estado mudar repetidamente, registre a sequência e pause automações sensíveis até entender a causa.

Não exclua e recrie a instância como primeiro recurso. A identidade dela pode estar referenciada por webhooks, filas, CRM ou banco do seu sistema. Confirme com documentação ou suporte se qualquer ação de reset afeta dados e associações. No self-hosted, o operador deve validar logs, recursos e conectividade dos serviços sob seu controle.

Segurança e privacidade

Consulte o status no servidor, onde a chave está protegida. Se um painel web precisa mostrar a situação, faça uma chamada ao seu backend com controle de usuário e permita consultar somente instâncias autorizadas. Não inclua domínio privado, chave ou resposta crua em HTML público. Registre quem iniciou uma ação de reconexão quando isso for relevante para auditoria.

Checklist de consulta

  • URL, chave e ID pertencem ao mesmo ambiente.
  • Requisição usa HTTPS e acontece no backend.
  • Resposta HTTP é separada do estado de negócio.
  • Valores desconhecidos são tratados de forma segura.
  • Polling tem intervalo e backoff razoáveis.
  • Eventos e consultas são reconciliados sem perder histórico.
  • A interface indica o momento da última atualização.
  • Logs registram contexto suficiente sem segredos ou dados excessivos.

Evite corridas entre consulta e ação

O status pode mudar entre a leitura e a chamada seguinte. Sua aplicação deve tratar a consulta como uma indicação recente, não como uma trava que garante a operação futura. Se o endpoint de envio responder que a instância se desconectou, atualize o estado e apresente uma ação adequada. Evite executar comandos destrutivos baseados num status que já ficou antigo.

Para tarefas concorrentes, mantenha uma única rotina de atualização por instância ou use cache curto compartilhado, com invalidação ao receber evento de conexão. Não permita que várias abas façam polling de alta frequência em paralelo. A aplicação pode consolidar a consulta no backend e transmitir o estado atualizado à interface.

Cuide dos limites e do cache

Se vários operadores abrem o mesmo painel, sincronize consultas para que cada tela não multiplique a carga. Use um intervalo proporcional à necessidade da operação e um tempo de expiração claro. Ao receber um webhook, invalide ou atualize o cache da instância; ainda assim, reconcilie periodicamente para recuperar eventos perdidos.

Não cacheie uma resposta de erro de autenticação como se fosse desconexão. Distinga falha da chamada de API, indisponibilidade de rede e estado da instância. Na interface, mostre “não foi possível consultar” se a consulta falhou e reserve “desconectada” para um estado efetivamente retornado pela API. Essa distinção evita que o usuário inicie pareamento desnecessário durante uma falha de rede.

Faça uma reconciliação ao iniciar

Quando seu worker ou backend reiniciar, consulte o estado atual das instâncias relevantes e compare com o último estado persistido. Se houve evento perdido durante a indisponibilidade, a consulta recupera a visão atual. Registre que houve reconciliação, não finja que observou cada transição intermediária. Se uma desconexão pode ter afetado mensagens, revise também jobs e callbacks associados.

Ao remover uma instância, retire seu monitor da rotina e mantenha histórico mínimo para correlacionar eventos antigos. Se o ID voltar a aparecer num ambiente diferente, não o trate como recurso antigo sem confirmar a associação. IDs devem ser escopados pelo ambiente.

Instrumente o estado para suporte

Um bom diagnóstico inclui o estado reportado, momento da consulta, status HTTP, duração e identidade do ambiente. Compare o painel com a API somente depois de confirmar URL e instância. Se os dois divergem, registre o horário de cada leitura, pois uma atualização entre elas pode explicar a diferença. Não compartilhe API Key ou QR code para reproduzir.

Para self-hosted, inclua versão e logs sanitizados da aplicação. Para Cloud, forneça nome do ambiente e ID da instância ao widget de suporte. Essa informação é suficiente para começar sem expor dados de contato. Em ambos os formatos, evite enviar screenshots que mostrem credenciais ou outras conversas.

Use uma resposta de status como contrato de interface

Mapeie os campos documentados para uma representação interna estável, por exemplo connectionState, lastCheckedAt e canSend. O valor original continua disponível para diagnóstico, mas a interface não precisa conhecer cada detalhe da API. Quando o schema mudar, atualize o adaptador num lugar só e mantenha a tela funcionando de modo seguro.

Não derive canSend apenas de uma string parcial ou de uma busca por palavra no texto da resposta. Use o campo estruturado documentado e uma lista explícita de estados aceitos como conectados. Se a resposta não contém o campo esperado, mostre indisponibilidade de consulta e alerte a equipe. Esse tratamento evita falso positivo causado por uma resposta HTML de proxy ou erro.

Casos de teste para seu monitor

Cubra estado conectado, desconectado, QR pendente, resposta desconhecida, timeout, 401, erro de rede e corpo inválido. Verifique que cada caso produz uma mensagem adequada e que nenhum erro técnico é rotulado como desconexão. Teste também duas consultas concorrentes e uma notificação webhook seguida de consulta de reconciliação.

Se o painel for compartilhado, confirme que um operador sem acesso à instância não consegue consultar seu estado pela API do seu backend. A chave StackZap não substitui autorização do seu produto. O controle de acesso precisa ser verificado para cada ID solicitado.

Alerta sem excesso de notificações

Uma oscilação curta pode produzir muitas mudanças de estado. Agrupe eventos próximos e notifique quando a indisponibilidade persistir por uma janela definida pela sua operação. Envie nova notificação quando houver recuperação confirmada ou quando o incidente mudar de gravidade, em vez de alertar a cada consulta.

Inclua no alerta nome lógico da instância, ambiente, estado e horário da última atualização. Não inclua chave nem conteúdo de conversa. Forneça um link para o painel autorizado e um procedimento simples para confirmar estado e iniciar reconexão. A pessoa de plantão deve saber se pode agir ou se precisa escalar.

Revise limiares depois de observar a operação por um período real. Um limite muito baixo gera alertas por oscilações normais; um limite alto atrasa a resposta. Registre o tempo de indisponibilidade detectada e o tempo até recuperação para ajustar a política. Não transforme a média observada em garantia de disponibilidade.

Documente esses limiares junto do canal de plantão e atualize quando a criticidade do número mudar. Para uma conexão de demonstração, pode bastar uma notificação ao responsável; para atendimento essencial, talvez seja necessário um escalonamento. Em ambos os casos, baseie a regra no impacto e na capacidade da equipe de agir.

Inclua a consulta de status no fluxo de suporte: peça ao operador que informe o ambiente, instância, horário e valor retornado, sem enviar credenciais. Se houver divergência entre painel e API, repita a consulta após um intervalo curto e registre ambos os horários. Uma diferença pode refletir atualização entre leituras. Não apague ou recrie a instância apenas para alinhar uma tela; primeiro confirme o estado real pela referência técnica.