Docs da Business API — Quantum Random Bot

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

Identificadores de requisição

X-Request-ID é o identificador técnico de uma requisição HTTP. Envie seu próprio identificador com até 128 letras ASCII, dígitos ou caracteres . _ : -, ou omita o cabeçalho para o servidor gerar um. A resposta devolve o X-Request-ID efetivo, inclusive nos erros tratados da API.

request_id no JSON identifica uma operação QRNG individual que obteve aleatoriedade. Ele é diferente de X-Request-ID e serve para verificar a fonte de aleatoriedade.

qrng_request_ids contém todos os identificadores QRNG quando uma requisição HTTP executa várias operações. Por exemplo, /random/int com count=3 devolve três valores; request_id contém então o identificador da última operação.

Ao contatar o suporte, envie o X-Request-ID do cabeçalho da resposta. Para dúvidas sobre um resultado aleatório específico, inclua também request_id ou qrng_request_ids do JSON.

Requisição:
X-Request-ID: order-2026-00042

Resposta:
X-Request-ID: order-2026-00042

Random endpoints

GET /api/v1/me informações da chave +

Retorna plano, limites e uso da chave API atual.

Exemplo

{
  "plan": "business",
  "key_prefix": "qrng_J5b8aB",
  "requests_today": 42,
  "daily_limit": 1000
}

GET /api/v1/random/int inteiro sem modulo bias +

Gera de 1 a 100 inteiros no intervalo inclusivo min–max. min deve ser menor que max e a amplitude não pode exceder 1.000.000.000. Os valores são escolhidos sem modulo bias.

Exemplo

GET /api/v1/random/int?min=1&max=100&count=3

{
  "numbers": [42, 7, 91],
  "count": 3,
  "range": {"min": 1, "max": 100},
  "qrng_source": "anu",
  "request_id": "c46bd22a-de82-466e-9571-8fc56d655b3e",
  "qrng_request_ids": [
    "8f3d9251-33ad-4930-a6f3-115740b5e7d1",
    "68f0348e-a965-4e7a-a121-80f3be21d108",
    "c46bd22a-de82-466e-9571-8fc56d655b3e"
  ]
}

POST /api/v1/random/choice seleção de uma lista +

Seleciona um ou mais itens de uma lista.

Exemplo

{
  "items": ["Alice", "Bob", "Charlie"],
  "count": 1,
  "unique": true
}

{
  "chosen": ["Bob"],
  "count": 1,
  "from_total": 3,
  "qrng_source": "nist",
  "request_id": "2d2babbb-5cc4-4a63-b514-6505836c78bd"
}

POST /api/v1/random/shuffle embaralhamento Fisher-Yates +

Embaralha uma lista com Fisher-Yates e uma fonte quântica.

Exemplo

{
  "items": ["A", "B", "C", "D"]
}

{
  "shuffled": ["C", "A", "D", "B"],
  "count": 4,
  "qrng_source": "anu",
  "request_id": "31d20e70-da21-4773-b979-460ab68eacc2"
}

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.

Exemplo

GET /api/v1/random/bytes?n=32&format=hex

{
  "bytes": "3f9a2b8c...",
  "format": "hex",
  "length": 32,
  "qrng_source": "anu",
  "request_id": "51c8d364-6a66-405c-ad8b-af6bd14c5160",
  "pool": "crypto"
}

Giveaway endpoints

GET /api/v1/giveaways criar e listar sorteios +

Retorna ou cria sorteios ligados ao usuário ou à chave API.

Exemplo

{
  "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.

Exemplo

{
  "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.

Exemplo

{
  "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.

Exemplo

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

400 — parâmetros ou corpo da requisição inválidos.

401 — chave ausente, inválida ou revogada.

403 — o plano não inclui Business API ou o recurso pertence a outro usuário.

404 — recurso solicitado não encontrado.

422 — um parâmetro tem tipo ou formato inválido.

429 — limite diário esgotado.

500 — erro interno inesperado do serviço.

503 — o serviço QRNG está temporariamente indisponível. Tente novamente com backoff exponencial.

Aleatoriedade quântica para integrar ao seu produto

Visão geral

Autorização

Identificadores de requisição

Random endpoints

Giveaway endpoints

Verificação e confiança

Verify URL público

Audit trail

Cascata de resiliência

Erros

Pronto para conectar aleatoriedade verificável?