Sandbox / Test mode

Prueba la integración sin tocar producción

CBCTHub te da un entorno de sandbox aislado para que pruebes tu integración sin afectar producción. Las keys de test se distinguen por su prefix cbct_test_ (vs. cbct_live_) y todo lo que crees con ellas vive en un universo paralelo: no descuenta storage, no cuenta contra tu límite de exámenes, y los webhooks que dispara son separados de los de producción.

Cuándo usar sandbox

  • Mientras desarrollas la integración por primera vez.
  • En tu pipeline de CI / staging para tests end-to-end automatizados.
  • Antes de ejecutar un cambio en producción: replicalo en sandbox para verificar.
  • Para hacer un demo o capacitación sin ensuciar tus datos reales.

Cómo crear una key de test

En el dashboard ve a Ajustes → API. Cambia al tab Sandbox, escribe un nombre y haz clic en Crear key de test. La key empieza con cbct_test_ y aparece marcada con un badge naranja en el listado.

http
# Una key de test luce así:
Authorization: Bearer cbct_test_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4

Qué es lo que se aísla exactamente

  • Datos: los exámenes creados con key de test llevan is_test=true. Una key live nunca los ve; una key test solo ve los suyos. Si pides un exam_id que existe en el otro modo, recibes 404.
  • Storage: los archivos de test NO descuentan de tu storage_used_bytes. Puedes subir lo que quieras para probar.
  • Exam count: los exámenes de test NO incrementan tu exam_count. Tu plan no se consume.
  • Rate limit: las keys de test tienen su propio bucket con 1000 req/h independiente del plan. No consume tu cuota de producción.
  • Webhooks: por defecto las suscripciones reciben SOLO eventos live. Para recibir eventos de sandbox tienes que activar el flag enabled_test en la subscription.
El profile, plan, branding, slug público y configuración de la cuenta son los MISMOS en sandbox que en producción — no son datos transaccionales. Si en sandbox cambias el nombre de la clínica, también lo verás en producción. Esto se considera correcto: tu cuenta es una sola; sandbox solo aísla los datos transaccionales (exámenes, informes, webhooks).

Cómo identificar el modo en el payload

Todos los webhook payloads incluyen un campo booleano livemode (estilo Stripe): true para producción, false para sandbox. Tu integración puede ramificar lógica con este flag sin necesidad de mirar la URL o tener subscriptions separadas.

json
{
  "id": "evt_9z8y7x6w5v",
  "type": "exam.confirmed",
  "created_at": "2026-06-23T14:33:01Z",
  "livemode": false,
  "data": {
    "exam_id": "exm_test_abc123",
    "status": "ready",
    ...
  }
}

Configurar webhooks para sandbox

Cada subscription de webhook tiene dos flags: enabled_live y enabled_test. Por defecto enabled_live=true y enabled_test=false. Puedes activar test en una subscription existente (PATCH) o crear una nueva dedicada solo a sandbox.

bash
# Crear una subscription dedicada solo a sandbox
curl -X POST https://cbcthub.com/api/v1/webhooks \
  -H "Authorization: Bearer $CBCTHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://staging.miclinica.com/webhooks/cbcthub",
    "events": ["exam.confirmed", "report.signed"],
    "description": "Sandbox staging",
    "enabled_live": false,
    "enabled_test": true
  }'

# Activar test mode en una subscription existente
curl -X PATCH "https://cbcthub.com/api/v1/webhooks/$SUB_ID" \
  -H "Authorization: Bearer $CBCTHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled_test": true }'

Workflow recomendado

  1. Genera una key cbct_test_* y guárdala en la env var CBCTHUB_API_KEY_TEST de tu staging.
  2. Crea una subscription de webhook con enabled_live=false y enabled_test=true apuntando a tu URL de staging.
  3. En tu pipeline de CI, ejecuta el flujo end-to-end con la key de test. Recibes los eventos como en producción pero con livemode: false.
  4. Cuando todo pasa, repite con la key cbct_live_* en producción.

Probar rápido con curl

bash
# Verifica que la key de test funciona y aparece en sandbox
curl https://cbcthub.com/api/v1/me \
  -H "Authorization: Bearer cbct_test_..."

# Crea un examen en sandbox (no descuenta storage)
curl -X POST https://cbcthub.com/api/v1/exams \
  -H "Authorization: Bearer cbct_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test exam",
    "patient_name": "Sandbox Patient",
    "files": [{ "name": "ct.dcm", "size": 1024 }]
  }'

# Lista solo lo creado en sandbox (los exams live no aparecen)
curl https://cbcthub.com/api/v1/exams \
  -H "Authorization: Bearer cbct_test_..."

Limpieza de datos test

Los exámenes de sandbox se quedan en la base hasta que los elimines explícitamente con DELETE /api/v1/exams/{id}. No descuentan storage, así que en general no es necesario limpiarlos, pero puedes hacerlo si quieres mantener tu listado de sandbox prolijo.

Siguiente →

Flujo de subida