Visão geral
A Quantum Random Bot Business API dá acesso a aleatoriedade verificável e fluxos de sorteio sem um processo manual no Telegram.
Cada resultado importante pode ser vinculado a um Certificate ID público, URL de verificação e certificado PDF para participantes, jurídico, patrocinadores ou auditoria interna.
Autorização
Toda requisição exige o cabeçalho Authorization: Bearer <key>. A chave é criada no bot no plano Business.
A chave em texto puro aparece apenas uma vez. Guarde como segredo e não envie para o navegador do cliente.
Authorization: Bearer qrng_xxxxxxxxxxxxxxxxx
Random endpoints
GET /api/v1/me informações da chave +
Retorna plano, limites e uso da chave API atual.
{
"plan": "business",
"key_prefix": "qrng_J5b8aB",
"requests_today": 42,
"daily_limit": 1000
}
GET /api/v1/random/int inteiro sem modulo bias +
Gera um ou mais inteiros em um intervalo, sem modulo bias.
GET /api/v1/random/int?min=1&max=100&count=3
{
"numbers": [42, 7, 91],
"source": "anu",
"request_id": "c46bd22a-de82-466e-9571-8fc56d655b3e"
}
POST /api/v1/random/choice seleção de uma lista +
Seleciona um ou mais itens de uma lista.
{
"items": ["Alice", "Bob", "Charlie"],
"count": 1
}
{
"chosen": ["Bob"],
"source": "nist",
"request_id": "..."
}
POST /api/v1/random/shuffle embaralhamento Fisher-Yates +
Embaralha uma lista com Fisher-Yates e uma fonte quântica.
{
"items": ["A", "B", "C", "D"]
}
GET /api/v1/random/bytes bytes aleatórios +
Retorna bytes hex para tokens e chaves: entropia segura do sistema com quantum-mix quando uma fonte externa está disponível.
{
"hex": "3f9a2b8c...",
"bytes_count": 32,
"source": "anu",
"request_id": "..."
}
Giveaway endpoints
GET /api/v1/giveaways criar e listar sorteios +
Retorna ou cria sorteios ligados ao usuário ou à chave API.
{
"giveaways": [
{
"public_id": "A1B2C3D4",
"title": "My Giveaway",
"status": "active",
"participants_count": 500
}
],
"total": 1
}
POST /api/v1/giveaways criar e listar sorteios +
Retorna ou cria sorteios ligados ao usuário ou à chave API.
{
"title": "My API Giveaway",
"winners_count": 3,
"description": "Optional campaign copy"
}
POST /api/v1/giveaways/{id}/draw seleção de vencedores +
Executa a seleção de vencedores e retorna dados para verificação pública.
{
"winners": [
{"username": "alice", "telegram_id": 123456}
],
"certificate_id": "17d58bb5...",
"verify_url": "https://quantum-bot.space/verify/17d58bb5...",
"qrng_source": "anu",
"request_id": "..."
}
GET /api/v1/giveaways/{id}/participants.csv exportação CSV +
Relatório CSV para patrocinadores, jurídico, contabilidade e auditoria interna.
telegram_id,username,first_name,joined_at,is_winner
123456,alice,Alice,2026-05-05T12:00:00,true
789012,bob,Bob,2026-05-05T12:05:00,false
Verificação e confiança
Verify URL público
Participantes abrem a página do certificado e veem fonte, algoritmo, hash e vencedores.
Audit trail
Business recebe dados suficientes para relatório e revisão interna.
Cascata de resiliência
Se uma fonte externa falhar, a requisição passa para o próximo nível e a fonte usada fica registrada.
Erros
401 — chave ausente ou inválida.
403 — o plano não inclui Business API.
429 — limite diário esgotado.
500 — erro temporário do serviço. Tente novamente com backoff.
Pronto para conectar aleatoriedade verificável?
Comece com Business, crie uma chave no bot e conecte a API à sua campanha, CRM ou produto.