Saltar al contenido principal
Esta página cubre solución de problemas basada en síntomas — comienza aquí cuando algo no funciona como se espera. Para el catálogo completo de mensajes de error del SDK con la salida exacta en consola, consulta la Referencia de Errores.

​
Problemas de Inicialización

​
Propiedades requeridas faltantes o inválidas

Síntomas: El componente muestra mensajes de error detallados en consola y falla al montarse Ejemplo de mensaje de error: 
[Sofia SDK] Configuration Error - Missing or invalid required properties:

  • baseurl: API base URL for backend communication
  • wssurl: WebSocket URL for real-time communication
  • apikey: API key for authentication
  • userid: Unique identifier of the healthcare professional
  • patientid: Unique identifier of the patient
    Current value: "INVALID_BASE_URL"
    Current value: "INVALID_WSS_URL"
    Current value: "INVALID_API_KEY"
Soluciones:
  1. API key inválida: Verificar que la API key es correcta y activa
  2. Formato de URL inválido: Asegurar que las URLs empiecen con https:// (baseurl) y wss:// (wssurl)
  3. Propiedades faltantes: Confirmar que todas las propiedades requeridas están proporcionadas
  4. JSON Schema inválido: Validar que template contiene un JSON Schema Draft-07 válido
  5. Verificar nombres de propiedades: Asegurar ortografía exacta (baseurl, wssurl, apikey, userid, patientid, template)

​
El componente no se carga

Síntomas: El componente SofIA no aparece en la página Causas comunes:
  • Script no cargado correctamente
  • API key faltante o inválida
  • Error en configuración de props
Soluciones:
  1. Verificar que el script se carga sin errores en la consola
  2. Confirmar que apikey está configurada correctamente
  3. Validar que baseurl apunta al endpoint correcto
  4. Asegurar que el elemento contenedor existe en el DOM

​
Error de autenticación

Síntomas: Mensajes de error 401 o 403 en consola Soluciones:
  1. Verificar que tu API key es válida y activa
  2. Confirmar que estás usando el endpoint correcto (sandbox vs producción)
  3. Verificar que tu IP está en la lista blanca si aplica
  4. Contactar soporte si el problema persiste

​
Problemas de Audio y Transcripción

​
Audio del micrófono no detectado

Síntomas: La transcripción no inicia o no detecta voz Soluciones:
  1. Permisos del navegador: Asegurar que el navegador tiene permisos de micrófono
  2. HTTPS requerido: WebRTC requiere conexión HTTPS en producción
  3. Dispositivo de audio: Verificar que el micrófono está conectado y funcionando
  4. Configuración del navegador: Verificar configuración de privacidad y audio

​
Calidad de transcripción deficiente

Síntomas: Texto transcrito con muchos errores Soluciones:
  1. Mejorar calidad de audio (micrófono más cerca, menos ruido)
  2. Hablar claramente y a velocidad moderada
  3. Configurar el idioma correcto en el SDK
  4. Usar audífonos para evitar eco y retroalimentación

​
Desconexiones frecuentes de WebSocket

Síntomas: Pérdida de conexión durante transcripción Soluciones:
  1. Verificar estabilidad de conexión de red
  2. El SDK gestiona la reconexión automáticamente. Si las desconexiones persisten, verifica la estabilidad de tu red y la configuración de firewall/proxy.
  3. Verificar que ningún proxy corporativo o firewall esté terminando conexiones WebSocket inactivas

​
Problemas de generación de reportes

​
El reporte no se genera

Síntomas: Al hacer clic en el botón generar no se produce resultado, o handleReport nunca se ejecuta Soluciones:
  1. Verificar template y templateid: Ambos template y templateid deben estar configurados. Si falta alguno, el botón de generar no aparecerá
  2. Comprobar validez del template: Abre la consola del navegador con debug="true" y busca mensajes [Sofia SDK] Settings Error. Problemas comunes incluyen $schema faltante, sintaxis JSON inválida o un template que supera los 100 KB
  3. Asegurar suficiente conversación: La IA necesita contexto de conversación suficiente para extraer datos. Si la conversación no cubre los campos definidos en tu template, el reporte puede estar incompleto o la generación puede fallar
  4. Comprobar conectividad de red: La generación de reportes requiere una llamada API. Verifica que tu baseurl es accesible y busca mensajes [Sofia SDK] API Error en la consola
  5. Verificar que el callback está asignado: Asegúrate de que handleReport está asignado antes de que el usuario haga clic en generar — consulta los ejemplos específicos por framework más abajo

​
El reporte está incompleto o vacío

Síntomas: handleReport se ejecuta pero al objeto del reporte le faltan campos esperados Soluciones:
  1. Revisar tu esquema template: Los campos listados en "required" siempre estarán presentes pero pueden contener valores genéricos o vacíos si la conversación no los cubrió
  2. Añadir descripciones a los campos: Usa la propiedad description en tu JSON Schema para guiar a SofIA sobre qué datos extraer para cada campo
  3. Comprobar patientdata: Proporcionar contexto relevante del paciente a través de patientdata mejora la precisión de la extracción — consulta Datos del paciente
  4. Habilitar modo debug: Configura debug="true" y busca mensajes [Sofia SDK] API - que muestran el ciclo de vida de la generación de reportes

​
Problemas de Configuración

​
Esquemas JSON inválidos

Síntomas: Errores de validación en template Soluciones:
  1. Validación de sintaxis: Usar un linter JSON para verificar sintaxis
  2. Encabezado de esquema: Incluir "$schema": "http://json-schema.org/draft-07/schema#"
  3. Tipos de datos: Verificar que los tipos coincidan con JSON Schema Draft-07
  4. Referencias: Asegurar que $ref apunten a definiciones válidas

​
Payload demasiado grande

Síntomas: Error 413 o mensajes sobre límite de tamaño Soluciones:
  1. Reducir template: Simplificar esquemas, usar $ref para reutilización
  2. Optimizar patientData: incluir solo datos relevantes para la consulta actual, y usar campos url en las notas médicas para referenciar registros externos en lugar de incrustar el contenido completo
  3. Segmentación: Dividir consultas grandes en múltiples sesiones
  4. Compresión: Eliminar espacios innecesarios y campos opcionales vacíos

​
Problemas de Integración

​
Callbacks no se ejecutan

Síntomas: handleReport u otros callbacks no responden Soluciones:
  1. Sintaxis correcta: Verificar que los callbacks son funciones válidas
  2. Contexto: Asegurar que this está correctamente vinculado
  3. Errores previos: Verificar consola para errores que impiden la ejecución
  4. Configuración de esquema: Confirmar que required está configurado apropiadamente

​
Problemas específicos de framework

React: 
// Problema común: callback no asignado al montar
useEffect(() => {
  if (sofiaRef.current) {
    sofiaRef.current.handleReport = handleReport;
  }
}, []); // Array vacío — asignar una vez al montar
Angular: 
// Problema común: vinculación de propiedades
@ViewChild('sofia', { static: false }) sofia!: ElementRef;

ngAfterViewInit() {
  this.sofia.nativeElement.handleReport = this.handleReport.bind(this);
}
Vanilla JS: 
// Problema común: timing del DOM
document.addEventListener('DOMContentLoaded', () => {
  const sofia = document.querySelector('sofia-sdk');
  sofia.handleReport = handleReport;
});

​
Problemas de Rendimiento

​
Respuestas lentas

Síntomas: Tiempo excesivo entre Generate y handleReport Soluciones:
  1. Red: Verificar latencia de conexión a servidores
  2. Datos: Reducir tamaño de patientData y template
  3. Especialidad: Algunas especialidades requieren más procesamiento
  4. Cache: Implementar cache para consultas similares

​
Consumo excesivo de memoria

Síntomas: Navegador lento o se congela después de uso prolongado Soluciones:
  1. Limpiar sesiones: Cerrar sesiones no utilizadas
  2. Event listeners: Eliminar listeners al destruir componentes
  3. Referencias: Evitar referencias circulares en callbacks
  4. Recarga: Implementar recarga periódica para sesiones largas

​
Depuración y Logging

​
Habilitar logging detallado

Añade debug="true" al componente SofIA para activar la salida detallada en consola. Todos los mensajes del SDK tienen el prefijo [Sofia SDK]. 
<sofia-sdk
  debug="true"
  baseurl="https://..."
  wssurl="wss://..."
  apikey="tu-api-key"
  userid="doctor-123"
  patientid="paciente-456"
></sofia-sdk>

​
Qué registra el modo debug

El modo debug emite mensajes organizados por categoría:
Categoría de logPrefijoQué cubre
Configuración[Sofia SDK] Settings - ...Parsing de template, validación, comportamiento de fallback
Autenticación[Sofia SDK] Auth - ...Validación de API key, refresco de token
Llamadas API[Sofia SDK] API - ...Ciclo de vida de generación de reportes (started, completed, failed)
WebSocket[Sofia SDK] WS - ...Estado de conexión, intentos de reconexión
Los mensajes de error incluyen un sufijo de categoría para ayudar a identificar el origen: configError, authError, apiError, settingsError, audioError, storageError o webSocketError.

​
Filtrar la salida de consola

En las DevTools de tu navegador, usa el filtro de Consola para aislar los logs del SDK:
  1. Abre DevTools (F12 o Cmd+Option+I)
  2. Ve a la pestaña Console
  3. En el campo de filtro, escribe [Sofia SDK]
  4. Solo se mostrarán los mensajes del SDK, eliminando el ruido de tu aplicación y librerías de terceros

​
Leer logs de templates

Para depuración específica de templates — incluyendo la referencia completa de logs de consola, checklist de validación y resolución de problemas comunes — consulta Esquemas de datos clínicos — Depuración de tu template.

​
Información útil para soporte

Al contactar soporte técnico, incluir:
  • Versión del SDK utilizada
  • Navegador y versión
  • Mensajes de error completos de la consola (filtrar por [Sofia SDK])
  • Configuración de props (sin incluir API keys)
  • Pasos para reproducir el problema