A fila de envio da StackZap permite enfileirar mensagens de texto e consultar os jobs associados a uma instância. Ela é útil quando sua aplicação precisa desacoplar a solicitação do envio e acompanhar o processamento sem bloquear uma requisição web até o fim.

Um envio passando pela fila
  1. 01Aplicação cria o job
  2. 02StackZap registra a solicitação
  3. 03Worker processa a mensagem
  4. 04Sua aplicação acompanha o estado

Endpoints documentados

A referência da API descreve POST /v1/instances/{id}/send-queue/text para incluir texto na fila e GET /v1/instances/{id}/send-queue para consultar jobs e contagens. Há também uma operação para cancelar um job pelo ID. Use a credencial da instância e confira os campos e estados aceitos na documentação da versão atual.

curl -X POST "$STACKZAP_API_URL/v1/instances/$STACKZAP_INSTANCE_ID/send-queue/text" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $STACKZAP_API_KEY" \
  -d '{"to":"[email protected]","text":"Mensagem de teste autorizada"}'

Acompanhe antes de repetir

Guarde o identificador retornado pelo endpoint e consulte a fila para acompanhar o job. Uma solicitação ainda pendente não significa automaticamente falha; repetir sem verificar pode gerar conteúdo duplicado. Se precisar interromper um envio, use a operação de cancelamento enquanto o job permitir a ação e confirme o resultado da API.

Na instalação própria, o ritmo de processamento depende dos recursos e da configuração que você administra. No Cloud, consulte o plano e os limites comerciais atuais. A fila organiza o trabalho, mas não transforma a resposta de aceitação em confirmação de entrega ou leitura pelo destinatário.

Consulte os endpoints e estados atuais na referência da API StackZap.

O que a fila resolve

Uma fila separa o momento em que seu sistema registra a intenção de enviar do momento em que o worker processa a operação. Isso é útil quando uma requisição web não deve esperar pelo envio ou quando a aplicação precisa acompanhar pendências. A fila não decide se a mensagem é adequada, não elimina a autenticação e não confirma que o destinatário recebeu ou leu o conteúdo.

Defina a fonte de verdade do evento de negócio no seu sistema. O cliente registra uma solicitação, seu backend valida as regras e então cria um job. Mantenha um identificador interno que relacione pedido, mensagem e job StackZap. Se o endpoint aceitar a solicitação mas a resposta se perder, sua aplicação precisa reconhecer que o resultado pode ser incerto antes de criar outro job.

Campos e formato do destino

O exemplo inicial usa um JID ilustrativo; os formatos aceitos devem ser confirmados na documentação e dependem da operação. Não monte IDs manualmente com base em suposições. Normalize e valide o destinatário no seu sistema e mantenha uma relação rastreável com o contato. Teste com destino autorizado antes de ativar uma fila de produção.

Armazene texto, finalidade, destinatário, ambiente e prazo de validade conforme sua política. Evite colocar dados sensíveis em metadados que apareçam em logs de worker. Uma mensagem pode perder sentido com o tempo: um aviso de cancelamento ou confirmação atrasada deve ser reavaliado antes do processamento.

Estados e transições

Consulte os valores exatos documentados para a versão instalada. Aplicações geralmente precisam diferenciar trabalho aguardando processamento, ativo, concluído, cancelado e falho, mas esses rótulos não devem ser inventados no parser. Quando surgir um estado desconhecido após atualização, mantenha o job visível para diagnóstico e não conclua sucesso automaticamente.

O estado muda. Uma consulta pode mostrar pendente e, logo depois, o worker pode marcar concluído. A interface deve indicar horário da consulta e atualizar com intervalo razoável. Não faça polling acelerado para cada job nem transforme listas grandes em chamadas individuais sem paginação ou limite documentado.

Cancelamento e expiração

Cancelar um job só é útil enquanto a operação ainda não avançou para um estado que permita interrupção. Confira a resposta do endpoint e consulte o estado quando apropriado. Não informe que a mensagem foi cancelada apenas porque o botão foi clicado; confirme o resultado retornado.

Sua aplicação também pode ter prazo de validade próprio. Se a ação perdeu sentido, interrompa novos retries e marque a decisão. Não delete o histórico do job: retenha o mínimo necessário para auditoria e suporte. Diferencie cancelamento solicitado pelo operador, expiração de negócio e falha técnica.

Retry sem duplicidade

Uma falha de rede durante a criação do job não revela se a StackZap recebeu a requisição. Salve uma intenção local antes de chamar e use um identificador de negócio estável. Se a resposta não chegar, procure o job correspondente por mecanismo documentado antes de reenviar. Se não houver busca inequívoca, marque como resultado_incerto para reconciliação humana ou regra segura.

Não repita automaticamente erros permanentes, como autenticação, instância inexistente ou dados inválidos. Para falhas temporárias, use backoff, máximo de tentativas e limite de concorrência. Uma fila interna pode acumular mensagens; monitore o tempo de espera e suspenda produtores quando a idade ultrapassar o limite de negócio.

Planeje a desconexão

Se a instância ficar desconectada, decida se os jobs devem aguardar, expirar ou ser cancelados. Configure sua aplicação para evitar que workers repitam operações em alta velocidade. Depois do pareamento, retome gradualmente e reconcilie jobs que estavam em processamento durante a queda. A fila StackZap e a fila do seu próprio sistema são camadas distintas; documente qual delas guarda cada estado.

Métricas úteis

Acompanhe jobs por estado, idade do mais antigo, taxa de erro, cancelamentos, retries e tempo entre criação local e conclusão. Segmente por ambiente e instância sem expor conteúdo. Um painel ajuda a perceber congestionamento antes que usuários vejam atrasos. Defina retenção para jobs antigos e evite consultas sem filtro se o endpoint oferece paginação.

Checklist de implantação

  • Evento de negócio validado antes de criar o job.
  • Instância, ambiente e destinatário correspondem ao registro correto.
  • ID do job é armazenado para acompanhar o processamento.
  • Timeout é tratado como resultado incerto.
  • Retentativas usam backoff e regras de deduplicação.
  • Cancelamento é confirmado consultando o estado permitido.
  • Jobs antigos expiram conforme finalidade e contexto.
  • Desconexão controla workers e não duplica mensagens.
  • Métricas mostram idade, falhas e volume por instância.
  • Logs não expõem chave, telefone completo ou conteúdo desnecessário.

Modele o estado na sua aplicação

Não dependa de uma consulta à fila para saber por que uma mensagem existe. Armazene um registro local com identificador de negócio, ID do job, instância, horário de criação e estado local. Separe “solicitado pelo usuário” de “aceito pela API” e “processado segundo o estado retornado”. Essa trilha ajuda a resolver disputa sobre duplicidade sem guardar mais conteúdo do que o necessário.

Defina transições válidas no seu código. Um job concluído não deve voltar a pendente porque uma resposta antiga chegou depois. Use timestamp ou versão do registro para não aplicar estado fora de ordem. Estados desconhecidos devem ficar numa fila de revisão e gerar alerta controlado, não desaparecer da interface.

Escolha entre fila StackZap e fila da aplicação

A fila da StackZap atende aos endpoints e workers do produto. Uma fila própria pode oferecer controle de prioridade, agendamento, política de expiração e integração com seu domínio. As duas camadas podem coexistir, mas é necessário saber quem é responsável pelo retry e pelo estado final. Se ambas repetirem a mesma requisição sem coordenação, o resultado pode ser envio duplicado.

Documente o caminho: pedido entra na fila interna, worker chama o endpoint StackZap, job é registrado e seu sistema acompanha o ID. Se o worker cair depois da resposta, a fila interna pode tentar de novo; use um controle local para consultar o job existente antes de criar outro. Não assuma que o produto fornece uma garantia de exactly-once sem contrato explícito.

Prioridade e justiça entre tarefas

Se há diferentes finalidades, defina prioridades sem permitir que uma campanha grande bloqueie notificações operacionais importantes. Limite concorrência e distribua lotes. Respeite termos e cotas; não use rotação entre instâncias para contornar limites. Uma fila crescente deve levar a uma decisão de capacidade, priorização ou pausa, não a uma rajada maior.

Mantenha ordem por conversa quando o contexto exigir, mas não imponha ordenação global se isso atrasar todos os destinatários. Uma operação de alto volume pode particionar filas por instância ou tipo, desde que a documentação e seu plano permitam. Observe a latência por partição para identificar gargalos.

Reprocessamento operacional

Crie uma tela ou comando restrito para reprocessar jobs em falha, mostrando motivo, tentativas e possível estado incerto. Exija justificativa e registre quem solicitou a ação. Antes de reprocessar, confira se o efeito original ocorreu. Reprocessar um evento de webhook ou uma solicitação de envio são operações diferentes e devem ter controles distintos.

Uma fila de falhas precisa de procedimento de revisão: corrigir dados inválidos, renovar configuração, reconectar instância ou marcar como cancelado. Evite retries automáticos para sempre. Defina quando mover para dead letter, quanto tempo reter e quem analisa os itens.

Teste volume sem afetar contatos

Faça teste de carga com endpoints de leitura ou ambiente de homologação, e use números sob controle da equipe para qualquer envio. Aumente concorrência gradualmente e monitore latência, respostas, uso de recursos e idade da fila. Não faça teste de estresse em número de cliente ou infraestrutura compartilhada sem autorização e limites claros.

Simule worker reiniciando, API indisponível e webhook atrasado. Confirme que os jobs persistem, que duplicatas são tratadas e que a equipe consegue retomar o processamento. Esses cenários demonstram resiliência melhor do que uma única chamada bem-sucedida.

Exemplo de política de expiração

Uma confirmação de cadastro pode continuar válida enquanto o registro existir; um lembrete de horário pode expirar depois do compromisso; um código temporário deve ser descartado quando perde validade. A fila técnica não conhece essas regras de negócio por conta própria. Inclua prazo e finalidade no seu job local e verifique-os imediatamente antes da chamada de envio.

Se um item expirar, marque o motivo e evite chamar a StackZap. Se a pessoa ainda precisa da informação, gere uma nova mensagem a partir do estado atual do negócio, em vez de reenviar texto antigo. Isso evita mensagens fora de contexto depois de uma indisponibilidade longa.

Apresente a fila para operadores

Mostre estado, horário, tentativas, instância e ação permitida. Um botão “tentar novamente” deve explicar que pode duplicar se o resultado anterior estiver incerto e pedir confirmação ou executar checagem de reconciliação. Não mostre texto integral a todos os perfis; use acesso conforme função e masque destinatários.

Registre quem cancelou ou reprocessou um job e a justificativa operacional. Esses controles ajudam a distinguir falha automática de intervenção humana. Para filas grandes, ofereça filtros por estado e período, paginação e busca por ID interno sem disparar consulta para cada linha.

Defina níveis de observabilidade

No painel técnico, mostre contagem por estado, idade do job mais antigo, falha recente e taxa de retry. Para atendimento, apresente uma explicação curta e ação autorizada. Para auditoria, mantenha histórico de transições com usuário ou worker responsável. Essas três visões podem usar a mesma fonte, mas não precisam expor os mesmos dados a todos.

Alertas devem apontar para uma condição tratável. Por exemplo: “fila de produção atrasada acima do limite” com ambiente, instância e link para jobs sanitizados. Evite uma notificação por item falho. Agrupe, mantenha o evento original e mostre uma contagem para que a equipe investigue padrão antes de abrir cada registro.

Estabeleça critérios de conclusão

Documente o que sua aplicação considera concluído: job processado, operação aceita, evento de status recebido ou outro sinal definido pela API. Use termos precisos na interface e nos relatórios. Se a API só confirma que a solicitação foi registrada, não apresente o job como mensagem entregue. Essa diferença evita métricas de sucesso que não representam a experiência do destinatário.

Quando revisar desempenho da fila, acompanhe percentis de espera e quantidade de tarefas antigas, não somente a média. Alguns jobs podem ficar presos enquanto a maioria termina rápido. Segmente por instância e finalidade para encontrar gargalos sem abrir texto e telefone dos destinatários.

Faça a fila sobreviver a reinícios

Se sua aplicação mantém uma fila própria, grave jobs em armazenamento durável e recupere o trabalho pendente quando o worker reiniciar. Marque o início da tentativa e use um mecanismo que impeça dois workers de processarem o mesmo registro ao mesmo tempo. Ainda assim, um processo pode cair depois de chamar a StackZap; por isso, preserve o ID e trate o resultado como incerto até reconciliar. Não confie somente numa lista em memória para mensagens importantes.