Saltar al contenido principal

​
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 tools-args contiene un JSON Schema Draft-07 válido
  5. Verificar nombres de propiedades: Asegurar ortografía exacta (baseurl, wssurl, apikey, userid, patientid, toolsargs)

​
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. Configurar reconexión automática en tu implementación
  3. Implementar buffer local para datos no enviados
  4. Verificar firewall y proxy que puedan bloquear WebSockets

​
Problemas de Configuración

​
Esquemas JSON inválidos

Síntomas: Errores de validación en toolsArgs 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 toolsArgs: Simplificar esquemas, usar $ref para reutilización
  2. Optimizar patientData: Usar urls_historial en lugar de datos completos
  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: useEffect sin dependencias
useEffect(() => {
  if (sofiaRef.current) {
    sofiaRef.current.handleReport = handleReport;
  }
}, [handleReport]); // Incluir dependencia
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-component');
  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 toolsArgs
  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

// Configurar modo debug
<sofia-component 
  debug="true"
  // ... otras props
>

​
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
  • Configuración de props (sin incluir API keys)
  • Pasos para reproducir el problema

​
Error de autenticación

Síntomas: Mensajes de error 401 o 403 en consola Soluciones:
  1. Verifique que su API key es válida y activa
  2. Confirme que está usando el endpoint correcto (sandbox vs producción)
  3. Verifique que su IP está en la whitelist si aplica
  4. Contacte soporte si el problema persiste

​
Problemas de audio y transcripción

​
No se detecta audio del micrófono

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

​
Transcripción de baja calidad

Síntomas: Texto transcrito con muchos errores Soluciones:
  1. Mejore la calidad del audio (micrófono más cercano, menos ruido)
  2. Hable con claridad y velocidad moderada
  3. Configure el idioma correcto en el SDK
  4. Use auriculares para evitar eco y feedback

​
Desconexiones frecuentes de WebSocket

Síntomas: Pérdida de conexión durante la transcripción Soluciones:
  1. Verifique la estabilidad de la conexión de red
  2. Configure reconexión automática en su implementación
  3. Implemente buffer local para datos no enviados
  4. Verifique firewall y proxy que puedan bloquear WebSockets

​
Problemas de configuración

​
Esquemas JSON inválidos

Síntomas: Errores de validación en toolsArgs Soluciones:
  1. Validación de sintaxis: Use un linter JSON para verificar sintaxis
  2. Schema header: Incluya "$schema": "http://json-schema.org/draft-07/schema#"
  3. Tipos de datos: Verifique que los tipos coincidan con JSON Schema Draft-07
  4. Referencias: Asegúrese de que $ref apuntan a definiciones válidas

​
Payload demasiado grande

Síntomas: Error 413 o mensajes sobre límite de tamaño Soluciones:
  1. Reducir toolsArgs: Simplifique esquemas, use $ref para reutilización
  2. Optimizar patientData: Use urls_historial en lugar de datos completos
  3. Segmentación: Divida consultas grandes en múltiples sesiones
  4. Compresión: Elimine 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: Verifique que los callbacks son funciones válidas
  2. Contexto: Asegúrese de que this esté correctamente vinculado
  3. Errores previos: Revise la consola por errores que impidan la ejecución
  4. Configuración de esquemas: Confirme que required está configurado apropiadamente

​
Problemas específicos de framework

React: 
// Problema común: useEffect sin dependencias
useEffect(() => {
  if (sofiaRef.current) {
    sofiaRef.current.handleReport = handleReport;
  }
}, [handleReport]); // Incluir dependencia
Angular: 
// Problema común: binding de propiedades
@ViewChild('sofia', { static: false }) sofia!: ElementRef;

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

​
Problemas de rendimiento

​
Respuestas lentas

Síntomas: Tiempo excesivo entre Generate y handleReport Soluciones:
  1. Red: Verifique latencia de conexión a los servidores
  2. Datos: Reduzca el tamaño de patientData y toolsArgs
  3. Especialidad: Algunas especialidades requieren más procesamiento
  4. Cache: Implemente caching para consultas similares

​
Consumo excesivo de memoria

Síntomas: Navegador lento o bloqueos tras uso prolongado Soluciones:
  1. Limpiar sesiones: Cierre sesiones no utilizadas
  2. Event listeners: Elimine listeners al destruir componentes
  3. Referencias: Evite referencias circulares en callbacks
  4. Recargar: Implemente recarga periódica para sesiones largas

​
Información útil para soporte

Cuando contacte soporte técnico, incluya:
  • Versión del SDK utilizada
  • Navegador y versión
  • Mensajes completos de error de consola
  • Configuración de props (sin incluir API keys)
  • Pasos para reproducir el problema