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 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 y Propiedades Opcionales.

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
updateTemplate	function	—	Opcional	Alimenta contenido existente del EMR a la generación (pre-carga)
insertionPreviewClassNames	object	—	Opcional	Overrides de class-name para el modal de vista previa de inserción
templateExtras	object	—	Opcional	JSON Schema de categorías de acción; habilita los botones de 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)
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.

​

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.

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

​

Ejemplo mínimo (modo solo chat)

Con una clave más nueva, apikey, userid y patientid son todo lo que necesitas:

<sofia-sdk
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
></sofia-sdk>

¿Tu clave requiere un baseurl? Añade el que Omniloy te asignó:

<sofia-sdk
  apikey="your-legacy-key"
  baseurl="https://your-assigned-endpoint/v1"
  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
  apikey="your-api-key"
  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="your-api-key"
  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="your-api-key"
    userid="dr-smith-789"
    patientid={patientId}
    templateid={templateId}
    template={JSON.stringify(template)}
  />
);

Angular

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
2. Diseñar esquemas de datos clínicos
3. Implementar en tu framework