Referência de endpoints
Dez endpoints cobrem o fluxo inteiro: consultar o saldo, ver apps e países, comprar um número, ler o SMS e encerrar o pedido.
Quais endpoints a API da SMS Nitro tem?
GET /v1/balance, GET /v1/services, GET /v1/services/{product}/countries, POST /v1/orders, GET /v1/orders, GET /v1/orders/{id} e POST /v1/orders/{id}/finish, /cancel, /resend e /ban. Todos ficam em https://smsnitro.com/api e exigem o cabeçalho X-Api-Key.
Todos os endpoints
| Endpoint | O que faz |
|---|---|
| GET /v1/balance | Saldo disponível e valor reservado por pedidos em aberto (USD) |
| GET /v1/services | Apps disponíveis com o preço inicial. Opcionais: country, server (1 ou 2), search |
| GET /v1/services/{product}/countries | Países de um app com preço, taxa de sucesso e DDI. Opcional: server |
| POST /v1/orders | Compra um número. Corpo: product (obrigatório), country, operator, server |
| GET /v1/orders | Seus pedidos, do mais recente ao mais antigo. Opcionais: limit (1 a 100, padrão 50), offset |
| GET /v1/orders/{id} | Um pedido sincronizado em tempo real: é aqui que o SMS aparece |
| POST /v1/orders/{id}/finish | Encerra a ativação depois de usar o código |
| POST /v1/orders/{id}/cancel | Cancela antes de qualquer SMS e estorna o valor reservado |
| POST /v1/orders/{id}/resend | Pede outro SMS no mesmo número, depois do primeiro código |
| POST /v1/orders/{id}/ban | Devolve um número que o app diz já estar em uso |
Ver apps e países
Use os endpoints de catálogo para escolher o que comprar. O valor de product (por exemplo telegram) é o identificador enviado na compra. Na lista de países, rate3 e rate24 são as taxas recentes de entrega em porcentagem, e offers mostra o preço de cada servidor.
curl "https://smsnitro.com/api/v1/services?country=usa" \
-H "X-Api-Key: $SMSNITRO_API_KEY"[
{ "product": "telegram", "price": "0.30", "count": 850,
"rate": null, "countries": [], "countries_count": 120 }
]curl https://smsnitro.com/api/v1/services/telegram/countries \
-H "X-Api-Key: $SMSNITRO_API_KEY"[
{
"country": "usa", "name": "United States", "iso": "us", "dial_code": "+1",
"price": "0.45", "count": 1200, "rate3": 95.0, "rate24": null, "server": 1,
"offers": [
{ "server": 1, "price": "0.45", "count": 1200, "rate3": 95.0 },
{ "server": 2, "price": "0.52", "count": 300, "rate3": 88.0 }
]
}
]Comprar um número
Envie product e country. O país aceita o identificador do catálogo (usa, england), o código ISO (gb) ou o nome em inglês, e o padrão é usa. Deixe server de fora para a API escolher o melhor. A resposta é o pedido com status PENDING e o número para digitar no app.
| Campo | Descrição |
|---|---|
| product | Obrigatório. Identificador do app em GET /v1/services |
| country | Opcional. Identificador do catálogo, ISO 3166-1 alfa-2 ou nome em inglês. Padrão: usa |
| operator | Opcional. Operadora, padrão any |
| server | Opcional. 1 ou 2. Sem ele: automático |
curl -X POST https://smsnitro.com/api/v1/orders \
-H "X-Api-Key: $SMSNITRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"product": "telegram", "country": "usa"}'{
"id": 123456,
"provider_order_id": "987654321",
"country": "usa",
"operator": "any",
"product": "telegram",
"phone": "+12025550123",
"status": "PENDING",
"price": "0.45",
"created_at": "2026-10-24T12:00:00Z",
"expires": "2026-10-24T12:20:00Z",
"messages": [],
"awaiting_resend": false,
"server": 1
}Ler o SMS
Consulte o pedido a cada 3 a 5 segundos. Quando o SMS chega, o status vira RECEIVED e messages traz o remetente, o texto completo e o código extraído. Use code quando vier preenchido; se vier vazio, leia text.
curl https://smsnitro.com/api/v1/orders/123456 \
-H "X-Api-Key: $SMSNITRO_API_KEY"{
"id": 123456,
"phone": "+12025550123",
"status": "RECEIVED",
"price": "0.45",
"expires": "2026-10-24T12:20:00Z",
"messages": [
{
"sender": "Telegram",
"text": "Telegram code: 48291",
"code": "48291",
"received_at": "2026-10-24T12:01:10Z"
}
],
"awaiting_resend": false,
"server": 1
}Concluir, cancelar, reenviar ou devolver
Cada ação devolve o pedido atualizado. As regras de quando cada uma é permitida estão na página do ciclo do pedido.
# Done: the code worked
curl -X POST https://smsnitro.com/api/v1/orders/123456/finish -H "X-Api-Key: $SMSNITRO_API_KEY"
# No SMS: cancel and get the frozen amount back
curl -X POST https://smsnitro.com/api/v1/orders/123456/cancel -H "X-Api-Key: $SMSNITRO_API_KEY"
# Another SMS on the same number (after the first code, no extra cost)
curl -X POST https://smsnitro.com/api/v1/orders/123456/resend -H "X-Api-Key: $SMSNITRO_API_KEY"
# The app says the number is already used: return it
curl -X POST https://smsnitro.com/api/v1/orders/123456/ban -H "X-Api-Key: $SMSNITRO_API_KEY"Listar seus pedidos
curl "https://smsnitro.com/api/v1/orders?limit=20&offset=0" \
-H "X-Api-Key: $SMSNITRO_API_KEY"Perguntas frequentes
Existe webhook quando o SMS chega?
Não. Consulte GET /v1/orders/{id} a cada 3 a 5 segundos; o SMS aparece assim que chega.
O que é o campo server?
Os números vêm de dois servidores de fornecimento. O servidor 1 é o principal e o 2 é o alternativo. Sem o campo, a API escolhe; informe para comparar preços ou tentar de novo no outro.