Propiedades Requeridas

Estas propiedades son obligatorias para el correcto funcionamiento del componente SofIA SDK. El componente validará automáticamente la presencia y tipo de cada propiedad antes de establecer la conexión.

Referencia Rápida

Todas las propiedades del SofIA SDK en una sola tabla. Para documentación detallada, consulte Propiedades Requeridas y Propiedades Opcionales.

Propiedad	Tipo	Default	Estado	Descripción
baseurl	`string`	—	Requerida	URL del endpoint de la API REST (HTTPS)
wssurl	`string`	—	Requerida	URL WebSocket para streaming en tiempo real (WSS)
apikey	`string`	—	Requerida	Clave de autenticación proporcionada por Omniloy
userid	`string`	—	Requerida	Identificador único del profesional sanitario
patientid	`string`	—	Requerida	Identificador único del paciente para la sesión
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
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
~~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
~~toast~~	`function`	—	Deprecada	Sin efecto

Para guía de migración de propiedades deprecadas, consulte la Guía de Migración.

Propiedades de Configuración

Propiedad	Tipo	Descripción
baseurl	`string`	URL del endpoint de la API REST de SofIA. Debe usar protocolo HTTPS (ej.: `https://api.example.com/v1`)
wssurl	`string`	URL WebSocket para streaming en tiempo real. Debe usar protocolo WSS (ej.: `wss://ws.example.com`)
apikey	`string`	Clave de autenticación proporcionada por Omniloy para acceso a los servicios de SofIA

Identificadores de Sesión

Propiedad	Tipo	Descripción
userid	`string`	Identificador único del profesional sanitario en el sistema EHR/HIS
patientid	`string`	Identificador único del paciente para la sesión actual

Mejores prácticas para userid

Usar identificadores únicos persistentes
Evitar información personalmente identificable
Mantener consistencia entre sesiones
Considerar usar números de licencia profesional o IDs internos

Notas importantes sobre patientid

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.

<sofia-sdk template='{"$schema":"http://json-schema.org/draft-07/schema#","title":"Medical Consultation"}'></sofia-sdk>

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:

{
  "$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.

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

<sofia-sdk templateid="soap-general-v1"></sofia-sdk>

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 baseurl y wssurl usan protocolos seguros (HTTPS/WSS)

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:

  • 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 in the EHR/HIS system
  • patientid: Unique identifier of the patient in the EHR/HIS system
    Current value: "INVALID_BASE_URL"
    Current value: "INVALID_WSS_URL"
    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.

Ejemplo mínimo (modo solo chat)

<sofia-sdk
  baseurl="https://api.example.com/v1"
  wssurl="wss://ws.example.com"
  apikey="sk-your-api-key-here"
  userid="user_12345"
  patientid="patient_67890"
></sofia-sdk>

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:

<sofia-sdk
  baseurl="https://api.example.com/v1"
  wssurl="wss://ws.example.com"
  apikey="sk-your-api-key-here"
  userid="user_12345"
  patientid="patient_67890"
  templateid="soap-notes-v1"
  template='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Clinical Notes",
    "type": "object",
    "properties": {
      "diagnosis": {"type": "string", "description": "Primary diagnosis"}
    },
    "required": ["diagnosis"]
  }'
></sofia-sdk>

Ejemplo de Configuración Completa

<sofia-sdk
  apikey="sk-your-api-key-here"
  baseurl="https://api.example.com/v1"
  wssurl="wss://ws.example.com"
  userid="dr-garcia-456"
  patientid="patient-123"
  templateid="emergency-triage-v2"
  template='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Consulta de Emergencia",
    "type": "object",
    "properties": {
      "triage_level": {
        "type": "string",
        "enum": ["1", "2", "3", "4", "5"],
        "description": "Nivel de triaje de emergencia"
      },
      "chief_complaint": {
        "type": "string",
        "description": "Queja principal"
      },
      "vital_signs": {
        "type": "object",
        "properties": {
          "blood_pressure": {"type": "string"},
          "heart_rate": {"type": "number"},
          "temperature": {"type": "number"}
        }
      },
      "diagnosis": {
        "type": "string",
        "description": "Diagnóstico de emergencia"
      },
      "disposition": {
        "type": "string",
        "enum": ["discharge", "admit", "transfer", "observe"],
        "description": "Disposición del paciente"
      }
    },
    "required": ["triage_level", "chief_complaint", "diagnosis", "disposition"]
  }'>
</sofia-sdk>

Configuración Dinámica

Actualizar propiedades programáticamente

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

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 (
  <sofia-sdk
    apikey="sk-your-api-key-here"
    baseurl="https://api.example.com/v1"
    wssurl="wss://ws.example.com"
    userid="dr-smith-789"
    patientid={patientId}
    templateid={templateId}
    template={JSON.stringify(template)}
  />
);

Angular

export class AppComponent {
  apiKey = 'sk-your-api-key-here';
  baseUrl = 'https://api.example.com/v1';
  wssUrl = 'wss://ws.example.com';
  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
wssurl usa protocolo WSS
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:

Instalación y Configuración

Integración por Framework

Funcionalidades

Soporte

Referencia Rápida

Propiedades de Configuración

Identificadores de Sesión

Generación de Reportes

`template` (Opcional — necesario para generación de reportes)

`templateid` (Opcional — necesario para generación de reportes)

Validación Automática

Mensajes de Error de Validación

Ejemplo mínimo (modo solo chat)

Con generación de reportes

Ejemplo de Configuración Completa

Configuración Dinámica

Actualizar propiedades programáticamente

Configuración específica por framework

Validación

Lista de verificación de validación de propiedades

Próximos Pasos

Instalación y Configuración

Integración por Framework

Funcionalidades

Soporte

​Referencia Rápida

​Propiedades de Configuración

​Identificadores de Sesión

​Generación de Reportes

​template (Opcional — necesario para generación de reportes)

​templateid (Opcional — necesario para generación de reportes)

​Validación Automática

​Mensajes de Error de Validación

​Ejemplo mínimo (modo solo chat)

​Con generación de reportes

​Ejemplo de Configuración Completa

​Configuración Dinámica

​Actualizar propiedades programáticamente

​Configuración específica por framework

​Validación

​Lista de verificación de validación de propiedades

​Próximos Pasos

Referencia Rápida

Propiedades de Configuración

Identificadores de Sesión

Generación de Reportes

`template` (Opcional — necesario para generación de reportes)

`templateid` (Opcional — necesario para generación de reportes)

Validación Automática

Mensajes de Error de Validación

Ejemplo mínimo (modo solo chat)

Con generación de reportes

Ejemplo de Configuración Completa

Configuración Dinámica

Actualizar propiedades programáticamente

Configuración específica por framework

Validación

Lista de verificación de validación de propiedades

Próximos Pasos