Como enviar SMS com Node.js pela API do Mandaí

1. Prepare uma chave Sandbox no backend

Crie sua conta, selecione Sandbox e gere uma chave com messages:send e messages:read. Guarde-a na variável de ambiente MANDAI_API_KEY. Execute o exemplo no servidor; nunca exponha essa chave no React, no navegador ou no repositório.

2. Envie uma intenção com fetch

Salve como enviar-sms.mjs e execute node enviar-sms.mjs com a variável de ambiente configurada. Preserve a mesma chave de idempotência e o mesmo corpo ao repetir esta intenção após um timeout. Para um novo evento de negócio, use outra chave.

const apiKey = process.env.MANDAI_API_KEY;
if (!apiKey) throw new Error('Configure MANDAI_API_KEY');
const baseUrl = 'https://sandbox.api.mandaionline.com';

const response = await fetch(baseUrl + '/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiKey,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'tutorial-order-123-confirmation',
  },
  body: JSON.stringify({
    to: '+5511000000001',
    body: 'Pedido confirmado',
  }),
});
if (!response.ok) throw new Error('Envio recusado: HTTP ' + response.status);
const { data } = await response.json();
console.log('Mensagem aceita:', data.message_id);

const statusResponse = await fetch(
  baseUrl + '/v1/messages/' + encodeURIComponent(data.message_id),
  { headers: { Authorization: 'Bearer ' + apiKey } },
);
if (!statusResponse.ok) throw new Error('Consulta recusada: HTTP ' + statusResponse.status);
const result = await statusResponse.json();
console.log('Estado atual:', result.data.status);

3. Diferencie aceitação de entrega

A consulta imediata pode retornar queued: o processamento é assíncrono. Acompanhe a mensagem no console ou receba webhooks para observar a evolução. delivered representa um recibo positivo; unknown significa que não há conclusão suficiente e não deve provocar outro envio automático.

Em falhas de rede, preserve a intenção antes de repetir. Não gere uma nova Idempotency-Key para contornar timeout ou indisponibilidade.

4. Prepare a passagem para Produção

Valide assinatura e duplicidade dos webhooks, exercite destinos determinísticos de falha e atraso e confira o preview de segmentos. Para enviar a destinatários reais, configure uma chave de Produção e capacidade mensal ativa, seguindo os primeiros passos da documentação.