Como monitorar uma integração de SMS em produção

Integração de SMS falha de um jeito específico: ela não cai, ela piora. O endpoint continua respondendo 200, os pedidos continuam sendo criados, e a taxa de código entregue vai de 90% para 40% ao longo de uma semana. Sem medição, você descobre pelo suporte.

A métrica que importa

Não é uptime. Não é latência. É taxa de conclusão: pedidos que terminaram com código recebido, dividido por pedidos criados.

taxa = pedidos com SMS ÷ pedidos criados

Meça por país e por serviço, separado. A média geral esconde justamente o que você precisa ver: quando uma faixa de numeração é marcada, um par país+serviço despenca enquanto o resto continua bem. Na média, isso vira uma queda de três pontos que ninguém nota.

Se você acompanha o custo por verificação concluída, essa é a mesma métrica pelo outro lado — e é ela que diz se o preço que você paga está de pé.

Quatro sinais, e o que cada um significa

Taxa de conclusão caindo em um par específico. A faixa daquele país para aquele serviço foi marcada. Ação: trocar de país, ou aceitar o custo maior de outra faixa.

Tempo até o primeiro SMS subindo. Rota congestionada. Se a mediana passa dos poucos minutos, seus pedidos vão começar a expirar antes do código chegar. Meça mediana e p95, não média — média some com um pedido de 19 minutos no meio.

Aumento de pedidos expirados. Consequência dos dois anteriores, e o que dói no bolso: cada expiração é um número reservado que não virou nada. Como expirado sem SMS é estornado, isso não aparece como perda de saldo — aparece como uso de tempo e de cota.

429 na sua própria integração. Você está pedindo mais rápido do que o teto permite. Não é falha da plataforma, é retentativa mal calibrada do seu lado.

Instrumentação mínima

Não precisa de stack de observabilidade para começar. Precisa de quatro campos gravados em cada pedido:

await db.verificacao.create({
  data: {
    pedidoId: pedido.id,
    pais: pedido.country.code,
    servico: pedido.service.slug,
    criadoEm: new Date(),
    // preenchidos depois:
    // primeiroSmsEm, desfecho ("codigo" | "expirado" | "cancelado")
  },
});

Com isso você responde, em uma consulta, as perguntas que interessam: qual par está pior esta semana, quanto tempo o código leva, quantos pedidos morrem sem nada.

Guarde pais e servico como colunas próprias, não dentro de um JSON. A diferença aparece no dia em que você quiser agrupar por elas.

Alerta que vale a pena

Alerta bom é o que muda uma decisão. Dois bastam no começo:

Taxa de conclusão abaixo de um piso, num par com volume relevante. Exija volume mínimo na condição — três pedidos falhando em três não é sinal, é acaso.

Nenhum SMS recebido em X minutos, tendo pedidos ativos. Esse pega a falha silenciosa: sua integração parou de processar os eventos e ninguém percebeu, porque nada deu erro.

Alerta de erro 500 é útil, mas não é onde essa integração falha. Ela falha respondendo 200 e não entregando nada.

Onde os eventos entram

Se você recebe os códigos por webhook em vez de consultar em laço, o seu endpoint já é o ponto natural de medição: é ele que sabe a hora exata em que a mensagem chegou. Registre ali o primeiroSmsEm.

Só cuidado com um detalhe: webhook chega pelo menos uma vez, então o mesmo evento pode ser entregue duas vezes. Se você contar cada chegada como um SMS, sua métrica infla sozinha. Trate a idempotência antes de confiar no número.

O painel que resolve 90%

Uma tabela, atualizada por hora:

país	serviço	pedidos	concluídos	taxa	tempo mediano
BR	whatsapp	120	108	90%	40s
BR	telegram	85	34	40%	3m10s

Duas linhas dessas dizem, sem ambiguidade, que o problema é o Telegram no Brasil — e não a plataforma, não a sua chave, não a sua rede. É a diferença entre abrir um chamado com "não está funcionando" e abrir com "esse par caiu de 88% para 40% desde terça".

Na API de números virtuais, os eventos de SMS chegam por webhook ou SSE — são eles que fornecem os horários que alimentam essa tabela.