Docs de Business API — Quantum Random Bot

Resumen

Quantum Random Bot Business API da acceso a aleatoriedad verificable y flujos de sorteos sin un proceso manual en Telegram.

Cada resultado importante puede vincularse a un Certificate ID público, una URL de verificación y un certificado PDF para participantes, legales, sponsors o auditoría interna.

Autorización

Cada solicitud requiere el encabezado Authorization: Bearer <key>. La clave se crea en el bot con el plan Business.

La clave en texto plano se muestra una sola vez. Guárdala como secreto y no la envíes al navegador del cliente.

Authorization: Bearer qrng_xxxxxxxxxxxxxxxxx

Identificadores de solicitudes

X-Request-ID es el identificador técnico de una solicitud HTTP. Envía tu propio identificador de hasta 128 letras ASCII, dígitos o caracteres . _ : -, u omite el encabezado para que el servidor genere uno. La respuesta devuelve el X-Request-ID efectivo, también en los errores controlados del API.

request_id en el JSON identifica una operación QRNG individual que obtuvo aleatoriedad. Es distinto de X-Request-ID y sirve para verificar la fuente de aleatoriedad.

qrng_request_ids contiene todos los identificadores QRNG cuando una solicitud HTTP ejecuta varias operaciones. Por ejemplo, /random/int con count=3 devuelve tres valores; request_id contiene entonces el identificador de la última operación.

Al contactar con soporte, envía el X-Request-ID del encabezado de respuesta. Para consultas sobre un resultado aleatorio concreto, incluye también request_id o qrng_request_ids del JSON.

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

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

Random endpoints

GET /api/v1/me información de la clave +

Devuelve el plan, los límites y el uso de la clave API actual.

Ejemplo

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

GET /api/v1/random/int entero sin modulo bias +

Genera de 1 a 100 enteros en el rango inclusivo min–max. min debe ser menor que max y la amplitud no puede superar 1.000.000.000. Los valores se eligen sin modulo bias.

Ejemplo

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 selección de una lista +

Selecciona uno o varios elementos de una lista.

Ejemplo

{
  "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 mezcla Fisher-Yates +

Mezcla un arreglo con Fisher-Yates y una fuente cuántica.

Ejemplo

{
  "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 aleatorios +

Devuelve bytes hex para tokens y claves: entropía segura del sistema con quantum-mix cuando hay una fuente externa disponible.

Ejemplo

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 crear y listar sorteos +

Devuelve o crea sorteos vinculados al usuario o a la clave API.

Ejemplo

{
  "giveaways": [
    {
      "public_id": "A1B2C3D4",
      "title": "My Giveaway",
      "status": "active",
      "participants_count": 500
    }
  ],
  "total": 1
}

POST /api/v1/giveaways crear y listar sorteos +

Devuelve o crea sorteos vinculados al usuario o a la clave API.

Ejemplo

{
  "title": "My API Giveaway",
  "winners_count": 3,
  "description": "Optional campaign copy"
}

POST /api/v1/giveaways/{id}/draw selección de ganadores +

Ejecuta la selección de ganadores y devuelve datos para verificación pública.

Ejemplo

{
  "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 exportación CSV +

Reporte CSV para sponsors, legales, contabilidad y auditoría interna.

Ejemplo

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

Verificación y confianza

Verify URL público

Los participantes abren la página del certificado y ven fuente, algoritmo, hash y ganadores.

Audit trail

Business recibe datos suficientes para reportes y revisión interna.

Cascada de resiliencia

Si una fuente externa no responde, la solicitud pasa al siguiente nivel y la fuente usada queda registrada.

Errores

400 — parámetros o cuerpo de solicitud no válidos.

401 — clave ausente, inválida o revocada.

403 — el plan no incluye Business API o el recurso pertenece a otro usuario.

404 — recurso solicitado no encontrado.

422 — un parámetro tiene un tipo o formato no válido.

429 — límite diario agotado.

500 — error interno inesperado del servicio.

503 — el servicio QRNG no está disponible temporalmente. Reintenta con backoff exponencial.

Aleatoriedad cuántica para integrar en tu producto

Resumen

Autorización

Identificadores de solicitudes

Random endpoints

Giveaway endpoints

Verificación y confianza

Verify URL público

Audit trail

Cascada de resiliencia

Errores

¿Listo para conectar aleatoriedad verificable?