> ## 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 Requeridas > Configuración obligatoria para SofIA SDK El SofIA SDK requiere solo tres propiedades para conectarse: **`apikey`**, **`userid`** y **`patientid`**. El componente valida su presencia y tipo antes de establecer la conexión. `baseurl` solo es necesario para algunas claves — consulta [Conexión y autenticación](#conexión-y-autenticación) más abajo. ## Referencia Rápida Todas las propiedades del SofIA SDK en una sola tabla. Para documentación detallada, consulte [Conexión y autenticación](#conexión-y-autenticación) y [Propiedades Opcionales](/sofia/es/sdk/optional-properties). | Propiedad | Tipo | Default | Estado | Descripción | | ------------------------------ | -------------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **apikey** | `string` | — | Requerida | Clave de autenticación de Omniloy | | **userid** | `string` | — | Requerida | Identificador subrogado interno del profesional sanitario (nunca un MRN ni PII directo) | | **patientid** | `string` | — | Requerida | Identificador subrogado interno del paciente para la sesión (nunca un MRN ni PII directo) | | **baseurl** | `string` | auto | Condicional | Endpoint de la API REST (HTTPS). Opcional para las claves más nuevas desde 1.0.8 (auto-resuelto); requerido en caso contrario | | **template** | `object` | — | Opcional | JSON Schema Draft-07 que define la estructura de datos clínicos. Habilita la generación de reportes junto con `templateid` | | **templateid** | `string` | — | Opcional | Identificador definido por el integrador para la plantilla. Necesario junto con `template` para habilitar la generación de reportes | | **isopen** | `boolean` | `true` | Opcional | Estado de visibilidad del componente (abierto/cerrado) | | **handleReport** | `function` | — | Opcional | Callback que recibe el reporte clínico generado | | **setIsOpen** | `function` | — | Opcional | Callback para eventos de cambio de visibilidad | | **setGetLastReport** | `function` | — | Opcional | Callback que recibe una función para recuperar el último reporte | | **onReportApply** | `function` | — | Opcional | Recibe el informe curado del [modal de vista previa de inserción](/sofia/es/sdk/insertion-preview) | | **updateTemplate** | `function` | — | Opcional | Alimenta contenido existente del EMR a la generación ([pre-carga](/sofia/es/sdk/update-template)) | | **insertionPreviewClassNames** | `object` | — | Opcional | Overrides de class-name para el [modal de vista previa de inserción](/sofia/es/sdk/insertion-preview) | | **templateExtras** | `object` | — | Opcional | JSON Schema de categorías de acción; habilita los botones de [Extras](/sofia/es/sdk/extras) junto con `handleExtras`. Atributo `template-extras` en el web component | | **handleExtras** | `function` | — | Opcional | Recibe las acciones clínicas extraídas por categoría, tal como las produjo tu esquema ([Extras](/sofia/es/sdk/extras)) | | **patientdata** | `string` \| `object` | — | Opcional | Información contextual del paciente para procesamiento enriquecido | | **language** | `string` | `"es"` | Opcional | Idioma de la interfaz (`"es"` o `"en"`) | | **debug** | `boolean` | `false` | Opcional | Habilita logging detallado en consola | | ~~wssurl~~ | `string` | — | Deprecada | Ignorada desde 1.0.7 — la URL del transcriber ahora proviene de la settings API | | ~~toolsargs~~ | `object` | — | Deprecada | Use `template` en su lugar | | ~~isonlychat~~ | `boolean` | — | Deprecada | Auto-detectado — omita `template`/`templateid` para modo solo chat | | ~~disableactions~~ | `boolean` | — | Deprecada | No monte el componente en su lugar | | ~~disablegenerate~~ | `boolean` | — | Deprecada | Omita `template`/`templateid` en su lugar | | ~~sofiatitle~~ | `string` | — | Deprecada | El título siempre es "SofIA" | | ~~isscreenloading~~ | `boolean` | — | Deprecada | No disponible en la UI basada en Chat | | ~~transcriptorselectvalues~~ | `array` | — | Deprecada | Sin efecto | | ~~render-report-content~~ | `function` | — | Deprecada | No disponible en la UI basada en Chat | | ~~handleFill~~ | `function` | — | Deprecada | No disponible en la UI basada en Chat | Para guía de migración de propiedades deprecadas, consulte la [Guía de Migración](/sofia/es/sdk/migration). ## Conexión y autenticación El `apikey` es la única propiedad de conexión que siempre necesitas. Para las claves más nuevas, el SDK selecciona el endpoint automáticamente — de modo que **no** pasas `baseurl`. | Propiedad | Tipo | Descripción | | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | **apikey** | `string` | Clave de autenticación de Omniloy. Para las claves más nuevas se selecciona el endpoint correcto automáticamente | | **baseurl** | `string` | Endpoint de la API REST (HTTPS). **Opcional** para las claves más nuevas; **requerido** en caso contrario | **¿Mi clave necesita `baseurl`?** Las claves más nuevas no lo necesitan — el SDK resuelve el endpoint por ti, así que puedes omitir `baseurl`. Otras claves sí — sigue pasando el valor de `baseurl` que Omniloy te asignó. Si tienes dudas, Omniloy te indica cuál aplica a tu clave. **`wssurl` está deprecada y se ignora desde la v1.0.7.** La URL WebSocket de transcripción ahora la proporciona automáticamente la settings API. Pasar `wssurl` no tiene efecto; puedes eliminarla de tu integración con seguridad. ## Identificadores de Sesión | Propiedad | Tipo | Descripción | | ------------- | -------- | ------------------------------------------------------------------------------- | | **userid** | `string` | Identificador subrogado interno del profesional sanitario en el sistema EHR/HIS | | **patientid** | `string` | Identificador subrogado interno del paciente para la sesión actual | Usa **identificadores subrogados internos** para `userid` y `patientid` — nunca un número de historia clínica (MRN) u otro identificador directo del paciente/profesional. A diferencia de `patientdata`, estos valores se envían sin anonimizar. * Usar identificadores únicos persistentes * Evitar información personalmente identificable * Mantener consistencia entre sesiones * Considerar usar números de licencia profesional o IDs internos * Debe ser único dentro de su sistema * No debe contener identificadores personales directos * Puede cambiarse dinámicamente para diferentes consultas * Debe cumplir con las regulaciones de protección de datos **Cambiar `patientid` provoca un reset completo de la sesión.** Cuando actualizas `patientid` dinámicamente, el SDK limpia el historial de chat, cierra la conexión WebSocket actual e inicia una sesión completamente nueva. El contexto de la conversación anterior no se transfiere al nuevo paciente. Asegúrate de que cualquier generación de reporte pendiente haya finalizado antes de cambiar de paciente. ## Generación de Reportes Estas propiedades habilitan la generación de reportes. Cuando se proporcionan tanto `template` como `templateid`, el botón de generar se muestra en la interfaz. Sin ellas, SofIA opera automáticamente en modo solo chat. | Propiedad | Tipo | Requerido | Descripción | | -------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **template** | `object` | Opcional | Esquema JSON Schema Draft-07 completo que define la estructura de datos clínicos a generar. Necesario junto con `templateid` para habilitar la generación de reportes. Pasar como cadena JSON en atributos HTML o como objeto JavaScript programáticamente | | **templateid** | `string` | Opcional | Identificador definido por el integrador para la plantilla. Cada plantilla única debe tener su propio `templateid`. Necesario junto con `template` para habilitar la generación de reportes | **Deprecado:** La propiedad `toolsargs` ha sido renombrada a `template`. Use `template` en su lugar. `toolsargs` será eliminado en v2.0. ### `template` (Opcional — necesario para generación de reportes) JSON Schema que define la estructura para captura de datos clínicos. Cuando se proporciona junto con `templateid`, habilita la funcionalidad de generación de reportes y muestra el botón de generar en la interfaz. ```html theme={null} ``` **Requisitos del esquema:** * Debe ser un JSON Schema Draft-07 válido * Debe incluir la propiedad `$schema` * Debe definir campos requeridos apropiadamente * No debe exceder 100KB de tamaño **Ejemplo para consulta general:** ```json theme={null} { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Consulta Médica General", "type": "object", "properties": { "chief_complaint": { "type": "string", "description": "Motivo principal de la visita" }, "diagnosis": { "type": "string", "description": "Diagnóstico principal" }, "treatment_plan": { "type": "string", "description": "Tratamiento recomendado" } }, "required": ["chief_complaint", "diagnosis"] } ``` Para esquemas complejos, configura el `template` programáticamente vía JavaScript en lugar de HTML inline para evitar problemas de escape de JSON. Ver [Templates — Pasar templates al componente](/sofia/es/sdk/templates#pasar-templates-al-componente). ### `templateid` (Opcional — necesario para generación de reportes) Identificador definido por el integrador que asignas a cada plantilla. Debe proporcionarse junto con `template` para habilitar la generación de reportes. ```html theme={null} ``` **Cómo funciona:** * Tú eliges el valor de `templateid` — no lo proporciona Omniloy * Cada plantilla única debe tener su propio `templateid` * SofIA usa este ID para asociar configuraciones e historial de reportes en el servidor * Si reutilizas el mismo `templateid` con un esquema `template` diferente, la configuración anterior se sobrescribirá Usar el mismo `templateid` para esquemas de plantilla diferentes sobrescribirá la configuración anterior. Asigna siempre un `templateid` distinto a cada plantilla que utilices. **Ejemplos de nomenclatura:** * `"soap-general-v1"` — notas SOAP para medicina general * `"emergency-triage-v2"` — triaje en urgencias * `"cardiology-consult-v1"` — consultas de cardiología * `"my-clinic-intake-form"` — formulario de admisión personalizado de tu clínica ## Validación Automática El componente SofIA SDK realiza validación automática de las propiedades de configuración requeridas: * **Verificación de tipos**: Confirma que cada propiedad tiene el tipo correcto * **Validación de URLs**: Verifica que el `baseurl` resuelto usa el protocolo seguro HTTPS ### Mensajes de Error de Validación Cuando la validación falla, SofIA SDK mostrará mensajes de error detallados en la consola del navegador y evitará que el componente se monte. Esto asegura que los problemas de integración se identifiquen temprano en el proceso de desarrollo. **Ejemplo de salida de error de validación:** ``` [Sofia SDK] Configuration Error - Missing or invalid required properties: • apikey: API key for authentication • userid: Unique identifier of the healthcare professional in the EHR/HIS system • patientid: Unique identifier of the patient in the EHR/HIS system • 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" Component will not mount until all required properties are provided. Documentation: https://omniloy.mintlify.app/es/sdk/required-properties ``` **Componentes del mensaje de error:** * **Nombre de propiedad**: Identifica qué propiedad falló la validación * **Descripción**: Explica el propósito de cada propiedad * **Valor actual**: Muestra el valor inválido que se proporcionó (cuando aplica) * **Enlace de documentación**: Proporciona acceso directo a esta guía de referencia **Comportamiento del componente durante errores de validación:** * El componente SofIA SDK no establecerá conexiones * No se realizará procesamiento de datos médicos * El componente permanece en un estado seguro y no funcional * Los mensajes de error se registran para ayudar a los desarrolladores a identificar y resolver problemas rápidamente Para solución de problemas integral de errores de validación, vea nuestra [guía de solución de problemas](/sofia/es/sdk/troubleshooting). ## Ejemplo mínimo (modo solo chat) Con una clave más nueva, `apikey`, `userid` y `patientid` son todo lo que necesitas: ```html theme={null} ``` ¿Tu clave requiere un `baseurl`? Añade el que Omniloy te asignó: ```html theme={null} ``` Si alguna propiedad requerida está ausente o es inválida, el componente mostrará un error y no se conectará a los servicios de SofIA. ## Con generación de reportes Para habilitar la generación de reportes, agregue tanto `template` como `templateid`: ```html theme={null} ``` ## Ejemplo de Configuración Completa ```html theme={null} ``` ## Configuración Dinámica ### Actualizar propiedades programáticamente ```javascript theme={null} const sofiaElement = document.querySelector('sofia-sdk'); // Actualizar paciente para nueva consulta sofiaElement.setAttribute('patientid', 'patient-456'); // Actualizar esquema para diferente especialidad const cardiologySchema = { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Consulta de Cardiología", "type": "object", "properties": { "heart_rhythm": { "type": "string", "enum": ["normal", "irregular", "fast", "slow"] }, "blood_pressure": { "type": "string", "pattern": "^\\d{2,3}/\\d{2,3}$" }, "ecg_findings": { "type": "string" } }, "required": ["heart_rhythm", "blood_pressure"] }; sofiaElement.setAttribute('template', JSON.stringify(cardiologySchema)); ``` ### Configuración específica por framework **React** ```jsx theme={null} const [patientId, setPatientId] = useState('patient-123'); const [template, setTemplate] = useState({ "$schema": "http://json-schema.org/draft-07/schema#", "title": "Clinical Notes", "type": "object", "properties": { "diagnosis": { "type": "string", "description": "Primary diagnosis" } }, "required": ["diagnosis"] }); const [templateId, setTemplateId] = useState('soap-general-v1'); return ( ); ``` **Angular** ```typescript theme={null} export class AppComponent { apiKey = 'your-api-key'; userId = 'dr-lopez-456'; patientId = 'patient-789'; templateId = 'soap-general-v1'; schema = { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Clinical Notes", "type": "object", "properties": { "diagnosis": { "type": "string", "description": "Primary diagnosis" } }, "required": ["diagnosis"] }; templateJson = JSON.stringify(this.schema); } ``` ## Validación ### Lista de verificación de validación de propiedades * [ ] `apikey` es válida y no ha expirado * [ ] `baseurl` usa protocolo HTTPS (solo necesario para claves que lo requieren) * [ ] `userid` es único y consistente * [ ] `patientid` es único para la consulta * [ ] `templateid` es único por plantilla y consistente entre sesiones (si usa generación de reportes) * [ ] `template` es un JSON Schema Draft-07 válido (si usa generación de reportes) * [ ] Todas las propiedades requeridas están presentes * [ ] Ninguna propiedad excede los límites de tamaño ## Próximos Pasos Después de configurar las propiedades requeridas: 1. [Configurar propiedades opcionales](/sofia/es/sdk/optional-properties) 2. [Diseñar esquemas de datos clínicos](/sofia/es/sdk/templates) 3. [Implementar en tu framework](/sofia/es/sdk/vanilla)