Outros

API pública do SMS4You: API REST para a receção de SMS, OTP e números virtuais

01/07/2026
API pública do SMS4You: API REST para a receção de SMS, OTP e números virtuais

Apresentamos a API pública do SMS4You: automatize a receção de SMS e a gestão de números

Temos o prazer de anunciar o lançamento daquilo que muitos de vocês esperavam há muito tempo: a API pública do SMS4You. Agora, tudo o que faziam manualmente na vossa área de cliente pode ser feito programaticamente: comprar números, receber códigos por SMS e e-mail, acompanhar o saldo e os preços. Os vossos scripts, bots e sistemas de registo podem interagir diretamente com SMS4You, sem precisar de clicar uma única vez.

A seguir, explicamos o que lançámos exatamente, para que serve e como começar em cinco minutos.

Resumo do essencial

  • Uma API REST completa para ativações por OTP (receção de SMS) e por e-mail.
  • Catálogo de países, serviços e preços atualizados — tudo o que está visível na área de cliente está também disponível através da API.
  • Webhooks: os códigos e as alterações de estado chegam automaticamente ao seu servidor, sem necessidade de consultas constantes.
  • Compatibilidade com o protocolo SMS-Activate: transfira integrações já prontas, alterando apenas um endereço.
  • Autenticação simples através de um token que o próprio cria na sua área de cliente.
  • Documentação interativa com a possibilidade de testar as consultas diretamente no navegador.

Para que serve a API

A compra manual de números é boa quando há poucas ativações. Mas assim que se trata de dezenas e centenas de registos, processamentos em massa ou integração da receção de SMS no seu próprio produto, clicar na interface torna-se inconveniente. A API resolve precisamente esta tarefa: descreve a lógica uma única vez no código e, a partir daí, tudo ocorre automaticamente, em qualquer volume e a qualquer hora do dia.

Cenários típicos para os quais criámos esta funcionalidade:

  • registo e verificação automáticos de contas no seu software;
  • execuções em massa e testes, em que são necessários muitos números consecutivos;
  • integração da receção de códigos SMS diretamente no seu serviço ou produto;
  • migração de integrações existentes, desenvolvidas para outros fornecedores.

O que a API permite fazer

1. Ativações «chave na mão»: desde a compra do número até à receção do código

Todo o ciclo de vida da ativação está disponível através de endpoints REST intuitivos:

  • escolher o serviço e o país, verificar a disponibilidade e o preço;
  • comprar um número com uma única solicitação;
  • receber a SMS enviada (ou um e-mail, no caso de ativação por e-mail);
  • concluir, cancelar ou solicitar um novo SMS — o controlo do estado está totalmente nas suas mãos.

São suportados os dois produtos principais: receção de SMS (OTP) e ativações por e-mail. Cada ativação tem um identificador único, através do qual poderá aceder à mesma posteriormente.

2. Catálogo e preços atualizados

A API fornece dados atualizados:

  • lista de países com códigos telefónicos;
  • lista de serviços (para SMS e para e-mail);
  • preços por serviço específico ou país, bem como uma tabela de preços completa com apresentação página a página.

Um pormenor importante: os preços são apresentados tendo em conta o seu desconto pessoal. O que vê na resposta da API é exatamente o que será debitado do seu saldo.

3. Webhooks: os códigos chegam até si automaticamente

Consultar constantemente o servidor à espera de SMS é dispendioso e lento. Por isso, o SMS4You dispõe de webhooks: assim que chega uma nova mensagem ou o estado de ativação muda, enviamos nós próprios um pedido HTTP para os endereços que indicou.

  • recebe as notificações instantaneamente, sem necessidade de polling;
  • cada chamada é assinada com uma assinatura HMAC, para que possa ter a certeza de que a solicitação é realmente nossa;
  • estão implementadas tentativas de reenvio, caso o seu servidor fique indisponível por um segundo;
  • para quem restringe a receção de tráfego através de uma lista de permissões, publicamos a lista de endereços IP a partir dos quais os webhooks são enviados.

Juntamente com a API REST, isto completa a integração: é o próprio utilizador que envia as solicitações e recebe as atualizações através de um canal push.

4. Compatibilidade com o SMS-Activate: migração sem necessidade de reescrever o código

Além disso, algo de que nos orgulhamos particularmente. Se já dispõe de software desenvolvido para a API SMS-Activate, não precisa de reescrever a integração. O SMS4You suporta um protocolo compatível: basta alterar o endereço do servidor para o nosso e inserir a sua chave.

O seu código, bibliotecas e bots existentes continuarão a funcionar tal como estão, mas já com os números, preços e qualidade do SMS4You. Isto torna a transição para o nosso serviço uma questão de uma única linha na configuração, em vez de semanas de desenvolvimento.

5. Autenticação segura e simples

Sem nomes de utilizador nem palavras-passe nos scripts. Acede à sua área pessoal, cria um token pessoal no separador «Token API» e utiliza-o nas solicitações. O token pode ser transmitido de três formas — escolha a que for mais conveniente para a sua biblioteca:

  • no cabeçalho Authorization: Bearer <токен>;
  • cabeçalho X-Api-Token: <токен>;
  • parâmetro de consulta ?api_token=<токен>.

É possível criar vários tokens (por exemplo, um separado para cada projeto) e revogar a qualquer momento um token comprometido, sem afetar os restantes. O valor do token é apresentado uma única vez durante a criação — depois disso, é guardado apenas por si.

6. Documentação interativa

Preparámos uma documentação interativa baseada na OpenAPI: cada endpoint está descrito, o tipo de cada campo está indicado e as solicitações podem ser executadas diretamente a partir da página, sem necessidade de abrir o terminal. Nessa mesma página, encontra-se uma secção dedicada aos webhooks e ao protocolo compatível com o SMS-Activate.

A documentação está disponível em docs.sms4you.org.

Início rápido em cinco minutos

Endereço base da API: https://api.sms4you.org/api/v1

Passo 1. Verificar o saldo e o desconto da conta

curl https://api.sms4you.org/api/v1/me \
  -H "Authorization: Bearer YOU TOKEN"


{
  "data": {
    "name": "Ivan",
    "email": "[email protected]",
    "email_verified": true,
    "balance": "12.3456",
    "currency": "USD",
    "discount_percent": 5
  }
}

Passo 2. Verifique o preço do serviço pretendido

curl "https://api.sms4you.org/api/v1/prices?service_id=SERVICE_ID" \
  -H "Authorization: Bearer YOU TOKEN"

Passo 3. Comprar um número

curl -X POST https://api.sms4you.org/api/v1/activations \
  -H "Authorization: Bearer YOU TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service_id": 123, "country_id": 7, "price": "0.20"}'

Na resposta, receberá o número de telefone e o código de ativação.

Passo 4. Recebemos a SMS enviada

curl https://api.sms4you.org/api/v1/activations/АКТИВАЦИЯ_ID/messages \
  -H "Authorization: Bearer YOU TOKEN"

E se configurar um webhook, este passo nem sequer será necessário — o código será-lhe enviado automaticamente.

Limites e fiabilidade

  • As solicitações estão limitadas em termos de frequência (por predefinição, até 120 solicitações por minuto), para que o serviço se mantenha estável para todos.
  • Todas as respostas são enviadas num formato único, incluindo os erros: um código compreensível, uma mensagem legível e, se necessário, detalhes. Processá-las no código é um prazer.
  • Para efetuar compras, é necessário ter um e-mail confirmado na conta — uma medida de segurança habitual.

A quem se destina

  • Para programadores que precisam de receber SMS no seu produto.
  • Áreas de arbitragem e marketing, onde os registos ocorrem em grande volume.
  • Equipas de controlo de qualidade que testam cenários com verificação por telefone.
  • A todos aqueles que já utilizam software compatível com o SMS-Activate e pretendem mudar de fornecedor sem complicações.

O que se segue

A API pública é a base sobre a qual vamos continuar a construir. Os nossos planos passam por alargar a cobertura de produtos e funcionalidades, atendendo aos vossos pedidos. Se sentir falta de algum endpoint ou cenário, escreva-nos através do chat de apoio: lemos tudo e damos prioridade ao que é realmente necessário.

Experimente agora mesmo:

  1. Aceda à sua área pessoal e crie um token no separador «Tokens API».
  2. Aceda à documentação em docs.sms4you.org.
  3. Faça a primeira solicitação — e automatize todo o resto.

Boa integração e que os códigos cheguem a tempo.