Migre o seu tráfego de SMS para BroadNet, independentemente do fornecedor.

Mapeie a sua API atual para BroadNet

A maioria API de SMS partilha os mesmos conceitos básicos, embora com nomes diferentes. Encontre o conceito na primeira coluna, seja qual for o nome que o seu fornecedor lhe dê, e use o equivalente BroadNet. Os nomes dos campos são exatamente como aparecem na especificação OpenAPI.

Aqui está o mesmo envio como uma única solicitação. Substitua os campos de remetente, destinatário e texto do seu fornecedor por senderId, destinationNumber e message :

curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "ACME",
    "destinationNumber": "447700900101",
    "message": "Your code is 8123",
    "messageType": "TEXT"
  }'

# 200 OK — the response body is the message ID, e.g. 2603121407537573731

Para verificar uma mensagem, consulte o seu estado com o ID da mensagem que a solicitação de envio devolveu:

# Status lookup on the legacy HTTP API (/websmpp), by message ID
curl "https://api.broadnet.me/websmpp/websmsstatus?respid=2603121407537573731&format=json" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

# "status": "DELIVRD"   (or UNDELIV, EXPIRED, REJECTD)

Mova os seus IDs de remetente

Os IDs de remetente alfanuméricos e os códigos curtos são geralmente portáteis, sujeitos às regras de registo de cada operadora e regulador. Um registo está vinculado à rota que o seu tráfego percorre, portanto, planeie-o antes que qualquer mensagem de produção seja enviada para a BroadNet.

1. 1

   Liste todos os IDs de remetente, os países para os quais enviam e o tipo de tráfego que transportam: OTP, transacional ou de marketing.

2. 2

   Verifique as regras de cada país. Nos Emirados Árabes Unidos, os IDs de remetente são registados de acordo com as regras TDRA por meio da operadora, sendo um ID por entidade legal por caso de uso. Na Arábia Saudita, eles precisam da aprovação CST e da operadora, e os remetentes estrangeiros se vinculam por meio de um agregador local licenciado CST.

3. 3

   O seu engenheiro de migração envia os registos das rotas da BroadNet, e a equipa de conformidade da BroadNet acompanha cada um deles até a aprovação.

4. 4

   Inicie a execução paralela num país somente após o ID do remetente ser aprovado para as rotas da BroadNet naquele país. Até lá, continue a enviar pelo seu fornecedor atual.

As regras para cada mercado estão nas páginas de regulamentos. Regulamentação de SMS por país

Execute ambos os fornecedores em paralelo

Mantenha o seu fornecedor atual ativo e adicione BroadNet como uma segunda rota por trás de um switch no seu próprio código. Envie primeiro para os seus próprios números verificados, depois para uma pequena parte do tráfego real e compare ambas as rotas nos mesmos destinos.

Comparação por país e operadora:

• A combinação de status de entrega: entregue, não entregue, expirado e rejeitado.
• O tempo decorrido entre o envio de uma mensagem e a receção do relatório de entrega.
• O remetente exibido no aparelho.
• A contagem de segmentos para o mesmo texto, de POST /sms/identify.

Escolha a rota por destinatário em vez de por mensagem, para que todas as tentativas de reenvio OTP para um utilizador passem pelo mesmo fornecedor. Uma troca de encaminhamento mínima:

// Send a share of recipients through BroadNet; the rest stay on your
// current provider. BROADNET_SHARE is a percentage (0-100) you control.
const BROADNET_SHARE = Number(process.env.BROADNET_SHARE ?? "0");

// Same recipient -> same bucket, so OTP retries stay on one provider.
function bucket(to: string): number {
  let h = 0;
  for (const c of to) h = (h * 31 + c.charCodeAt(0)) >>> 0;
  return h % 100;
}

export async function sendSms(to: string, text: string, senderId: string) {
  if (bucket(to) < BROADNET_SHARE) return sendViaBroadNet(to, text, senderId);
  return sendViaCurrentProvider(to, text, senderId); // your existing code
}

async function sendViaBroadNet(to: string, text: string, senderId: string) {
  const res = await fetch("https://api.broadnet.me/sms/sendSms", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BROADNET_TOKEN}`,
      "Content-Type": "application/json",
    },
    // Use UNICODE for non-GSM text; POST /sms/identify tells you which.
    body: JSON.stringify({ senderId, destinationNumber: to, message: text, messageType: "TEXT" }),
  });
  if (!res.ok) throw new Error(`BroadNet send failed: ${res.status}`);
  return { provider: "broadnet", messageId: await res.text() };
}

Aumentar o tráfego em etapas

Transfira o volume de produção para BroadNet em etapas que você escolher, um país ou caso de uso por vez. Permaneça em cada etapa até que os comprovativos de entrega correspondam ao que você enviou e, em seguida, passe para a próxima.

1. Testando

   Somente os seus números verificados. Confirme o ID do remetente, o texto da mensagem e os comprovativos de entrega.

2. 5%

   Uma pequena parcela do tráfego real. O tráfego OTP para um único país devolve comprovativos de entrega rápidos e claros.

3. 25%

   Volume suficiente para comparar taxas de entrega e prazos de receção com o seu fornecedor atual.

4. 100%

   Todo o tráfego para esse país ou caso de uso. O seu fornecedor atual permanece ativo até que os comprovativos de entrega correspondam ao que você enviou.

Quanto tempo leva?

Aumentar o tráfego leva o tempo que você precisar. O processo de integração segue um único caminho: respondemos a uma solicitação de acesso de teste em até um dia útil, a integração técnica leva de 2 a 5 dias úteis e a validação da rota com aprovação do ID do remetente leva de 3 a 10 dias úteis. Na maioria dos mercados, o processo da descoberta à entrada em operação leva de 5 a 15 dias úteis; em mercados onde os órgãos reguladores demoram mais para aprovar os IDs dos remetentes, o processo leva ainda mais tempo. Consulte as etapas de integração.

Volte para o seu fornecedor atual sem interrupção

Para reverter, use o mesmo botão ao contrário: reduza a porcentagem de tráfego enviado pelo BroadNet para o último nível que funcionou ou para zero. A sua integração atual e os seus registos de ID de remetente permanecem ativos o tempo todo, portanto, reduzir a porcentagem é suficiente. Nada precisa ser reconstruído.

• Mantenha as credenciais do seu fornecedor atual, os registos de ID do remetente e o endpoint webhook ativos até que todo o tráfego tenha sido transferido e os relatórios de entrega correspondam ao que você enviou.
• Antes de começar, definam o que desencadeia um rollback, por exemplo, uma queda na proporção de mensagens entregues num determinado país, e quem tem permissão para tomar essa decisão.
• Mantenha o seu manipulador webhook em execução após um rollback: os relatórios de entrega de mensagens já enviadas pelo BroadNet ainda podem chegar.
• Desative a rota antiga somente depois que todo o tráfego passar sem problemas pela BroadNet e os comprovativos de entrega corresponderem ao que você enviou.

Quem é responsável por quê?

Uma migração afeta o seu código, os seus registos de remetente e o tráfego em produção. É assim que o trabalho é dividido.

Documentação relacionada

Perguntas frequentes