Preguntas frecuentes
Respuestas a las dudas más comunes
Respuestas a las preguntas más comunes sobre la API.
¿Puedo usar la API con plan Free?
Sí, con 100 requests/hora. Suficiente para probar e integrar. Para uso productivo recomendamos Pro (1.000 req/h) o superior. Detalle completo en la sección Rate limits.
¿Cómo verifico que mi API key es válida?
Llama GET /api/v1/me con tu key en el header Authorization. Si responde 200 con tu plan, scopes, storage y exam count, la key funciona; si responde 401 unauthorized, está mal, revocada o pertenece a otro entorno (live vs test). Es la prueba más rápida y no consume cuota relevante. También puedes probarla desde el playground integrado en la sección Autenticación.
¿Cómo veo cuánto estoy consumiendo de la API?
En el dashboard, abre /dashboard/api/usage. Vas a ver el gráfico hora a hora de los últimos 7 días por key, las llamadas más usadas (endpoint + método) y los 429 recientes para detectar si te estás acercando al límite. Si recibes 429 frecuentes, sube de plan o pasa parte de los flujos a sandbox (que tiene bucket separado).
¿Es obligatorio enviar el header X-CBCTHub-Version?
No es obligatorio, pero sí recomendado en producción. Si lo omites, usamos la última versión estable (hoy 2026-06-23) — fácil para empezar, riesgoso si publicamos un cambio incompatible más adelante. Pinear el valor te protege: cuando saquemos una versión nueva tu sistema sigue sobre la vieja hasta que la migres a propósito. Si envías un valor inválido devolvemos 400 con code unsupported_api_version. Detalle en la sección Autenticación → Versionado.
¿Hay SDKs oficiales?
Publicamos la especificación OpenAPI 3.1 oficial en https://cbcthub.com/openapi.json. Desde ahí puedes auto-generar un SDK type-safe en TypeScript, Python, PHP, Go, Java y muchos lenguajes más con openapi-generator. Mira la sección "OpenAPI y SDKs" para los comandos exactos.
¿Hay sandbox de testing?
Sí. Genera una key con prefix cbct_test_ desde Ajustes → API → tab Sandbox. Todo lo que crees con ella vive aislado de producción: no descuenta storage, no cuenta contra tu plan y dispara webhooks por separado con livemode: false. Detalle completo en la sección Sandbox / Test mode.
¿Cómo separo eventos de webhook live y test?
Cada subscription tiene dos flags independientes: enabled_live (default true) y enabled_test (default false). Una sola subscription puede recibir ambos modos (y diferenciarlos por el campo livemode del payload), o puedes tener subscriptions separadas — una con enabled_live=true para tu URL de producción y otra con enabled_test=true para staging.
¿Puedo embeber el visor en mi sistema?
Sí. Usa el viewer_url en un iframe HTML, o redirige al usuario. En modo público, el visor se abre sin controles de edición.
¿El link compartido tiene la marca de mi centro?
En plan Free muestra "Powered by CBCTHub". En plan Pro o superior puedes activar el branding completo de tu centro (logo, nombre, colores) desde el dashboard.
¿Hay webhooks de eventos?
Sí. Soportamos exam.created, exam.confirmed, exam.deleted, report.published y report.signed. Con firma HMAC SHA-256 y reintentos automáticos. Detalle completo en la sección Webhooks.
¿Cómo verifico que un webhook viene realmente de CBCTHub?
Valida el HMAC SHA-256 del body crudo (bytes originales, no del JSON parseado) con el secret que recibiste al crear la subscription. El header X-CBCTHub-Signature trae el valor con formato sha256=<base64>. Compara en tiempo constante con crypto.timingSafeEqual (Node) o hmac.compare_digest (Python).
¿Qué pasa si mi endpoint webhook está caído?
Reintentamos automáticamente con backoff exponencial: 30s, 2min, 10min, 1h, 6h, 24h. Máximo 6 intentos por evento. Después de 20 fallos consecutivos la subscription se deshabilita sola para no quemar tu endpoint. Puedes ver el log de cada delivery en GET /api/v1/webhooks/{id}/deliveries.
¿Puedo subir informes en otro formato que no sea PDF?
Por ahora solo PDF (validamos magic bytes %PDF-). Si necesitas generar el PDF desde texto, HTML o template, hazlo en tu lado con cualquier librería (puppeteer, pdfkit, jspdf, wkhtmltopdf) y súbelo en base64.
¿Pueden firmar un DPA?
Sí. Descarga el template en cbcthub.com/dpa, fírmalo y envíalo. Lo devolvemos firmado en 48 horas hábiles.
¿Cómo subo un CBCT que tengo como ZIP?
Usa upload_mode="zip" en POST /api/v1/exams (con zip_size_bytes). Te devolvemos UNA URL presignada; haz PUT del ZIP completo ahí (1 sola request) y después llama POST /api/v1/exams/{id}/process-zip. Nuestro servidor descomprime en streaming (sin cargar el ZIP a RAM) y sube cada DICOM a R2. Listo: examen ready en 3 llamadas en vez de N. Límites: 1 GB de ZIP, 5000 archivos dentro, 5 GB expandidos, 1,6 TB por archivo individual. Ejemplos curl/Node/Python en la sección Flujo de subida → Opción A.
¿Aceptan archivos no-DICOM?
La API acepta cualquier formato (no validamos extensión). Pero el visor 3D solo funciona con DICOM válido. Para exam_type "mesh" soportamos STL y PLY.
¿Cómo saben si hay un incidente?
Publicamos cada incidente en nuestro status page público, con timeline en tiempo real. Suscríbete por email o RSS desde el status page, o pide a soporte@cbcthub.com que te agreguemos a alertas dedicadas por webhook (clientes Ultra / Enterprise). Más detalles en la sección Confiabilidad.