A resposta curta: o seu site ou aplicação gera o código, guarda-o e confirma-o; a nossa API envia o SMS. Basta um pedido POST /v1/sms/messages com o número e o texto. Teste primeiro na Sandbox, onde nada é enviado nem cobrado, e passe para Produção com uma chave que só tenha a permissão de enviar SMS.
Quem faz o quê
| Tarefa |
Quem faz |
| Gerar um código aleatório |
O seu sistema |
| Guardar o código (com hash, nunca em texto simples) |
O seu sistema |
| Dar ao código uma validade curta e limitar as tentativas |
O seu sistema |
| Enviar o SMS para o telemóvel |
A nossa API |
| Confirmar o código que a pessoa escreve |
O seu sistema |
Os cuidados de segurança, com pormenor, estão em enviar códigos de uso único com segurança. Aqui fica a parte prática: a chave, o pedido, o texto e o que fazer quando alguma coisa corre mal.
Antes do primeiro código
| 1 |
Active o SMS e compre créditos na página SMS do My MozOut. Um código curto ocupa normalmente uma parte, ou seja, 1 crédito.
|
|
| 2 |
Crie uma chave Sandbox (começa por sandbox_) na página API do My MozOut, com a permissão sms:write. Pedimos a sua senha e um código de 6 dígitos enviado por e-mail, e a chave só aparece uma vez: guarde-a no servidor, nunca no código de uma página ou de uma aplicação móvel.
|
|
| 3 |
Quando tudo funcionar, crie uma chave de Produção (prod_...) com a mesma permissão, um limite de gastos e, se o seu servidor tem IP fixo, a lista de IPs autorizados.
|
|
O pedido que envia o código
curl https://api.mozout.com/v1/sms/messages \
-H "Authorization: Bearer sandbox_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7d4f2b1e-9c3a-4e8f-b6d2-1a5c3e9f0b7d" \
-d '{"number": "+258841234567", "text": "O seu código de verificação é 482913."}'
Na Sandbox, a resposta vem com "status": "simulated" e o cabeçalho X-API-Simulated: true: o texto foi validado, mas não saiu nem foi cobrado. Em Produção, o mesmo pedido envia o SMS e desconta os créditos do saldo de SMS. A resposta traz o id da mensagem, as partes e os créditos gastos; guarde o id para consultar o estado com GET /v1/sms/messages/{id}.
O texto: curto, numa só parte
Um código cabe à vontade num SMS de uma parte. Mas basta um acento como ó ou ã para a mensagem inteira passar a Unicode, e aí uma parte leva só 70 caracteres. A frase do exemplo tem acentos e cabe na mesma, porque é curta. A conta completa está em quantos créditos gasta um SMS.
Escreva sempre três coisas: quem envia (o nome da sua empresa), o código e um aviso para não o partilhar. Por exemplo: EMPRESA: o seu código é 482913. Não o partilhe com ninguém..
|
Com um Sender ID, o SMS chega com o nome da sua empresa e a pessoa reconhece logo de onde vem o código. Passe-o no campo sender, com um nome já aprovado (veja GET /v1/sms/senders). Sem sender, o envio sai pelo remetente grátis NETMSG.
|
Duplo clique, reenvios e limites
| 1 |
Use o cabeçalho Idempotency-Key. Gere um UUID por cada código e repita-o se tiver de refazer o pedido (falha de rede, duplo clique em «Enviar código»). A mesma chave com o mesmo corpo devolve a mesma resposta, sem outro SMS; com um corpo diferente, dá 409.
|
|
| 2 |
Controle o botão «Reenviar» no seu sistema. Deixe passar algum tempo antes de permitir reenviar e limite quantos reenvios cada número pode pedir: cada reenvio é um SMS novo e gasta créditos.
|
|
| 3 |
Vigie o saldo e os limites. A API aceita 300 pedidos por minuto, por conta, e há um limite diário de envios por conta. GET /v1/sms/balance devolve o saldo em créditos, daily_limit e sent_today.
|
|
|
Uma mensagem que falha é tentada mais 2 vezes, de 10 em 10 minutos. Com uma validade curta, o código pode já ter expirado quando sair. Por isso, o «Reenviar» deve gerar sempre um código novo. Se o pedido for recusado (por exemplo, com invalid_number: «Confira os algarismos, como em 841234567»), mostre à pessoa uma mensagem simples e veja o que fazer em erros e estados da API de SMS.
|
|
Quer enviar códigos de verificação a partir do seu site ou aplicação? Veja o que a API faz e crie a sua chave.
Ver a página da API
|
Angola
Brasil
Kenya
Moçambique
Nigeria
Portugal
South Africa
United Kingdom
United States
International
