Ghost Number API

API pública do bot SMS — compre números virtuais, receba códigos OTP via HTTP, gerencie saldo em BRL e recarregue via Pix.

1. Visão geral

O endereço-base é lido dinamicamente da chave api_base_url. Dois prefixos estão disponíveis:

https://ghostnumber.fun/v1/api/...
https://ghostnumber.fun/v2/api/...

V1 opera com o tier padrão de provedores. V2 utiliza somente provedores premium — se não houver estoque premium no momento da compra, a API retorna 404 e a V2 não troca silenciosamente para outro tier.

Todos os endpoints recebem JSON por POST. Envie Content-Type: application/json. O campo token é a chave pessoal gerada no chat do bot em 💠 Configurar API — exibida uma única vez. Ao trocá-la, a chave antiga é revogada imediatamente.

2. Autenticação

Gere sua chave no bot: t.me/Gostsmsbot → 💠 Configurar API. Envie sempre no corpo:

{ "token": "SUA_CHAVE" }

Exemplo cURL — consultar saldo

curl -X POST https://ghostnumber.fun/v1/api/balance \
  -H "Content-Type: application/json" \
  -d '{"token":"SUA_CHAVE"}'

3. Códigos de erro

Formato padrão de erro:

{ "status": "error", "error": "insufficient_balance", "message": "..." }

HTTP	Significado
400	Parâmetros ou valor inválidos
401	Chave inválida
402	Saldo insuficiente
403	Conta bloqueada
404	Serviço, país ou ativação não encontrado
409	Conflito — `request_id` repetido ou operação não permitida
429	Limite excedido — 120 req/min por chave
502	Falha ou recusa do provedor
503	Serviço temporariamente indisponível

Saldo

POST/v1/api/balance /v2/api/balance

{ "token": "SUA_CHAVE" }

Resposta:

{ "status": "success", "saldo": 20.00 }

Serviços & países

POST/v1/api/services /v2/api/services

Lista os serviços cadastrados no bot. Os IDs de país são numéricos. Em compras, aceita-se country ou country_id. Se nenhum for enviado, usa o país do perfil do cliente.

{
  "token": "SUA_CHAVE",
  "country": "73"
}

Comprar número

POST/v1/api/buy

{
  "token": "SUA_CHAVE",
  "service": "wa",
  "country": "73"
}

service é o código do serviço cadastrado no bot; servico também é aceito. country é opcional.

Sucesso (valores ilustrativos):

{
  "status": "success",
  "aid": "id-da-ativacao",
  "number": "5511999999999",
  "short": "wa",
  "price": 2.50,
  "saldo_restante": 17.50,
  "provider": "premium",
  "country": "73"
}

O preço é calculado em BRL a partir do custo retornado pelo provedor e da margem da versão da API. O saldo é debitado de forma atômica; se o provedor falhar, a API tenta devolver o valor. O prazo final de uma ativação depende do provedor.

Status

POST/v1/api/status

{
  "token": "SUA_CHAVE",
  "aid": "id-da-ativacao"
}

Respostas possíveis:

{ "status": "waiting", "aid": "...", "number": "5511...", "sms": [] }
{ "status": "received", "aid": "...", "number": "5511...", "sms": ["123456"] }

Aguardar SMS (até 30s)

POST/v1/api/wait

{
  "token": "SUA_CHAVE",
  "aid": "id-da-ativacao",
  "timeout": 25
}

Cancelar

POST/v1/api/cancel

Só pode ser solicitado após 2 minutos da compra e antes do SMS ser recebido. O reembolso é idempotente e volta ao saldo da conta.

{
  "token": "SUA_CHAVE",
  "aid": "id-da-ativacao"
}

Solicitar novo SMS

POST/v1/api/retry

{
  "token": "SUA_CHAVE",
  "aid": "id-da-ativacao"
}

Os mesmos endpoints existem em V2. Sempre use o mesmo prefixo de versão usado na compra.

Recarga Pix — criar cobrança

POST/v1/api/recharge/pix

{
  "token": "SUA_CHAVE",
  "amount": 20.00,
  "request_id": "recarga-0001"
}

request_id deve ser único por cliente; se repetido, retorna 409 — consulte a cobrança anterior em vez de criar outra. O valor precisa respeitar os limites de depósito configurados no bot.

Resposta:

{
  "status": "pending",
  "payment_id": "id-do-pagamento",
  "request_id": "recarga-0001",
  "amount": 20.00,
  "qr_code": "copia-e-cola-do-pix",
  "qr_code_base64": "imagem-base64",
  "reused": false
}

Recarga Pix — consultar / creditar

POST/v1/api/recharge/status

{
  "token": "SUA_CHAVE",
  "request_id": "recarga-0001"
}

O saldo só é creditado após validar pagamento aprovado, valor e referência externa. A gravação é idempotente.

Não compartilhe sua chave de API — ela autoriza gastos do saldo da sua conta.