API de SMS Virtual & Ativações Ultra Rápida

Autenticação

Todas as requisições autenticadas para https://api.painelsms.tech exigem o cabeçalho HTTP Authorization no padrão Bearer <TOKEN>.

Você pode gerar ou consultar seu token de API diretamente no menu do seu usuário no site oficial painelsms.tech.

Authorization: Bearer SUA_CHAVE_API
Content-Type: application/json
Accept: application/json

Consultar Saldo da Conta

Retorna o saldo atual disponível para compra de números virtuais na moeda BRL (Reais).

{
  "success": true,
  "user_id": 8322591222,
  "balance": 150.75,
  "currency": "BRL"
}

Listar Serviços e Menor Preço

Retorna todos os serviços disponíveis com seus nomes traduzidos, código de identificação, código do país e sempre o menor preço (mais barato) encontrado em estoque no momento.

Endpoints equivalentes: /api/v1/services ou /api/v1?action=getServicesList

curl -s "https://api.painelsms.tech/v1/catalog/services?country=73"   -H "Authorization: Bearer SEU_TOKEN"

{
  "success": true,
  "country": "73",
  "currency": "BRL",
  "services": [
    {
      "code": "wa",
      "name": "WhatsApp",
      "country": "73",
      "price": 8.38,
      "min_price": 8.38,
      "available": 100,
      "provider": "Phantom Gold"
    },
    {
      "code": "tg",
      "name": "Telegram",
      "country": "73",
      "price": 5.40,
      "min_price": 5.40,
      "available": 420,
      "provider": "Phantom Diamond"
    }
  ]
}

Opções de Provedores e Preços (1 a 10)

Para dar controle total aos seus scripts, este endpoint lista as 10 opções mais baratas em tempo real para o serviço solicitado, organizadas e numeradas de 1 a 10 por ordem crescente de preço:

• Provedor Gold (V1): Exibe os números originais de identificação dos provedores (ex: 2953, 3182) e índice 1..10.
• Provedor Diamond (V2): Numerado de forma limpa como Opção 1, Opção 2, Opção 3, Opção 4, Opção 5... para configuração facilitada em robôs.
• Provedor Operadoras (V4): Numerado por operadora como Opção 1 - Vivo, Opção 2 - TIM, Opção 3 - Algar Telecom, Opção 4 - Surf...
• Provedor Voice OTP (V3): Numerado como Opção 1 - Voice OTP.

Endpoints equivalentes: /api/v2/providers?service_code=wa ou /api/v1?action=getProvidersList&service=wa

{
  "success": true,
  "service_code": "wa",
  "country": "73",
  "currency": "BRL",
  "provider": "Phantom Diamond",
  "providers": [
    { "index": 1, "option": 1, "name": "Opção 1", "price": 16.04, "available": 99 },
    { "index": 2, "option": 2, "name": "Opção 2", "price": 27.64, "available": 26 },
    { "index": 3, "option": 3, "name": "Opção 3", "price": 28.13, "available": 2 },
    { "index": 4, "option": 4, "name": "Opção 4", "price": 28.21, "available": 16 },
    { "index": 5, "option": 5, "name": "Opção 5", "price": 30.50, "available": 45 }
  ]
}

Listar Países Disponíveis

Retorna todos os países globais suportados com seus respectivos IDs numéricos e nomes oficiais.

{
  "success": true,
  "countries": [
    { "id": "73", "name": "Brasil" },
    { "id": "187", "name": "Estados Unidos" },
    { "id": "117", "name": "Portugal" },
    { "id": "39", "name": "Argentina" },
    { "id": "78", "name": "Reino Unido" }
  ]
}

Comprar Número — POST /v1/api/buy

Aloca imediatamente um número virtual ativo. Roteia internamente entre os provedores parceiros (Opção 1 e Opção 2), selecionando dinamicamente o menor custo e a maior taxa de entrega, com fallback automático instantâneo se um dos provedores estiver sem estoque.

{
  "status": "success",
  "aid": "24722162",
  "number": "5519976210608",
  "price": 0.60,
  "saldo_restante": 149.40,
  "provider": "diamond"
}

Consultar Status do SMS — POST /v1/api/status

Consulta tradicional para checar o status atual do número pelo ID curto aid.

// 1. Aguardando SMS:
{ "status": "waiting", "sms": [] }

// 2. Código Recebido:
{ "status": "received", "sms": ["480594"] }

// 3. Cancelado ou Estornado:
{ "status": "canceled", "sms": [] }

Aguardar SMS em Tempo Real (Long-Polling) — POST /v1/api/wait

Conexão assíncrona persistente (recomendado): Mantém a requisição HTTP aberta e utiliza PostgreSQL LISTEN/NOTIFY para disparar o código OTP no exato milissegundo em que for detectado, sem necessidade de fazer requisições repetidas.

{
  "status": "received",
  "sms": ["480594"]
}

// Se atingir o timeout de 90s sem código:
{
  "timeout": true,
  "status": "waiting",
  "sms": []
}

Cancelar Número & Estorno — POST /v1/api/cancel

Cancela a ativação e estorna 100% do valor de volta para o saldo da conta de forma atômica.

{
  "status": "canceled",
  "saldo": 150.00
}

Pedir Reenvio de SMS — POST /v1/api/retry

Solicita um novo código SMS para o mesmo número de telefone. Disponível exclusivamente no motor v2 (Phantom Diamond). Limpa a captura de SMS anterior para reativação imediata do Long-Polling.

{
  "status": "waiting",
  "message": "Reenvio solicitado com sucesso"
}

Comprar / Gerar Número Virtual

Aloca imediatamente um novo número temporário para recebimento de SMS ou Voice OTP. O saldo correspondente é debitado da sua conta.

{
  "service": "wa",
  "country": "73",
  "version": "v2"
}

Consultar Status & Receber SMS

Consulte periodicamente (polling a cada 3~5 segundos) até que o status mude para received com o código OTP detectado.

{
  "success": true,
  "order_id": "24722162",
  "status": "received",
  "code": "849201",
  "full_sms": "Seu codigo de confirmacao do WhatsApp e 849-201",
  "received_at": "2026-10-29T23:42:15Z"
}

Cancelar Pedido e Estornar Saldo

Cancela a ativação pendente. Se nenhum SMS tiver sido recebido, o valor cobrado é estornado imediatamente 100% para o seu saldo.

Solicitar Reenvio de SMS (Resend)

Disponível no provedor Diamond (v2): permite aguardar um segundo código SMS no mesmo número de telefone sem custo adicional.

Notificações Webhook (Opcional)

Em vez de realizar polling contínuo, configure uma URL de webhook no seu painel. Assim que o SMS chegar, nosso servidor enviará um HTTP POST com o código OTP.

Tabela de Respostas e Erros

Nossa API disponibiliza compatibilidade nativa com o protocolo consagrado no mercado internacional de números virtuais (compatível com os principais bots e softwares de automação de SMS). Você pode plugar qualquer bot, script ou biblioteca sem modificar uma linha de código.

1. Consultar Saldo (action=getBalance)

Retorna o saldo disponível na sua conta em formato de texto simples ACCESS_BALANCE:$valor ou JSON.

ACCESS_BALANCE:15.50

2. Obter Número Virtual (action=getNumber / getNumberV2)

Aloca um número virtual temporário para o serviço e país solicitados. A rota seleciona automaticamente a melhor operadora e opção disponível.

ACCESS_NUMBER:24722162:5519976210608

{
  "status": "SUCCESS",
  "activationId": "24722162",
  "phoneNumber": "5519976210608",
  "activationCost": 1.18,
  "currency": "BRL",
  "countryCode": "73",
  "canGetAnotherSms": true
}

3. Obter SMS Recebido (action=getStatus)

Efetue polling na URL a cada 3 a 5 segundos enviando o ID da ativação (id=$id) recebido na compra.

4. Alterar Status & Lógica Cronológica (action=setStatus)

Para a integração ser perfeita e respeitar as regras do mercado internacional, o seu script deve seguir a ordem cronológica exata descrita abaixo:

5. Lista de Serviços (action=getServicesList)

Retorna a listagem completa dos serviços com códigos universais e nomes oficiais formatados em JSON estruturado no padrão internacional de alta performance.

Exemplo dos códigos curtos mais utilizados no mercado:

{
  "status": "success",
  "services": [
    { "code": "wa", "name": "WhatsApp" },
    { "code": "tg", "name": "Telegram" },
    { "code": "go", "name": "Google" },
    { "code": "kt", "name": "KakaoTalk" }
  ]
}

6. Códigos de Países Multilíngue (action=getCountries)

Cada país possui um ID numérico universal fixo. O endpoint action=getCountries retorna a lista completa em padrão multi-idioma (Russo, Inglês, Chinês e Português):

[
  { "id": 73, "rus": "Бразилия", "eng": "Brazil", "chn": "巴西", "pt": "Brasil" },
  { "id": 187, "rus": "США", "eng": "USA", "chn": "美国", "pt": "Estados Unidos" },
  { "id": 1003, "rus": "Бермуды", "eng": "Bermuda", "chn": "百慕大", "pt": "Bermudas" }
]

7. Top Países por Serviço (action=getTopCountriesByService)

Permite ao seu bot descobrir rapidamente quais países possuem o maior estoque disponível e o menor custo para um serviço específico:

[
  { "country": 73, "count": 250, "price": 8.38 },
  { "country": 187, "count": 120, "price": 12.50 }
]

8. Consulta de Preços & Estoque (getPrices V1, V2 e V3)

Consulte a matriz completa de preços indexada por país e código de serviço:

{
  "73": {
    "wa": {
      "8.38": 150,
      "16.04": 99
    }
  }
}

9. Pagamentos, Carteira Estática & Webhooks

Carteira Estática / Recarga: Obtenha o endereço fixo de recarga e chave Pix chamando action=getActualWalletAddress.

Webhooks Automáticos: O Painel SMS envia um POST JSON instantâneo para o endereço cadastrado nas configurações da sua conta assim que a mensagem for recebida pela operadora, com até 5 retentativas exponenciais em caso de timeout.

{
  "event": "sms_received",
  "activationId": "24722162",
  "phone": "5519976210608",
  "code": "849201",
  "fullSms": "Seu codigo de confirmacao do WhatsApp e 849-201",
  "timestamp": "2026-10-31T03:00:00Z"
}

10. Tabela de Erros do Protocolo Universal