Perguntas frequentes
Respostas às dúvidas mais comuns
Respostas às perguntas mais comuns sobre a API.
Posso usar a API no plano Free?
Sim, com 100 requests/hora. Suficiente para testar e integrar. Para uso produtivo, Pro (1.000 req/h) ou superior é recomendado. Detalhes completos na seção Rate limits.
Como verifico que minha API key é válida?
Chame GET /api/v1/me com sua key no header Authorization. Um 200 com seu plano, scopes, storage e contagem de exames significa que a key funciona; 401 unauthorized significa inválida, revogada ou de ambiente diferente (live vs test). Teste mais rápido, quase sem consumir cota. Também pode testar pelo playground na seção Autenticação.
Como vejo quanto estou consumindo da API?
No dashboard abra /dashboard/api/usage. Você vê o gráfico hora a hora dos últimos 7 dias por key, as chamadas mais usadas (endpoint + método) e os 429 recentes para detectar se está chegando ao limite. Se 429 ficam frequentes, suba de plano ou mova parte dos fluxos ao sandbox (que tem bucket separado).
O header X-CBCTHub-Version é obrigatório?
Não é obrigatório, mas recomendado em produção. Se omitir usamos a última versão estável (hoje 2026-06-23) — tranquilo para começar, arriscado se publicarmos uma quebra depois. Pinar o valor protege: quando uma nova versão sair seu sistema continua na anterior até você migrar deliberadamente. Se enviar valor inválido retornamos 400 com code unsupported_api_version. Detalhes em Autenticação → Versionamento.
Existem SDKs oficiais?
Publicamos a especificação OpenAPI 3.1 oficial em https://cbcthub.com/openapi.json. A partir dela você pode auto-gerar um SDK type-safe em TypeScript, Python, PHP, Go, Java e muitas outras linguagens com openapi-generator. Veja a seção "OpenAPI e SDKs" para os comandos exatos.
Existe um sandbox para testes?
Sim. Gere uma key com o prefix cbct_test_ em Ajustes → API → aba Sandbox. Tudo o que você cria com ela fica isolado da produção: não consome storage, não usa cota do plano e os webhooks disparam separadamente com livemode: false. Detalhes completos na seção Sandbox / Test mode.
Como separo eventos de webhook live e test?
Cada subscription tem dois flags independentes: enabled_live (padrão true) e enabled_test (padrão false). Uma única subscription pode receber ambos os modos (e distingui-los pelo campo livemode do payload), ou você pode ter subscriptions separadas — uma com enabled_live=true para produção e outra com enabled_test=true para staging.
Posso embutir o visualizador no meu sistema?
Sim. Use viewer_url em um iframe HTML, ou redirecione o usuário. Em modo público, o visualizador abre sem controles de edição.
O link compartilhado leva a marca do meu centro?
No plano Free mostra "Powered by CBCTHub". No Pro ou superior você ativa o branding completo (logo, nome, cores) no dashboard.
Existem webhooks de eventos?
Sim. Suportamos exam.created, exam.confirmed, exam.deleted, report.published e report.signed. Com assinatura HMAC SHA-256 e retentativas automáticas. Detalhes completos na seção Webhooks.
Como verifico que um webhook realmente vem do CBCTHub?
Valide o HMAC SHA-256 do body cru (bytes originais, não do JSON parseado) com o secret que recebeu ao criar a subscription. O header X-CBCTHub-Signature traz sha256=<base64>. Compare em tempo constante com crypto.timingSafeEqual (Node) ou hmac.compare_digest (Python).
O que acontece se meu endpoint webhook estiver fora do ar?
Reintentamos automaticamente com backoff exponencial: 30s, 2min, 10min, 1h, 6h, 24h. Máximo 6 tentativas por evento. Após 20 falhas consecutivas a subscription se autodesabilita para não sobrecarregar seu endpoint. Você pode ver o log de cada delivery em GET /api/v1/webhooks/{id}/deliveries.
Posso enviar laudos em outros formatos além de PDF?
Por enquanto somente PDF (validamos magic bytes %PDF-). Se precisar gerar o PDF a partir de texto, HTML ou template, faça do seu lado com qualquer biblioteca (puppeteer, pdfkit, jspdf, wkhtmltopdf) e envie em base64.
Vocês assinam um DPA?
Sim. Baixe o template em cbcthub.com/dpa, assine e envie. Devolvemos assinado em 48 horas úteis.
Como envio um CBCT que tenho como ZIP?
Use upload_mode="zip" no POST /api/v1/exams (com zip_size_bytes). Retornamos UMA URL pré-assinada; faça PUT do ZIP inteiro lá (1 única request) e depois chame POST /api/v1/exams/{id}/process-zip. Nosso servidor descompacta em streaming (sem carregar o ZIP em RAM) e faz upload de cada DICOM ao R2. Pronto: exame ready em 3 chamadas em vez de N. Limites: 1 GB de ZIP, 5000 arquivos dentro, 5 GB expandidos, 1,6 TB por arquivo individual. Exemplos curl/Node/Python na seção Fluxo de envio → Opção A.
Aceitam arquivos não-DICOM?
A API aceita qualquer formato (não validamos extensão). Mas o visualizador 3D só funciona com DICOM válido. Para exam_type "mesh" suportamos STL e PLY.
Como saber se há um incidente?
Publicamos cada incidente em nosso status page público com timeline em tempo real. Assine por email ou RSS pelo próprio status page, ou peça em soporte@cbcthub.com para receber alertas dedicados por webhook (planos Ultra / Enterprise). Detalhes na seção Confiabilidade.