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

# 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](/sofia/es/sdk/installation#https-protocol) 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.

<Info>
  **¿Necesitas credenciales?** Envía un email a [support@omniloy.com](mailto:support@omniloy.com) 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.
</Info>

## 1. Instalar

```bash theme={null}
npm install @omniloy/sofia-sdk
```

```javascript theme={null}
// En tu archivo de entrada (main.js, index.js, etc.)
import '@omniloy/sofia-sdk';
```

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

```html theme={null}
<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.

```html theme={null}
<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>
```

<Warning>
  **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.
</Warning>

<Tip>
  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)](/sofia/es/sdk/templates#accesibilidad-a11y).
</Tip>

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

## 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í:

```json theme={null}
{
  "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`.

<Tip>
  También puedes obtener el último reporte generado posteriormente usando `setGetLastReport`. Consulta [Propiedades Opcionales](/sofia/es/sdk/optional-properties) para más detalles.
</Tip>

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

```html theme={null}
<sofia-sdk
  apikey="your-api-key"
  userid="doctor-demo-001"
  patientid="patient-demo-001"
></sofia-sdk>
```

<Tip>
  **¿Tu clave requiere un `baseurl`?** Añade el que Omniloy te asignó:

  ```html theme={null}
  <sofia-sdk
    apikey="your-legacy-key"
    baseurl="https://your-assigned-endpoint/v1"
    userid="doctor-demo-001"
    patientid="patient-demo-001"
  ></sofia-sdk>
  ```
</Tip>

## Ejemplo completo standalone

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

```html theme={null}
<!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](/sofia/es/sdk/required-properties)** — entiende cada parámetro de configuración
2. **[Esquemas de Datos Clínicos](/sofia/es/sdk/templates)** — diseña schemas para tu especialidad
3. **[Guías por Framework](/sofia/es/sdk/vanilla)** — integra con React, Angular o vanilla JS