Sandbox / Test mode

Teste a integração sem afetar a produção

O CBCTHub oferece um ambiente sandbox isolado para validar sua integração sem afetar a produção. As keys de test são identificadas pelo prefix cbct_test_ (vs cbct_live_) e tudo o que você cria com elas vive em um universo paralelo: não consome storage, não conta contra o limite de exames e os webhooks que dispara são separados dos de produção.

Quando usar sandbox

  • Enquanto você desenvolve a integração pela primeira vez.
  • No seu pipeline de CI / staging para testes end-to-end automatizados.
  • Antes de executar uma mudança em produção: repita-a em sandbox para verificar.
  • Para demos ou treinamentos sem sujar seus dados reais.

Como criar uma key de test

No dashboard vá em Ajustes → API. Mude para a aba Sandbox, digite um nome e clique em Criar key de teste. A key começa com cbct_test_ e aparece marcada com um badge laranja TEST na lista.

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

O que exatamente fica isolado

  • Dados: os exames criados com key de test carregam is_test=true. Uma key live nunca os vê; uma key test só vê os seus. Solicitar um exam_id do outro modo retorna 404.
  • Storage: os arquivos de test NÃO contam contra seu storage_used_bytes. Você pode enviar o que quiser para testar.
  • Exam count: os exames de test NÃO incrementam seu exam_count. A cota do seu plano é preservada.
  • Rate limit: as keys de test têm seu próprio bucket de 1000 req/h, independente do plano. Não consome sua cota de produção.
  • Webhooks: por padrão as subscriptions só recebem eventos live. Para receber eventos de sandbox você precisa ativar o flag enabled_test na subscription.
Profile, plano, branding, slug público e configurações da conta são os MESMOS em sandbox e produção — não são dados transacionais. Se você mudar o nome da clínica em sandbox também verá em produção. Isto é por design: sua conta é uma só; o sandbox isola apenas os dados transacionais (exames, laudos, webhooks).

Como identificar o modo no payload

Todos os payloads de webhook incluem um campo booleano livemode (estilo Stripe): true para produção, false para sandbox. Sua integração pode ramificar a lógica nesse flag sem inspecionar a URL ou manter 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 tem dois flags: enabled_live e enabled_test. Por padrão enabled_live=true e enabled_test=false. Você pode ativar test em uma subscription existente (PATCH) ou criar uma nova dedicada ao 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. Gere uma key cbct_test_* e guarde na variável de ambiente CBCTHUB_API_KEY_TEST do seu staging.
  2. Crie uma subscription de webhook com enabled_live=false e enabled_test=true apontando para sua URL de staging.
  3. No seu pipeline de CI execute o fluxo end-to-end com a key de test. Você recebe os eventos como em produção mas com livemode: false.
  4. Quando tudo passar, repita com a key cbct_live_* em produção.

Teste rápido com 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_..."

Limpeza de dados de test

Os exames de sandbox permanecem no banco até você excluí-los explicitamente com DELETE /api/v1/exams/{id}. Não consomem storage, então a limpeza geralmente não é necessária, mas você pode fazê-la para manter sua listagem de sandbox organizada.

Próximo →

Fluxo de envio