SMSPulse
REST API v1

API para Desenvolvedores

Integre o SMSPulse diretamente no seu sistema. Compre numeros e receba codigos SMS via API.

Para usar a API, crie uma conta e gere sua chave no painel do cliente.
Criar Conta

Autenticacao

A API do SMSPulse utiliza autenticacao via JWT (JSON Web Token). Para obter seu token, faca uma requisicao de login com suas credenciais de conta.

Apos o login, use o campo accessToken retornado no header Authorization: Bearer TOKEN em todas as requisicoes subsequentes.

shell
POST /auth/login
Content-Type: application/json

Body: { "identifier": "seu@email.com", "password": "suasenha" }

Response: {
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "user": {
    "id": 1,
    "name": "Seu Nome",
    "email": "seu@email.com",
    "role": "customer"
  }
}

Importante

Guarde seu accessToken de forma segura. Ele expira apos um periodo, e voce pode usar o refreshToken para obter um novo token sem precisar fazer login novamente.

Endpoints

Listar Servicos Disponiveis

GET/store/services

Retorna a lista de todos os servicos disponiveis para compra, incluindo nome, codigo e preco de cada um.

shell
GET /store/services
Authorization: Bearer TOKEN

Response: [
  { "code": "wa", "name": "WhatsApp", "price": 3.50 },
  { "code": "tg", "name": "Telegram", "price": 2.00 },
  { "code": "ig", "name": "Instagram", "price": 4.00 },
  ...
]

Comprar Numero

POST/store/purchase

Compra um numero virtual para o servico especificado. O valor e debitado automaticamente do seu saldo.

shell
POST /store/purchase
Authorization: Bearer TOKEN
Content-Type: application/json

Body: { "service": "wa" }

Response: {
  "id": 1,
  "service": "wa",
  "phoneNumber": "5514982332147",
  "status": "pending",
  "price": 3.50
}

Verificar Status (Polling)

GET/store/purchase/:id/status

Verifica o status atual de uma compra. Use polling a cada 5 segundos ate o status mudar para 'completed' com o codigo SMS.

shell
GET /store/purchase/:id/status
Authorization: Bearer TOKEN

// Aguardando SMS
Response: { "status": "waiting" }

// SMS recebido com sucesso
Response: { "status": "completed", "code": "847291" }

// Compra cancelada
Response: { "status": "cancelled" }

Faca polling a cada 5 segundos ate receber o codigo. Nao faca requests com intervalo menor que 3 segundos.

Cancelar Compra

POST/store/purchase/:id/cancel

Cancela uma compra ativa e devolve o valor ao seu saldo. So e possivel cancelar compras com status 'pending' ou 'active'.

shell
POST /store/purchase/:id/cancel
Authorization: Bearer TOKEN

Response: { "success": true }

Cancele para receber o reembolso no saldo. Compras com status 'completed' ou 'expired' nao podem ser canceladas.

Ver Saldo

GET/store/balance

Retorna o saldo atual da conta e o historico de transacoes (creditos e debitos).

shell
GET /store/balance
Authorization: Bearer TOKEN

Response: {
  "balance": 47.50,
  "transactions": [
    {
      "id": 1,
      "type": "credit",
      "amount": 50.00,
      "description": "Deposito via PIX",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "type": "debit",
      "amount": 3.50,
      "description": "Compra WhatsApp",
      "createdAt": "2025-01-15T10:35:00Z"
    }
  ]
}

Historico de Compras

GET/store/purchases?page=1

Lista todas as suas compras com paginacao. Retorna os dados e o total de registros.

shell
GET /store/purchases?page=1
Authorization: Bearer TOKEN

Response: {
  "data": [
    {
      "id": 1,
      "service": "wa",
      "phoneNumber": "5514982332147",
      "status": "completed",
      "code": "847291",
      "price": 3.50,
      "createdAt": "2025-01-15T10:35:00Z"
    }
  ],
  "total": 15
}

Codigos de Status

Cada compra passa por diferentes estados durante seu ciclo de vida. Utilize esses valores para controlar o fluxo da sua integracao.

StatusDescricao
pendingCompra criada, aguardando ativacao do numero.
activeNumero ativo e aguardando o SMS de verificacao.
completedSMS recebido com sucesso. O codigo esta disponivel no campo code.
cancelledCompra cancelada pelo usuario. O valor foi devolvido ao saldo.
expiredTempo esgotado sem receber o SMS. O valor foi devolvido automaticamente.

Exemplo Completo

Exemplo completo em JavaScript/Node.js mostrando o fluxo de login, compra de numero e aguardando o codigo SMS via polling.

javascript
// 1. Login
const login = await fetch('https://api.smspulse.com/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ identifier: 'seu@email.com', password: 'senha123' })
});
const { accessToken } = await login.json();

// 2. Comprar numero WhatsApp
const purchase = await fetch('https://api.smspulse.com/store/purchase', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({ service: 'wa' })
});
const { id, phoneNumber } = await purchase.json();
console.log(`Numero: ${phoneNumber}`);

// 3. Aguardar codigo (polling)
let code = null;
while (!code) {
  await new Promise(r => setTimeout(r, 5000));
  const status = await fetch(`https://api.smspulse.com/store/purchase/${id}/status`, {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });
  const result = await status.json();
  if (result.status === 'completed') {
    code = result.code;
    console.log(`Codigo recebido: ${code}`);
  }
}

Limites

Rate Limit

100

requests por minuto

Polling

5s

intervalo minimo recomendado

Uso Justo

A API do SMSPulse segue uma politica de uso justo. Requisicoes excessivas ou abusivas podem resultar em bloqueio temporario da conta. Se voce precisa de limites maiores, entre em contato com nosso suporte.

Pronto para integrar?

Crie sua conta, adicione saldo via PIX e comece a usar a API em minutos.

Criar Conta GratisJa tenho conta