Documentação da API

A API REST do RecebaSMS.ai permite receber SMS de forma programática: consultar saldo e preços, criar ativações (comprar um número), ler o código recebido e cancelar com reembolso. Todas as respostas são JSON.

Base e autenticação

Base URL: https://recebasms.ai/api/v1
Autenticação: cabeçalho x-api-key: SUA_CHAVE em toda requisição.
Gere e revogue chaves no painel em /developer.
Valores monetários em centavos de Real (BRL) — ex.: 2570 = R$ 25,70.
Rate limit por chave (padrão 60 req/min) — exceder retorna 429.

curl https://recebasms.ai/api/v1/balance -H "x-api-key: SUA_CHAVE"

Erros

Erros retornam um JSON { "message": "..." } com o status HTTP correspondente:

Status	Significado
400	Requisição inválida (ex.: saldo insuficiente, parâmetro faltando).
401	Chave de API ausente, inválida ou revogada.
404	Recurso não encontrado (serviço/país sem estoque, ativação inexistente).
429	Limite de requisições excedido.

Endpoints

GET/v1/balance

Saldo atual da carteira.

curl https://recebasms.ai/api/v1/balance -H "x-api-key: SUA_CHAVE"
# => { "balanceCents": 740, "currency": "BRL" }

GET/v1/prices?country=BR&service=tg

Lista o preço (em BRL) e o estoque por serviço/país — a melhor oferta disponível. É a forma recomendada de descobrir o que comprar: retorna o serviceCode, o countryIso, o preço e a disponibilidade. Filtros opcionais: country (ISO) e service (código).

curl "https://recebasms.ai/api/v1/prices?country=BR&service=tg" -H "x-api-key: SUA_CHAVE"
# => [
#   {
#     "serviceCode": "tg", "serviceName": "Telegram",
#     "countryIso": "BR", "countryName": "Brazil",
#     "priceCents": 2570, "available": 485676
#   }
# ]

GET/v1/countries

Lista os países habilitados. Use o campo iso ao criar uma ativação.

GET/v1/services

Lista os serviços habilitados. Use o campo code ao criar uma ativação.

POST/v1/activations

Cria uma ativação (reserva um número e cobra o valor da carteira). Corpo JSON: serviceCode (código do serviço), countryIso (ISO do país) e, opcionalmente, operator.

curl -X POST https://recebasms.ai/api/v1/activations \
  -H "x-api-key: SUA_CHAVE" \
  -H "content-type: application/json" \
  -d '{ "serviceCode": "ds", "countryIso": "BR" }'

# => {
#   "id": "cmqv...", "status": "ACTIVE",
#   "e164": "+5511991194980", "priceCents": 50,
#   "service": { "code": "ds", "name": "Discord" },
#   "country": { "iso": "BR", "name": "Brazil" },
#   "smsMessages": [], "latestOtp": null,
#   "expiresAt": "2026-06-26T21:11:23.629Z"
# }

Em caso de saldo insuficiente, retorna 400 "Insufficient balance" e nada é cobrado.

GET/v1/activations/:id

Consulta uma ativação. A cada chamada o provedor é verificado e os SMS recebidos aparecem em smsMessages; o último código fica em latestOtp. Faça polling até status = SMS_RECEIVED (ou use webhook, abaixo).

curl https://recebasms.ai/api/v1/activations/ID -H "x-api-key: SUA_CHAVE"
# => { ..., "status": "SMS_RECEIVED", "latestOtp": "12345",
#      "smsMessages": [ { "text": "Seu codigo: 12345", "otpCode": "12345" } ] }

POST/v1/activations/:id/cancel

Cancela e reembolsa a ativação. Por segurança, a operadora só permite cancelar após ~120s — antes disso retorna 400 com o tempo restante. Se um SMS já tiver sido recebido, não é reembolsável. Sem SMS, a expiração (~20 min) gera reembolso automático.

curl -X POST https://recebasms.ai/api/v1/activations/ID/cancel -H "x-api-key: SUA_CHAVE"
# => { ..., "status": "REFUNDED" }

Status da ativação

Status	Significado
PENDING	Criada, alocando o número.
ACTIVE	Número pronto, aguardando o SMS.
SMS_RECEIVED	Código recebido (ver `latestOtp`).
EXPIRED	Expirou (com SMS recebido).
CANCELLED / REFUNDED	Cancelada / reembolsada.

Fluxo completo (exemplo)

# 1. Descobrir preço/estoque
curl "https://recebasms.ai/api/v1/prices?country=BR&service=ds" -H "x-api-key: $K"

# 2. Criar a ativação
curl -X POST https://recebasms.ai/api/v1/activations -H "x-api-key: $K" \
  -H "content-type: application/json" -d '{"serviceCode":"ds","countryIso":"BR"}'

# 3. Usar o número (e164) no serviço e consultar o código
curl https://recebasms.ai/api/v1/activations/ID -H "x-api-key: $K"

# 4. (Opcional) cancelar após ~120s se não for usar
curl -X POST https://recebasms.ai/api/v1/activations/ID/cancel -H "x-api-key: $K"

Webhook (tempo real)

Em vez de polling, cadastre uma URL de webhook em /developer. Enviamos um POST no evento sms.received com assinatura HMAC-SHA256 no cabeçalho x-recebasms-signature (verifique-a com o segredo do webhook).

Veja também os guias: API para receber SMS, Webhook para SMS recebido e Como monitorar SMS recebido.

Boas práticas e limites

Disponibilidade e preço variam por país/serviço — sempre consulte /prices antes.
Respeite o rate limit da chave; trate 429 com retentativa espaçada.
Use a API apenas para finalidades legais e permitidas pelos serviços de destino.
Proteja sua chave; revogue e gere outra se houver exposição.

Pronto para integrar?

Gerar minha API key

RecebaSMS.ai