API SMS Brasil: enviar ou receber códigos por API? imprimir

Quem busca uma API SMS Brasil normalmente precisa de uma de duas coisas: enviar SMS para clientes ou receber SMS de verificação em números temporários. São produtos diferentes. Aqui você entende a diferença e vê como a API do 11SMS compra números, consulta códigos e avisa por webhook.

Confundir os dois tipos é comum e custa tempo. Uma equipe contrata uma API de envio achando que vai conseguir receber códigos de outros aplicativos, ou o contrário. Vamos separar cada caso.

API de envio de SMS x API para receber SMS

API de envio (SMS para seus clientes)

É a API que a sua empresa usa para mandar mensagens: código de login do seu próprio aplicativo, aviso de entrega, lembrete de consulta, confirmação de pedido. Nesse modelo, você cadastra o texto, o número do destinatário e a API entrega a mensagem pela operadora. Cuidados típicos:

• Custo por mensagem enviada e volume mensal.
• Consentimento e base legal para usar o telefone do cliente, conforme a LGPD.
• Regras das operadoras contra spam e mensagens de marketing sem autorização.

API para receber SMS de verificação

É o caminho inverso: você precisa de um número que receba um SMS enviado por outro serviço e quer ler o código de forma automática. Os usos legítimos mais comuns são:

• Testes automatizados de cadastro e login com verificação por SMS no seu próprio aplicativo.
• Integração de sistemas internos que precisam verificar uma ferramenta sem usar o celular de um funcionário.
• Automações de rotina em que uma pessoa teria de copiar o código manualmente.

A API do 11SMS é deste segundo tipo. Ela não envia SMS para clientes: ela compra números temporários, mostra o código que chegou e avisa quando ele chega.

Como funciona a API do 11SMS na prática

O 11SMS é o serviço de números temporários para receber SMS de verificação da Eleven Host. Tudo o que você faz no painel também pode ser feito pela API REST:

1. Chave de acesso: você gera a chave na Área do Cliente da Eleven Host e a envia no cabeçalho X-Api-Key de cada requisição.
2. Compra: você pede um número informando o serviço e o país.
3. Consulta: você consulta o número comprado para ver se o código já chegou.
4. Cancelamento ou conclusão: você cancela um número que não recebeu SMS ou marca a operação como concluída.
5. Webhook assinado: em vez de ficar consultando, você recebe um aviso no seu sistema assim que o código chega.

O endereço base da API, a lista de códigos de serviços e países e os formatos de resposta estão na documentação da API do 11SMS. Nos exemplos abaixo, {base} representa esse endereço.

Exemplo: comprar um número pela API

Para comprar, envie um POST para {base}/v1/numeros com a sua chave no cabeçalho e um JSON no corpo:

curl -X POST "{base}/v1/numeros" -H "X-Api-Key: SUA_CHAVE" -H "Content-Type: application/json" -d '{"servico":"wa","pais":73,"referencia":"pedido-123","preco_maximo":3.00}'

O que significa cada campo:

• servico: o código do serviço que vai mandar o SMS (no exemplo, wa). Os códigos estão na documentação.
• pais: o código numérico do país, conforme a lista da documentação.
• referencia: um identificador seu, como o número do pedido ou do teste, para ligar a compra ao seu sistema.
• preco_maximo: o valor máximo que você aceita pagar por esse número, útil para controlar custos em automações.

A resposta traz o identificador da compra e o número para você usar no cadastro. Guarde o identificador: ele é usado nas próximas chamadas.

Exemplo: consultar, cancelar e concluir

Para ver o status e o código de uma compra, faça um GET com o identificador:

curl "{base}/v1/numeros/{id}" -H "X-Api-Key: SUA_CHAVE"

Para cancelar um número que ainda não recebeu SMS, ou para concluir a operação depois de usar o código:

curl -X POST "{base}/v1/numeros/{id}/cancelar" -H "X-Api-Key: SUA_CHAVE"
curl -X POST "{base}/v1/numeros/{id}/concluir" -H "X-Api-Key: SUA_CHAVE"

As regras são as mesmas do painel: o número fica ativo por 20 minutos; o cancelamento com estorno é possível a partir de 2 minutos após a compra; se nenhum SMS chegar em 20 minutos, o valor volta sozinho para o saldo; e depois que o código chega a compra é definitiva.

Gere sua chave e faça a primeira chamada hoje. Ver documentação da API

Webhook: seja avisado quando o código chegar

Consultar o número de tempos em tempos funciona, mas gera chamadas desnecessárias. O webhook resolve isso: quando o SMS chega, o 11SMS envia uma requisição para o endereço que você configurou, com o evento numero.codigo_recebido.

Cada aviso vem assinado no cabeçalho X-11SMS-Assinatura. Antes de processar o evento, valide essa assinatura seguindo o método descrito na documentação. Assim você garante que o aviso veio mesmo do 11SMS e não de alguém tentando injetar dados falsos no seu sistema.

Boas práticas para o seu endpoint de webhook:

• Responda rápido e processe o evento em segundo plano, se a tarefa for demorada.
• Rejeite requisições com assinatura inválida.
• Use o campo referencia da compra para saber a qual pedido ou teste aquele código pertence.
• Trate avisos repetidos sem duplicar ações no seu sistema.

Boas práticas de integração

Proteja a chave da API

Trate a chave como uma senha. Guarde-a em variável de ambiente ou cofre de segredos, nunca no código-fonte nem em repositório público. Se suspeitar de vazamento, gere uma nova chave na Área do Cliente.

Controle o saldo

A API usa o mesmo saldo pré-pago da sua conta Eleven Host, sem mensalidade. Se o saldo acabar, novas compras falham. Em automações, monitore o saldo e use preco_maximo para evitar surpresas. O preço varia por serviço e país e vai de centavos a poucos reais.

Planeje os tempos

Considere a janela de 20 minutos no desenho do fluxo. Se o código não vier, cancele a partir de 2 minutos ou deixe o estorno automático acontecer e tente de novo, talvez com outro país. Alguns aplicativos recusam números virtuais, então sua automação deve lidar com falhas.

Onde rodar a automação

Scripts de teste e integrações podem rodar no seu servidor de CI ou em uma VPS da Eleven Host, que fica ligada 24 horas e recebe os webhooks em um endereço fixo.

O que a API não deve fazer

A API existe para integração, testes e automações legítimas. Pelos termos do 11SMS, usar números para fraude, spam, criação de contas falsas ou em massa, burlar bloqueios ou banimentos e qualquer atividade ilegal leva ao bloqueio da conta. Também é preciso respeitar os termos de cada aplicativo verificado. Lembre ainda que os números são temporários e reciclados, então não servem para contas que você precisa manter ou recuperar depois. Se o seu objetivo é testar o próprio app, veja o guia de número para teste de SMS.

Automatize a verificação por SMS com segurança. Criar conta grátis

Perguntas frequentes

A API do 11SMS envia SMS para meus clientes?

Não. Ela serve para receber SMS de verificação em números temporários. Para enviar mensagens aos seus clientes, você precisa de uma API de envio.

Onde gero a chave da API?

Na Área do Cliente da Eleven Host. A chave vai no cabeçalho X-Api-Key de cada requisição.

Preciso pagar mensalidade para usar a API?

Não. Você paga só pelos números que compra, com o saldo pré-pago da conta, e o preço aparece antes da compra.

Como sei que o webhook veio do 11SMS?

Pela assinatura enviada no cabeçalho X-11SMS-Assinatura. Valide-a conforme a documentação antes de processar o evento.