Início rápido da API para desenvolvedores
Compre números e leia códigos pelo seu próprio software. Crie uma chave, consulte preços, compre um número, espere o SMS e finalize, passo a passo.
Nesta página
A API para desenvolvedores do SmsGrab dá ao seu software os mesmos números do app, por meio de uma API REST que usa JSON. Você paga os mesmos preços do app, menos o seu desconto de atacado, com seu saldo SmsGrab normal e os mesmos reembolsos automáticos.
Quem pode usar
- Uma conta com e-mail confirmado. Contas de convidado não podem criar chaves.
- Uma conta sem restrições.
1. Crie uma chave de API
Abra Conta > Desenvolvedores no site, ou Configurações > API para desenvolvedores no app, e crie uma chave. Por segurança, você confirma com sua senha e, se estiver ativada, com o código da verificação em duas etapas. Escolha o escopo read para ferramentas só de leitura, ou read e purchase para comprar números.
A chave começa com sgk_ e é mostrada só uma vez. Guarde-a no cofre de segredos do seu servidor. Veja Chaves de API e segurança.
2. Autenticação
A URL base é https://smsgrab.com/api/dev/v1. Envie a chave como token bearer, ou no cabeçalho X-Api-Key:
GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here
Chaves ficam em servidores. Nunca coloque uma chave em um site, em uma extensão de navegador ou em um app que você distribui para outras pessoas.
3. Consulte seu saldo e os preços
export SMSGRAB_KEY="sgk_your_key_here"
curl -s https://smsgrab.com/api/dev/v1/balance \
-H "Authorization: Bearer $SMSGRAB_KEY"
curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
-H "Authorization: Bearer $SMSGRAB_KEY"
Os valores são sempre dados em unidades menores de USD, então 24 significa 0,24 USD. price_minor é o seu preço com o desconto de atacado e retail_price_minor o preço de tabela do app.
{ "currency": "USD", "discount_percent": 5,
"items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 24,
"retail_price_minor": 25, "available_numbers": 30412 } ] }
4. Compre um número
curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
-H "Authorization: Bearer $SMSGRAB_KEY" \
-H "Idempotency-Key: order-7f3c2a" \
-H "Content-Type: application/json" \
-d '{"service":"whatsapp","country":"indonesia","max_price_minor":24}'
serviceecountryrecebem nossos ids, comowhatsappeindonesia. Países também aceitam códigos ISO, comoID.max_price_minorprotege você: se o preço subiu, nada é cobrado e você recebe409 PRICE_CHANGED.Idempotency-Keytorna as novas tentativas seguras. Repetir a requisição com a mesma chave devolve o primeiro resultado em vez de comprar duas vezes.
A resposta é 201 Created com a ativação:
{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
"service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
"price_minor": 24, "currency": "USD",
"created_at": "2026-09-27T10:05:00.000Z", "expires_at": "2026-09-27T10:25:00.000Z",
"refunded": false, "refund_minor": 0, "sms": [] }
5. Espere o SMS
Em vez de consultar em um loop apertado, deixe a API segurar a requisição por até 30 segundos, até algo mudar:
curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
-H "Authorization: Bearer $SMSGRAB_KEY"
Quando uma mensagem chega, status passa a ser CODE_RECEIVED e sms traz todas as mensagens até agora:
{ "status": "CODE_RECEIVED",
"sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
"received_at": "2026-09-27T10:06:12.004Z" } ] }
Prefere push a consultas? Configure webhooks.
6. Finalize ou cancele
curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/finish \
-H "Authorization: Bearer $SMSGRAB_KEY"
curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/cancel \
-H "Authorization: Bearer $SMSGRAB_KEY"
- finish depois de usar o código. Só é aceito depois que um código chegou.
- cancel enquanto você ainda espera o primeiro código. O valor total é reembolsado.
- Se você não fizer nada, um número sem código expira no horário de
expires_ate é reembolsado automaticamente. A duração depende do serviço e do país, então sempre leiaexpires_atem vez de supor um tempo fixo.
Valores de status
| Status | Significado |
|---|---|
WAITING_SMS |
Comprado, esperando a primeira mensagem |
CODE_RECEIVED |
Pelo menos uma mensagem chegou |
COMPLETED |
Finalizado por você, ou quando o tempo acabou depois de um código |
CANCELLED |
Cancelado antes de um código, reembolsado |
EXPIRED |
Nenhum código até expires_at, reembolsado |
Erros
Todo erro tem o mesmo formato. Aja com base em code e reason e ignore motivos que você ainda não conhece:
{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }
Casos comuns são 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 com ACTIVATION_LIMIT_REACHED (no máximo 100 números podem esperar ao mesmo tempo por conta) e 429 RATE_LIMITED com o cabeçalho Retry-After.
A referência completa está na documentação para desenvolvedores.
Este artigo foi útil?
Obrigado! Que bom que ajudou.