🔌 BoquetaSMS API

API REST para compra automatizada de números virtuais para recebimento de SMS

🌐 Informações da API

Base URL: https://api.cotoxprovidersms.fun/api/v1

Preço por número: R$ 0,50

Timeout do número: 20 minutos

Cancelamento: Após 2 minutos da compra

🔐 Autenticação

Todas as requisições devem incluir o header de autenticação:

X-API-Key: sua_chave_api_aqui

Obtenha sua API Key no bot do Telegram em 🔌 API

💰 Saldo

GET /api/v1/balance Consultar saldo da conta

Requisição cURL

curl -X GET "https://api.cotoxprovidersms.fun/api/v1/balance" \
     -H "X-API-Key: sua_chave_api_aqui"

Requisição Python

# pip install requests
import requests

response = requests.get(
    "https://api.cotoxprovidersms.fun/api/v1/balance",
    headers={"X-API-Key": "sua_chave_api_aqui"}
)
print(response.json())

Resposta (200 OK)

{
  "success": true,
  "balance": 15.50,
  "currency": "BRL"
}

📱 Números

POST /api/v1/purchase Comprar um número virtual

Requisição cURL

curl -X POST "https://api.cotoxprovidersms.fun/api/v1/purchase" \
     -H "X-API-Key: sua_chave_api_aqui" \
     -H "Content-Type: application/json" \
     -d '{}'

Requisição Python

import requests

response = requests.post(
    "https://api.cotoxprovidersms.fun/api/v1/purchase",
    headers={
        "X-API-Key": "sua_chave_api_aqui",
        "Content-Type": "application/json"
    },
    json={}
)
data = response.json()
print(f"Número: {data['number']}")
print(f"Order ID: {data['order_id']}")

Resposta (200 OK)

{
  "success": true,
  "order_id": 12345,
  "number": "+5511999998888",
  "price": 0.50,
  "expires_at": "2024-12-26T15:30:00Z"
}

Resposta de Erro (400)

{
  "success": false,
  "error": "insufficient_balance",
  "message": "Saldo insuficiente. Necessário: R$ 0.50"
}

GET /api/v1/order/{order_id} Verificar status e SMS

💡 Dica: Use polling (a cada 3-5 segundos) para verificar se o SMS chegou.

Requisição cURL

curl -X GET "https://api.cotoxprovidersms.fun/api/v1/order/12345" \
     -H "X-API-Key: sua_chave_api_aqui"

Requisição Python (com polling)

import requests
import time

order_id = 12345
headers = {"X-API-Key": "sua_chave_api_aqui"}

# Polling para aguardar SMS
while True:
    response = requests.get(
        f"https://api.cotoxprovidersms.fun/api/v1/order/{order_id}",
        headers=headers
    )
    data = response.json()
    
    if data["status"] == "completed":
        print(f"SMS: {data['sms']}")
        print(f"Código: {data['code']}")
        break
    
    print("Aguardando SMS...")
    time.sleep(5)

Resposta - Aguardando SMS

{
  "success": true,
  "order_id": 12345,
  "number": "+5511999998888",
  "status": "waiting",
  "sms": null,
  "code": null
}

Resposta - SMS Recebido

{
  "success": true,
  "order_id": 12345,
  "number": "+5511999998888",
  "status": "completed",
  "sms": "Seu código de verificação é: 123456",
  "code": "123456"
}

POST /api/v1/order/{order_id}/cancel Cancelar pedido e receber reembolso

⚠️ Importante: Só é possível cancelar após 2 minutos da compra e antes de receber o SMS.

Requisição cURL

curl -X POST "https://api.cotoxprovidersms.fun/api/v1/order/12345/cancel" \
     -H "X-API-Key: sua_chave_api_aqui"

Requisição Python

import requests

response = requests.post(
    "https://api.cotoxprovidersms.fun/api/v1/order/12345/cancel",
    headers={"X-API-Key": "sua_chave_api_aqui"}
)
print(response.json())

Resposta (200 OK)

{
  "success": true,
  "message": "Pedido cancelado com sucesso",
  "refunded": 0.50
}

Resposta de Erro (400)

{
  "success": false,
  "error": "too_early",
  "message": "Aguarde 2 minutos para cancelar",
  "wait_seconds": 85
}

💳 Pagamentos PIX

POST /api/v1/payment/create Criar pagamento PIX

⚠️ Limite: Apenas 1 pagamento pendente por vez. O PIX expira em 10 minutos.

Requisição cURL

curl -X POST "https://api.cotoxprovidersms.fun/api/v1/payment/create" \
     -H "X-API-Key: sua_chave_api_aqui" \
     -H "Content-Type: application/json" \
     -d '{"amount": 10.00}'

Requisição Python

import requests

response = requests.post(
    "https://api.cotoxprovidersms.fun/api/v1/payment/create",
    headers={
        "X-API-Key": "sua_chave_api_aqui",
        "Content-Type": "application/json"
    },
    json={"amount": 10.00}
)
data = response.json()
print(f"PIX Copia e Cola: {data['pix_code']}")

Resposta (200 OK)

{
  "success": true,
  "payment_id": 67890,
  "amount": 10.00,
  "pix_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_base64": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2024-12-26T15:40:00Z"
}

GET /api/v1/payment/{payment_id} Verificar status do pagamento

Requisição cURL

curl -X GET "https://api.cotoxprovidersms.fun/api/v1/payment/67890" \
     -H "X-API-Key: sua_chave_api_aqui"

Resposta - Pendente

{
  "success": true,
  "payment_id": 67890,
  "status": "pending",
  "amount": 10.00
}

Resposta - Aprovado

{
  "success": true,
  "payment_id": 67890,
  "status": "approved",
  "amount": 10.00,
  "new_balance": 25.50
}

POST /api/v1/payment/{payment_id}/cancel Cancelar pagamento pendente

⚠️ Limite: Só é possível cancelar até 1 minuto após a criação.

Requisição cURL

curl -X POST "https://api.cotoxprovidersms.fun/api/v1/payment/67890/cancel" \
     -H "X-API-Key: sua_chave_api_aqui"

Resposta (200 OK)

{
  "success": true,
  "message": "Pagamento cancelado com sucesso"
}

🔧 Sistema

GET /api/v1/health Verificar status da API

Requisição cURL

curl -X GET "https://api.cotoxprovidersms.fun/api/v1/health"

Resposta (200 OK)

{
  "status": "ok",
  "version": "1.0.0"
}

📝 Exemplo Completo

Fluxo completo: Comprar número e aguardar SMS

import requests
import time

# Configuração
API_KEY = "sua_chave_api_aqui"
BASE_URL = "https://api.cotoxprovidersms.fun/api/v1"
headers = {"X-API-Key": API_KEY}

# 1. Verificar saldo
r = requests.get(f"{BASE_URL}/balance", headers=headers)
saldo = r.json()["balance"]
print(f"Saldo: R$ {saldo}")

# 2. Comprar número
r = requests.post(f"{BASE_URL}/purchase", headers=headers, json={})
data = r.json()

if not data["success"]:
    print(f"Erro: {data['message']}")
    exit()

order_id = data["order_id"]
numero = data["number"]
print(f"Número: {numero}")

# 3. Aguardar SMS (polling a cada 5 segundos)
print("Aguardando SMS...")
for _ in range(60):  # Máximo 5 minutos
    r = requests.get(f"{BASE_URL}/order/{order_id}", headers=headers)
    data = r.json()
    
    if data["status"] == "completed":
        print(f"✅ SMS recebido!")
        print(f"Mensagem: {data['sms']}")
        print(f"Código: {data['code']}")
        break
    
    time.sleep(5)
else:
    # Cancelar se não recebeu SMS
    r = requests.post(f"{BASE_URL}/order/{order_id}/cancel", headers=headers)
    print("❌ Timeout - pedido cancelado")