> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Solución de Problemas

> Soluciones para problemas comunes del SDK de SofIA incluyendo errores de inicialización, problemas de audio y fixes por framework

<Info>
  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](/sofia/es/sdk/error-reference).
</Info>

## 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:

  • apikey: API key for authentication
  • userid: Unique identifier of the healthcare professional
  • patientid: Unique identifier of the patient
  • baseurl: API base URL (only required for keys that need it)
    Current value: "INVALID_API_KEY"
    Current value: "INVALID_USER_ID"
    Current value: "INVALID_PATIENT_ID"
```

**Soluciones**:

1. **API key inválida**: Verificar que la API key es correcta y activa
2. **Formato de URL inválido**: Si tu clave requiere `baseurl`, asegúrate de que empiece con `https://`. Para las claves más nuevas el endpoint se resuelve automáticamente — omite `baseurl`
3. **Propiedades faltantes**: Confirmar que todas las propiedades requeridas (`apikey`, `userid`, `patientid`) 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 (`apikey`, `userid`, `patientid`, `baseurl`, `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](#problemas-específicos-de-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](/sofia/es/sdk/patient-data)
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**:

```javascript theme={null}
// 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**:

```typescript theme={null}
// Problema común: vinculación de propiedades
@ViewChild('sofia', { static: false }) sofia!: ElementRef;

ngAfterViewInit() {
  this.sofia.nativeElement.handleReport = this.handleReport.bind(this);
}
```

**Vanilla JS**:

```javascript theme={null}
// 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]`.

```html theme={null}
<sofia-sdk
  debug="true"
  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 log | Prefijo                      | Qué 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](/sofia/es/sdk/templates#depuracion-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