Quickstart

De cero a una integración funcional de SofIA en 5 minutos

​

Lo que vas a construir

Al final de esta guía, tendrás SofIA SDK funcionando en tu aplicación web — capturando una conversación clínica, generando un reporte estructurado y recibiéndolo en tu código a través de un callback. Verás el objeto del reporte en la consola de tu navegador.

Tiempo estimado: 5 minutos (después de recibir credenciales)

​

Requisitos previos

• Node.js 18.17.0 o superior
• HTTPS habilitado en tu entorno de desarrollo (requerido para captura de audio). Para desarrollo local, usa npx local-ssl-proxy o consulta la guia de instalacion para mas detalles.
• Credenciales Omniloy — un apikey (y un baseurl si tu clave lo requiere; Omniloy te lo indica). Las claves más nuevas resuelven el endpoint automáticamente.

¿Necesitas credenciales? Envía un email a [e-mail] con:

• Tu nombre de empresa y descripción del proyecto
• Uso esperado (número aproximado de consultas/mes)
• Si necesitas un entorno sandbox para pruebas

El equipo de Omniloy te proporcionará tu apikey. Para las claves más nuevas el SDK selecciona el endpoint automáticamente — sin necesidad de baseurl; otras claves también incluyen un baseurl que debes configurar. Omniloy te indica cuál aplica a la tuya. El tiempo de respuesta habitual es de 1-2 días laborables.

​

1. Instalar

npm install @omniloy/sofia-sdk

// En tu archivo de entrada (main.js, index.js, etc.)
import '@omniloy/sofia-sdk';

Alternativamente, carga vía CDN sin necesidad de build:

<script src="https://unpkg.com/@omniloy/sofia-sdk@latest/dist/webcomponents.umd.js"></script>

​

2. Pega este código

Copia lo siguiente en tu HTML. Reemplaza el placeholder de credencial con el valor de Omniloy. Con una clave más nueva solo necesitas apikey (más userid/patientid) — el endpoint se selecciona automáticamente.

<sofia-sdk
  apikey="your-api-key"
  userid="doctor-demo-001"
  patientid="patient-demo-001"
  templateid="quickstart-v1"
  template='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Consulta Quickstart",
    "type": "object",
    "properties": {
      "motivo_consulta": {
        "type": "string",
        "description": "Motivo principal de la consulta"
      },
      "diagnostico": {
        "type": "string",
        "description": "Diagnóstico principal"
      },
      "plan_tratamiento": {
        "type": "string",
        "description": "Tratamiento recomendado"
      }
    },
    "required": ["motivo_consulta", "diagnostico"]
  }'
></sofia-sdk>

<script>
  // Esperar a que el web component se registre
  customElements.whenDefined('sofia-sdk').then(() => {
    const sofia = document.querySelector('sofia-sdk');

    // Se ejecuta cuando SofIA genera un reporte clínico
    sofia.handleReport = (report) => {
      console.log('Reporte recibido:', report);
      // Procesa el reporte en tu aplicación:
      // ej., mostrarlo, guardarlo en tu EHR, o enviarlo a tu backend
    };

    // Se ejecuta cuando el componente se abre o cierra
    sofia.setIsOpen = (isOpen) => {
      console.log('SofIA está', isOpen ? 'abierto' : 'cerrado');
    };
  });
</script>

Tanto template como templateid son necesarios para la generación de reportes. Sin ellos, SofIA sigue funcionando — los usuarios pueden grabar audio, transcribir conversaciones y usar el chat clínico — pero el botón de generar no aparecerá. El template es el JSON Schema que los agentes de IA de SofIA usan para extraer datos estructurados de la conversación; sin él, no hay esquema que llenar ni reporte que generar.

Si necesitas enviar preferencias visuales de accesibilidad en tu integración, añade la variable accessibility al mismo nivel de template/toolsargs en tu payload de configuración. Ver Templates — Accesibilidad (a11y).

Tu eliges el valor de templateid — es tu propio identificador para esta plantilla. Usa cualquier cadena descriptiva (por ejemplo, quickstart-v1, soap-notes-v1). No necesita estar registrado en ningun lugar previamente.

​

3. Ejecutar y verificar

Abre tu página en el navegador. Deberías ver:

1. SofIA se abre automáticamente — la interfaz de chat aparece (por defecto: abierta)
2. Solicitud de acceso al micrófono — permítelo para habilitar la transcripción de audio
3. Interfaz de chat lista — puedes hablar o escribir para interactuar con SofIA
4. Botón de generar visible — porque tanto template como templateid están configurados

Después de una conversación, haz clic en el botón generar. Abre la consola del navegador (F12 → pestaña Consola). Deberías ver:

Reporte recibido: { motivo_consulta: "...", diagnostico: "...", plan_tratamiento: "..." }

​

Qué devuelve handleReport

El callback recibe un objeto JavaScript plano cuyas claves coinciden con tu schema template. Sin wrapper, sin metadata — solo los datos clínicos extraídos.

Para el schema anterior, el reporte se ve así:

{
  "motivo_consulta": "Paciente refiere cefalea persistente de 3 días",
  "diagnostico": "Cefalea tensional",
  "plan_tratamiento": "Ibuprofeno 400mg cada 8 horas durante 5 días. Control si persisten los síntomas."
}

Los valores exactos son extraídos por los agentes de IA de SofIA a partir de la conversación de la consulta y el contexto del paciente. Las claves siempre corresponden a las properties definidas en tu schema template.

También puedes obtener el último reporte generado posteriormente usando setGetLastReport. Consulta Propiedades Opcionales para más detalles.

​

Modo solo chat

Si no necesitas generación de reportes, omite template y templateid. SofIA operará como asistente de chat clínico — no aparece el botón de generar.

<sofia-sdk
  apikey="your-api-key"
  userid="doctor-demo-001"
  patientid="patient-demo-001"
></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="doctor-demo-001"
  patientid="patient-demo-001"
></sofia-sdk>

​

Ejemplo completo standalone

Aquí tienes un archivo HTML completo que puedes guardar y abrir directamente:

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>SofIA SDK — Quickstart</title>
  <script src="https://unpkg.com/@omniloy/sofia-sdk@latest/dist/webcomponents.umd.js"></script>
</head>
<body>
  <h1>SofIA Quickstart</h1>

  <sofia-sdk
    apikey="your-api-key"
    userid="doctor-demo-001"
    patientid="patient-demo-001"
    templateid="quickstart-v1"
    template='{
      "$schema": "http://json-schema.org/draft-07/schema#",
      "title": "Consulta Quickstart",
      "type": "object",
      "properties": {
        "motivo_consulta": { "type": "string", "description": "Motivo de consulta" },
        "diagnostico": { "type": "string", "description": "Diagnóstico principal" },
        "plan_tratamiento": { "type": "string", "description": "Tratamiento recomendado" }
      },
      "required": ["motivo_consulta", "diagnostico"]
    }'
  ></sofia-sdk>

  <div id="report-output"></div>

  <script>
    customElements.whenDefined('sofia-sdk').then(() => {
      const sofia = document.querySelector('sofia-sdk');

      sofia.handleReport = (report) => {
        console.log('Reporte recibido:', report);
        document.getElementById('report-output').innerHTML =
          '<h2>Reporte Generado</h2><pre>' +
          JSON.stringify(report, null, 2) +
          '</pre>';
      };
    });
  </script>
</body>
</html>

​

Próximos pasos

1. Propiedades Requeridas — entiende cada parámetro de configuración
2. Esquemas de Datos Clínicos — diseña schemas para tu especialidad
3. Guías por Framework — integra con React, Angular o vanilla JS