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

# Propiedades Opcionales

> Configuraciones adicionales para personalizar SofIA SDK

Estas propiedades te permiten personalizar el comportamiento y apariencia del componente SofIA SDK para adaptarse a las necesidades específicas de tu implementación.

## Propiedades Activas

### Control de Interfaz

| Propiedad  | Tipo      | Valor por Defecto | Descripción                                                                                                                                                               |
| ---------- | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **isopen** | `boolean` | `true`            | Estado de visibilidad del componente, permite control bidireccional del estado abierto/cerrado. Cuando no se proporciona, el componente se inicia **abierto** por defecto |

### Callbacks

| Propiedad            | Tipo       | Descripción                                                                                                                                                                                            |
| -------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **handleReport**     | `function` | Callback que recibe el reporte clínico estructurado generado por SofIA. Asígnalo como propiedad JS del elemento (`el.handleReport = fn`) — **no** se entrega vía atributo HTML ni evento DOM           |
| **setIsOpen**        | `function` | Función callback para manejar cambios de visibilidad solicitados por el componente                                                                                                                     |
| **setGetLastReport** | `function` | Un callback que recibe una función para recuperar el último reporte generado                                                                                                                           |
| **onReportApply**    | `function` | Recibe el informe curado cuando el médico hace clic en **Aplicar** en el [modal de vista previa de inserción](/sofia/es/sdk/insertion-preview). Cae en `handleReport` cuando el modal está desactivado |
| **updateTemplate**   | `function` | Devuelve el contenido existente de los campos del EMR para que la generación lo integre. Ver [Pre-cargar desde tu EMR](/sofia/es/sdk/update-template)                                                  |
| **handleExtras**     | `function` | Recibe las acciones clínicas (peticiones, citas, pruebas…) extraídas de la transcripción, tal como las produjo tu esquema. Ver [Acciones clínicas (Extras)](/sofia/es/sdk/extras)                      |

### Firmas de Callbacks

**handleReport**

```typescript theme={null}
handleReport: (report: Record<string, unknown>) => void
```

Se invoca cuando el usuario activa la generación de reportes. El objeto `report` coincide con la estructura definida en tu JSON Schema `template`. Ejemplo de payload:

```json theme={null}
{
  "diagnosis": "Diabetes Mellitus Tipo 2",
  "treatment_plan": "Metformina 500mg dos veces al día"
}
```

**setIsOpen**

```typescript theme={null}
setIsOpen: (isOpen: boolean) => void
```

Se invoca cuando el SDK solicita un cambio de visibilidad (ej.: el usuario hace clic en el botón de cerrar).

**setGetLastReport**

```typescript theme={null}
setGetLastReport: (getter: () => Promise<Record<string, unknown> | undefined>) => void
```

Se invoca una vez durante la inicialización. Proporciona una función que puedes almacenar y llamar posteriormente para recuperar el último reporte generado para la sesión actual de paciente/usuario.

**handleExtras**

```typescript theme={null}
handleExtras: (extras: Record<string, unknown>[]) => void
```

Se invoca al pulsar un botón de categoría de extras (peticiones, citas, pruebas, derivaciones…). Recibe el array de items de esa categoría, tal como los produjo tu esquema `templateExtras`: el SDK no renombra ni transforma campos. Se empareja con la prop `templateExtras`. Ver [Acciones clínicas (Extras)](/sofia/es/sdk/extras).

### Datos Contextuales

| Propiedad          | Tipo                        | Valor por Defecto | Descripción                                                                                                                                                                                                                                                                                             |
| ------------------ | --------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **patientdata**    | `string` (JSON) \| `object` | `undefined`       | Información contextual del paciente (antecedentes, notas previas, referencias) para enriquecer el procesamiento clínico                                                                                                                                                                                 |
| **templateExtras** | `string` (JSON) \| `object` | `undefined`       | Esquema JSON Schema cuyas propiedades de primer nivel son las categorías de acción. Cada propiedad genera un botón que extrae esa categoría de la transcripción. Propiedad JS `el.templateExtras`; atributo del web component `template-extras`. Ver [Acciones clínicas (Extras)](/sofia/es/sdk/extras) |

### Curación de informes y pre-carga desde el EMR

Estas props impulsan dos funcionalidades de informes. Consulta sus guías dedicadas para el flujo completo.

| Propiedad                      | Tipo       | Descripción                                                                                                                                                                                                                                                         |
| ------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **onReportApply**              | `function` | Se dispara cuando el médico hace clic en **Aplicar** en el [modal de vista previa de inserción](/sofia/es/sdk/insertion-preview). Recibe solo los campos que el médico dejó/editó                                                                                   |
| **insertionPreviewClassNames** | `object`   | Overrides de class-name para estilar el [modal de vista previa de inserción](/sofia/es/sdk/insertion-preview) (que vive en el shadow DOM del SDK). Claves: `backdrop`, `panel`, `header`, `body`, `footer`, `group`, `row`, `gapRow`, `applyButton`, `cancelButton` |
| **updateTemplate**             | `function` | Devuelve el contenido existente de los campos del EMR, por id de property de la plantilla, para que las notas generadas integren lo ya documentado. Ver [Pre-cargar desde tu EMR](/sofia/es/sdk/update-template)                                                    |

### Indicador de Consentimiento

El indicador de estado de consentimiento en el encabezado **no** es una propiedad del componente. Se habilita desde la configuración de tu cuenta/perfil de Omniloy (contacta a [support@omniloy.com](mailto:support@omniloy.com) para activarlo). Cuando está habilitado, el indicador refleja el campo `signedConsent` que proporcionas dentro de `patientdata` (ver [Datos del Paciente](/sofia/es/sdk/patient-data)).

### Localización

| Propiedad    | Tipo     | Valor por Defecto | Descripción                                                                  |
| ------------ | -------- | ----------------- | ---------------------------------------------------------------------------- |
| **language** | `string` | `"es"`            | Idioma de la interfaz. Valores soportados: `"es"` (Español), `"en"` (Inglés) |

<Info>
  El idioma por defecto es `"es"` (Español). Si tu aplicación está dirigida a usuarios de habla inglesa, establece `language="en"` explícitamente.
</Info>

### Contexto de analítica

| Propiedad                | Tipo     | Valor por Defecto | Descripción                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------ | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **usermedicalspecialty** | `string` | `undefined`       | La especialidad médica del profesional (p. ej. `"cardiología"`). Es puramente descriptiva: **no** cambia el comportamiento del SDK. Cuando se establece, se adjunta a cada evento de analítica (como `user_medical_specialty`) para poder segmentar el uso por especialidad. Se pasa tal cual, sin normalizar. Funciona tanto como prop de React como atributo/propiedad del web component |

<Warning>
  **Cambio incompatible (v1.0.9).** `usermedicalspecialty` sustituye al nombre en camelCase `userMedicalSpecialty` que se publicó en v1.0.8. El nombre antiguo ya no se lee: un host que lo siga pasando **no recibe error**, pero el valor se descarta en silencio y los eventos pierden la especialidad. Renómbralo al nombre en minúsculas `usermedicalspecialty`, en línea con el resto de props string (`userid`, `patientid`, `templateid`).
</Warning>

### Depuración

| Propiedad | Tipo      | Valor por Defecto | Descripción                                              |
| --------- | --------- | ----------------- | -------------------------------------------------------- |
| **debug** | `boolean` | `false`           | Habilita logging detallado para propósitos de depuración |

## Personalización CSS

SofIA SDK se renderiza como un Web Component con Shadow DOM. Esto evita conflictos con los estilos de la aplicación host, pero también significa que el CSS global de la aplicación no afecta directamente a los elementos internos del SDK.

Si necesita ajustar estilos internos concretos, inyecte una etiqueta `<style>` dentro del `shadowRoot` del componente una vez que el Web Component esté definido y montado:

```javascript theme={null}
async function setupSofIACustomStyles(selector = '#sofia') {
  await customElements.whenDefined('sofia-sdk');
  const sofia = await waitForSofiaComponent(selector);

  const customStyles = `
    :host {
      --sofia-custom-spacing: 12px;
    }

    .omniscribe_chat-view-stick-to-bottom-content {
      font-size: 14px;
    }
  `;

  const existingStyle = sofia.shadowRoot.querySelector('style[data-sofia-custom]');
  const styleTag = existingStyle || document.createElement('style');

  styleTag.setAttribute('data-sofia-custom', 'true');
  styleTag.textContent = customStyles;

  if (!existingStyle) {
    sofia.shadowRoot.appendChild(styleTag);
  }
}

function waitForSofiaComponent(selector) {
  return new Promise((resolve, reject) => {
    let attempts = 0;
    const maxAttempts = 40;

    function check() {
      const sofia = document.querySelector(selector);

      if (sofia?.shadowRoot) {
        resolve(sofia);
        return;
      }

      attempts += 1;
      if (attempts >= maxAttempts) {
        reject(new Error('SofIA no está montada o no tiene shadowRoot disponible'));
        return;
      }

      setTimeout(check, 100);
    }

    check();
  });
}

setupSofIACustomStyles('#sofia').catch((error) => {
  console.warn('No se pudieron aplicar los estilos personalizados de SofIA:', error);
});
```

Use el selector que corresponda a su componente, por ejemplo `#sofia` o `#sofia-component`. En Angular, ejecute esta lógica en `ngAfterViewInit`. En AngularJS, puede llamarla después de configurar los atributos y callbacks del componente. Si el componente se crea de forma condicional, vuelva a ejecutar la función después de montarlo.

<Warning>
  Los selectores de clases internas pueden cambiar entre versiones del SDK. El selector anterior corresponde a `@omniloy/sofia-sdk` 1.0.4. Mantenga estos estilos centralizados, pruebe la interfaz al actualizar `@omniloy/sofia-sdk` y prefiera propiedades documentadas del componente cuando estén disponibles.
</Warning>

## Recuperación Manual de Reportes

Además de recibir el reporte automáticamente, puedes solicitarlo bajo demanda desde tu aplicación.

La propiedad `set-get-last-report` ejecuta un callback que te proporciona una función asíncrona. Debes almacenar esta referencia para usarla cuando necesites recuperar el último reporte generado.

```javascript theme={null}
let getLastReportFn = null;

// Callback asignado a: set-get-last-report
function registerGetter(fn) {
  getLastReportFn = fn;
}

// Ejemplo de uso en un botón externo
async function handleSaveClick() {
  if (getLastReportFn) {
    const report = await getLastReportFn();
    console.log("Reporte recuperado:", report);
  }
}
```

## Ejemplos de Uso

### Configuración básica con datos del paciente

Las propiedades de datos van como atributos del elemento; los callbacks se asignan como propiedades JS:

```html theme={null}
<sofia-sdk
  id="sofia"
  patientdata='{"age": 45, "history": "Hipertensión arterial"}'
  language="es"
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
  template='{"type": "object"}'
  templateid="soap-general-v1"
  isopen="true"
></sofia-sdk>

<script>
  customElements.whenDefined('sofia-sdk').then(() => {
    const sofia = document.getElementById('sofia');
    sofia.handleReport = (report) => console.log('Reporte:', report);
    sofia.setIsOpen = (isOpen) => console.log('Abierto:', isOpen);
  });
</script>
```

### Modo solo chat (sin generación de reportes)

Para usar SofIA en modo solo chat, simplemente omita las propiedades `template` y `templateid`. El botón de generar no aparecerá.

```html theme={null}
<sofia-sdk
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
  language="es"
>
</sofia-sdk>
```

### Configuración avanzada con callbacks

```html theme={null}
<sofia-sdk
  id="sofia"
  debug="true"
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
></sofia-sdk>

<script>
  customElements.whenDefined('sofia-sdk').then(() => {
    const sofia = document.getElementById('sofia');
    sofia.handleReport = (report) => console.log('Reporte:', report);
    sofia.setGetLastReport = (getReport) => { window.getLastSofiaReport = getReport; };
  });
</script>
```

<Tip>
  **Los callbacks son propiedades JS, no atributos HTML.** Asigna cada callback directamente sobre el elemento en camelCase (ej.: `element.handleReport = fn`, `element.setIsOpen = fn`, `element.setGetLastReport = fn`, `element.onReportApply = fn`, `element.updateTemplate = fn`). No existe un atributo HTML `handle-report` ni un evento DOM — un atributo como `handle-report="miFn"` no se dispara. Las propiedades de datos simples (`isopen`, `patientdata`, `debug`) usan el mismo nombre en minúsculas como atributo HTML y como propiedad JS.

  | Propiedad          | Tipo     | Cómo asignarla                                                     |
  | ------------------ | -------- | ------------------------------------------------------------------ |
  | `handleReport`     | callback | Solo propiedad JS: `el.handleReport = fn`                          |
  | `setIsOpen`        | callback | Solo propiedad JS: `el.setIsOpen = fn`                             |
  | `setGetLastReport` | callback | Solo propiedad JS: `el.setGetLastReport = fn`                      |
  | `onReportApply`    | callback | Solo propiedad JS: `el.onReportApply = fn`                         |
  | `updateTemplate`   | callback | Solo propiedad JS: `el.updateTemplate = fn`                        |
  | `handleExtras`     | callback | Solo propiedad JS: `el.handleExtras = fn`                          |
  | `isopen`           | dato     | Atributo HTML o propiedad JS                                       |
  | `patientdata`      | dato     | Atributo HTML o propiedad JS                                       |
  | `templateExtras`   | dato     | Propiedad JS `el.templateExtras` o atributo HTML `template-extras` |
  | `debug`            | dato     | Atributo HTML o propiedad JS                                       |
</Tip>

## Propiedades Deprecadas

<Warning>
  Las siguientes propiedades están deprecadas y serán eliminadas en v2.0. No tienen efecto en la arquitectura actual basada en Chat.
</Warning>

| Propiedad                    | Migración                                                                                             |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| **toolsargs**                | Renombrada a `template`. Ver [Propiedades Requeridas](/sofia/es/sdk/required-properties)              |
| **isonlychat**               | Ya no es necesaria. El modo solo chat es automático cuando no se proporcionan `template`/`templateid` |
| **disableactions**           | Para deshabilitar todas las acciones, no monte el componente `<sofia-sdk>`                            |
| **disablegenerate**          | Para ocultar el botón de generar, no pase `template`/`templateid`                                     |
| **sofiatitle**               | Ya no es configurable. El título siempre es "SofIA"                                                   |
| **isscreenloading**          | No disponible en la UI basada en Chat                                                                 |
| **transcriptorselectvalues** | No se usa en la UI basada en Chat                                                                     |
| **render-report-content**    | No disponible en la UI basada en Chat                                                                 |
| **handleFill**               | No disponible en la UI basada en Chat                                                                 |

## Notas Importantes

* **patientdata**: Debe contener solo información necesaria para el contexto clínico, siguiendo principios de minimización de datos.
* **Estados**: Los cambios en propiedades booleanas se reflejan inmediatamente en la interfaz.
* **Localización**: Cambiar el idioma afecta toda la interfaz del componente, incluyendo mensajes de error y etiquetas.
* **Callbacks**: Asigna los callbacks programáticamente como propiedades JS del elemento (ej.: `element.handleReport = fn`). No pueden conectarse mediante atributos HTML ni nombres de función globales.