(Obsoleto) API de Llamalitica

Obsoleto

Esta documentación describe una versión anterior de la API. Por favor, consulta la nueva documentación de integración para implementar la última versión de Llamalitica en tu software.

Integración con Llamalítica mediante API

Llamalítica ofrece una solución avanzada de transcripción que convierte interacciones verbales en texto estructurado, permitiendo un análisis más profundo y la generación de informes automáticos.

Nuestro servicio se adapta a diversas necesidades mediante dos modalidades principales: transcripción desde cero y procesamiento de conversaciones previas. Ambas opciones están diseñadas para integrarse de manera fluida y eficiente en distintos entornos operativos, garantizando resultados precisos y útiles para su incorporación en las fichas médicas o EHR.

Modalidad sin conversación previa: Esta es la opción estándar. En este modo, el cliente no cuenta con una conversación transcrita previamente y desea que Llamalítica realice la transcripción directamente desde cero. La transcripción se basa en plantillas predeterminadas para analizar el contenido.
Modalidad con conversación previa: Ideal para servicios como chats en línea que ya tienen interacciones escritas entre un profesional y un paciente. Aquí, Llamalítica aplica plantillas específicas para generar resúmenes o informes basados en las conversaciones existentes.
Modalidad audio: Esta modalidad conisten en tener en una solcuion externa

Para iniciar cualquier proceso con el servicio de transcripción Llamalítica, tanto en la modalidad sin conversación previa como con conversación previa, se debe utilizar el servicio "Nuevo Caso Llamalítica". Este comando inicia un nuevo caso y asigna un UUID (Identificador Único Universal) que será utilizado para el procesamiento y tratamiento posterior del caso. Este paso asegura que cada transcripción y análisis se maneje de manera única y organizada, facilitando su seguimiento y gestión en el sistema.

Endpoint: `POST /michiQ/newCase`

Descripción:

Este endpoint maneja la creación de un nuevo caso en el sistema Michiq. Se espera que la solicitud incluya varios encabezados y archivos adjuntos en un formulario multipart/form-data.

Encabezados requeridos:

API_KEY: Clave API necesaria para autenticar la solicitud.
organization: Organización a la que pertenece el usuario.
user_mail: Correo electrónico del usuario que realiza la solicitud.
Authorization (opcional): Token JWT para validar la sesión actual del usuario.
template (opcional): ID de plantilla para generar un resumen.

Archivos esperados en la solicitud:

ehr: Archivo JSON que contiene la historia clínica.
files: Uno o más archivos PDF, TXT, etc.

Parámetros del cuerpo esperados:

conversation: Texto que representa una conversación.

Ejemplo de solicitud:

POST /michiQ/newCase HTTP/1.1 Host: https://lamalitica.com/ Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW API_KEY: your_api_key organization: your_organization user_mail: user@example.com Authorization: Bearer your_jwt_token template: 1 ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="conversation" This is a sample conversation. ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="ehr"; filename="ehr.json" Content-Type: application/json { "patient": "John Doe", "age": 30, "conditions": ["hypertension"] } ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="files"; filename="document1.pdf" Content-Type: application/pdf <binary content> ------WebKitFormBoundary7MA4YWxkTrZu0gW--

Ejemplo de respuesta:

{
  "michiq_uuid": "generated_uuid",
  "token": "generated_token",
  "message": "You are inside llamalitica services",
  "voice": 2221,
  "ehr": 1,
  "documents": 3
}

Detalles del procesamiento:

Verificar la clave API:
- Se verifica que la clave API proporcionada en el encabezado API_KEY sea válida. Si no es válida, se devuelve un error 401 (Unauthorized).
Verificar existencia del usuario:
- Se verifica que el usuario especificado en el encabezado user_mail exista en la organización proporcionada en el encabezado organization. Si no existe, se devuelve un error 401 (Unauthorized).
Validar el token de autorización (si se proporciona):
- Si se proporciona un token en el encabezado Authorization, se valida contra el usuario. Si la validación falla, se devuelve un error 401 (Unauthorized).
- Si no se proporciona el token, se genera uno nuevo para la sesión.
Leer y validar el archivo JSON de la historia clínica:
- Se lee el archivo ehr proporcionado y se valida. Si hay un error en la lectura, se devuelve un error 500 (Internal Server Error).
Leer y extraer texto de los archivos PDF:
- Se leen los archivos PDF proporcionados y se extrae el texto de cada uno. Si hay un error en la lectura o extracción, se devuelve un error 500 (Internal Server Error).
Crear la metadata del audio y serializarla a JSON:
- Se crea un objeto de metadata con los datos de la conversación, los documentos PDF y la historia clínica. Este objeto se serializa a JSON.
Crear un documento Michiq con la metadata serializada:
- Se crea un nuevo documento Michiq utilizando la metadata serializada y se guarda en el sistema. Si hay un error al guardar, se devuelve un error 500 (Internal Server Error).
Generar un resumen usando una plantilla (opcional):
- Si se proporciona un ID de plantilla en el encabezado template, se genera un resumen utilizando esa plantilla.
Devolver el UUID del nuevo documento y otros detalles en la respuesta:
- Se devuelve el UUID del nuevo documento creado, el token generado, y el conteo de tokens de voz, documentos EHR y files en la respuesta JSON.

Notas:

Asegúrate de manejar adecuadamente los errores y devolver mensajes claros en caso de fallos en cualquiera de los pasos del proceso.
La limitación del tamaño del formulario multipart está configurada en 10 MB. Puedes ajustarlo según las necesidades de tu aplicación.

Procedimientos Post-Respuesta Exitosa

Opcional: Audio a Texto - Transcripción

Si no se dispone previamente de una conversación transcrita y se desea activar el servicio de transcripción de audio durante la visita, se puede utilizar la interfaz de Llamalítica. Si este procedimiento no es necesario, puedes omitir este paso y proceder directamente a "Acceso a Caso".

Siguiente Paso: Acceso al Audio

Tras recibir una respuesta exitosa del endpoint 'NewCase', el sistema debe realizar una llamada adicional utilizando el 'michiq_uuid' proporcionado en la respuesta inicial para acceder a los detalles del caso.

URL de Acceso al Caso:

GET /app/encounter/{michiq_uuid}

Donde {michiq_uuid} debe ser reemplazado por el UUID recibido, como se muestra en el siguiente ejemplo:

Ejemplo de Uso con cURL:

curl -X GET "https://lamalitica.com/app/encounter/{el numero michiq_uuid}" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {your_access_token}"

Autenticación y Autorización:

Para acceder a los servicios, es esencial que el usuario esté registrado y dado de alta en el sistema. La llamada a este endpoint debe incluir un token de autenticación válido, proporcionado durante el proceso de registro o login del usuario.

Validaciones:

Token de Autenticación: Se requiere un token válido en la cabecera Authorization para acceder a este endpoint. Si el token no es válido o ha expirado, el servidor devolverá un error Unauthorized.
Acceso al Recurso: Solo los usuarios con permisos adecuados podrán acceder a los detalles del caso. Si un usuario intenta acceder a un recurso sin los permisos adecuados, recibirá un error Forbidden.

Respuestas:

200 OK: Devuelve los detalles del caso.
401 Unauthorized: Indica que el token de autenticación es inválido o ha expirado.
403 Forbidden: Acceso denegado debido a permisos insuficientes.
404 Not Found: El UUID proporcionado no corresponde a ningún caso existente.

Ver Caso

Endpoint: GET /michiQ/doc/{id}

Descripción: Este endpoint recupera un documento y sus metadatos asociados utilizando el UUID proporcionado en la URL. Está protegido con un token de autorización para asegurar que solo los usuarios autenticados y autorizados puedan acceder a sus documentos.

Parámetros de la ruta:

id (string): UUID del documento a recuperar.

Autenticación:

Los usuarios deben estar autenticados mediante un Token Bearer proporcionado en el encabezado de Autorización.

Respuestas:

200 OK: La solicitud ha tenido éxito y el documento junto con sus metadatos son devueltos.
404 Not Found: No se encuentra ningún documento que corresponda al UUID proporcionado.
401 Unauthorized: El token no se ha proporcionado o es inválido o ha expirado.

Respuesta de muestra:


{  "document":  {  "michiq_uuid":  "ejemplo-uuid",  "username":  "john_doe",  "timestamp":  "2024-01-01T12:00:00Z",  ... },  "metadata":  {  "username":  "john_doe",  "creationDate":  "2024-01-01T12:00:00Z",  "fileExtension":  ".pdf",  ... }  }

Manejo de errores: La API utiliza códigos de estado HTTP estándar para indicar el éxito o fracaso de las solicitudes. Los errores proporcionan una breve explicación en el cuerpo de la respuesta.

Seguridad: El endpoint implementa controles para asegurar que el solicitante esté autorizado para acceder al documento. Compara el de usuario asociado con el documento sea el autor, solo los autores de los documentos pueden recuperarlos.

Ejemplo:

curl -X GET "https://llamalitica.com/michiQ/doc/{uuid_del_documento}" \ -H "Authorization: Bearer {tu_token_de_acceso}" \ -H "Content-Type: application/json"

Integración Avanzada de Speech to Text

Endpoint: `/michiQ/speechToText/{id}`

Descripción

Este endpoint permite la transcripción de audio a texto utilizando el servicio de reconocimiento de voz.

Método

POST

Parámetros de la URL

id (cadena): Identificador único asociado con la transcripción de audio.

Encabezados

Authorization (cadena): Token de autorización necesario para acceder al servicio.

Respuestas

Códigos de estado:
- 200 OK: La transcripción se realizó con éxito.
- 400 Bad Request: Se proporcionaron datos incorrectos o incompletos.
- 401 Unauthorized: Falta o es incorrecto el token de autorización.
- 500 Internal Server Error: Error interno del servidor.

Respuesta exitosa

Si la transcripción se realizó con éxito, la respuesta contendrá un objeto JSON con la transcripción y otros detalles asociados con la tarea de transcripción.

Ejemplo de respuesta exitosa:

{
  "transcription": "Texto de la transcripción",
  "totalSpeechTextTime": "hh:mm:ss",
  "...": "otros campos de metadatos"
}

Ejemplo de solicitud

POST /michiQ/speechToText/123456789 HTTP/1.1 Host: llamalitica.com Authorization: Bearer <token> Content-Type: application/json { "audioFile": "ruta/al/archivo/audio.mp3" }

Ejemplo de respuesta exitosa

HTTP/1.1 200 OK Content-Type: application/json { "transcription": "El texto de la transcripción", "totalSpeechTextTime": "00:05:27", // Otros campos de metadatos }

Endpoint: `/michiQ/uploadAudio/{id}`

Descripción

Este endpoint permite subir archivos de audio para su posterior procesamiento.

Método

POST

Parámetros de la URL

id (cadena): Identificador único asociado con la carga del archivo de audio.

Encabezados

Authorization (cadena): Token de autorización necesario para acceder al servicio.

Cuerpo de la solicitud

El cuerpo de la solicitud debe contener el archivo de audio a subir. Se espera que el archivo se envíe utilizando el formulario multipart (multipart/form-data) con el nombre del campo audioChunk.

Respuestas

Códigos de estado:
- 200 OK: La carga del archivo se realizó con éxito.
- 400 Bad Request: Se proporcionaron datos incorrectos o incompletos.
- 401 Unauthorized: Falta o es incorrecto el token de autorización.
- 405 Method Not Allowed: El método de solicitud no es compatible (solo se permite POST).
- 500 Internal Server Error: Error interno del servidor.

Ejemplo de solicitud

POST /michiQ/uploadAudio/123456789 HTTP/1.1 Host: llamalitica.com Authorization: Bearer <token> Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="audioChunk"; filename="audio.mp3" Content-Type: audio/mpeg <archivo de audio en formato MP3> ----WebKitFormBoundary7MA4YWxkTrZu0gW

Ejemplo de respuesta exitosa

HTTP/1.1 200 OK Content-Type: text/plain Archivo subido exitosamente con UUID: 123456789

Endpoint: `/michiQ/encounters`

Descripción

Este endpoint devuelve los encuentros asociados a un usuario de la plataforma MichiQ.

Método

GET

Parámetros de URL

Ninguno

Encabezados

Authorization: Token de autenticación requerido. Debe ser proporcionado en el formato Bearer {token}.

Respuesta exitosa

Código: 200 OK
Contenido: Una lista de encuentros en formato JSON.

Ejemplo de Llamada

curl -X GET \  -H "Authorization: Bearer {tu_token_de_autenticación}"  \  <https://llamalitica.com/michiQ/encounters>

Estructura de los Encuentros (JSON)

Cada encuentro sigue la estructura definida por el tipo MichiqDocument.

Estructura del tipo `MichiqDocument`

MichiqUUID (string): UUID único del encuentro.
Timestamp (time.Time): Fecha y hora del encuentro.
Username (string): Nombre de usuario asociado al encuentro.
OrganizationID (string): ID de la organización asociada al encuentro.
TokensGenerated (int): Número de tokens generados durante el encuentro.
TokensInput (int): Número de tokens de entrada durante el encuentro.
Cost (float64): Costo asociado al encuentro.
RuntimeMs (int): Tiempo de ejecución en milisegundos del encuentro.
Temperature (float64): Temperatura asociada al encuentro.
Input (json.RawMessage): Datos de entrada en formato JSON.
GeneratedText (string, opcional): Texto generado durante el encuentro.
MichiqCoreVersion (string, opcional): Versión del núcleo de MichiQ asociada al encuentro.
AcrVersion (string, opcional): Versión del Reconocedor Automático de Contexto (ACR) asociada al encuentro.
UserScore (int, opcional): Puntuación del usuario asociada al encuentro.
StructuredData (json.RawMessage): Datos estructurados asociados al encuentro en formato JSON.

Respuestas de error

Código: 405 Method Not Allowed
- Contenido: "Método no permitido"
Código: 401 Unauthorized
- Contenido: "Error al obtener el token de autorización"
Código: 500 Internal Server Error
- Contenido: "Error obteniendo datos del usuario", "Error al obtener los encuentros", "Error al codificar la respuesta como JSON"

Esta documentación describe el endpoint /michiQ/encounters y la estructura de los encuentros devueltos por este endpoint. Asegúrate de tener definidos correctamente los modelos y funciones auxiliares mencionados en el código para que el endpoint funcione correctamente. Además, recuerda incluir el token de autenticación en la llamada a este endpoint.

Endpoint: QueryCase

POST /michiQ/query/{id}

Descripción

Este endpoint permite realizar una consulta al caso especificado por su UUID. La consulta se envía en el cuerpo de la solicitud y el resultado se devuelve en formato JSON.

Encabezados

Authorization: Token de autenticación requerido. Debe ser proporcionado en el formato Bearer {token}.
Content-Type: application/json

Parámetros

Path Parameters

id (string): El UUID del documento Michiq.

Request Body

El cuerpo de la solicitud debe ser un JSON con la siguiente estructura:

{ "query": "string" }

query (string): La consulta que se va a realizar. Este campo es obligatorio.

Ejemplo de Solicitud

curl -X POST \ https://llamalitica.com/michiQ/query/12345 \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "query": "Evolución del TAS del paciente interanual" }'

Respuesta

La respuesta será un JSON con el resultado de la consulta:

Ejemplo de Respuesta Exitosa

{ "response": "Esto es una respuesta de ejemplo" }

Posibles Errores

400 Bad Request

ID audio no proporcionado: Si el parámetro id no está presente en la URL.
Error al procesar la solicitud: Si hay un error al decodificar el cuerpo de la solicitud JSON.
Query no proporcionada: Si el campo query en el cuerpo de la solicitud está vacío.

401 Unauthorized

Authorization token missing or invalid: Si el encabezado de autorización no está presente o el token es inválido.

500 Internal Server Error

Error al generar la respuesta: Si ocurre un error interno durante el procesamiento de la consulta.

Ejemplo de Flujo

Solicitud:
- Método: POST
- URL: https://llamalitica.com/michiQ/query/12345uuid
- Encabezados:
  - Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  - Content-Type: application/json
- Cuerpo:
```
{ "query": "Cual es la última temperatura registrada al paciente ?" }
```

Respuesta:

Código HTTP: 200 OK
Cuerpo:

{ "response": "Temperatura fué de 38.7C el dia de hoy a las 21:00" }

(Obsoleto) API de Llamalitica

Integración con Llamalítica mediante API

Endpoint: POST /michiQ/newCase​

Descripción:​

Encabezados requeridos:​

Archivos esperados en la solicitud:​

Parámetros del cuerpo esperados:​

Ejemplo de solicitud:​

Ejemplo de respuesta:​

Detalles del procesamiento:​

Notas:​

Procedimientos Post-Respuesta Exitosa

Opcional: Audio a Texto - Transcripción​

URL de Acceso al Caso:​

Ejemplo de Uso con cURL:​

Autenticación y Autorización:​

Validaciones:​

Respuestas:​

Ver Caso

Integración Avanzada de Speech to Text

Endpoint: /michiQ/speechToText/{id}​

Descripción​

Método​

Parámetros de la URL​

Encabezados​

Respuestas​

Respuesta exitosa​

Ejemplo de solicitud​

Ejemplo de respuesta exitosa​

Endpoint: /michiQ/uploadAudio/{id}​

Descripción​

Método​

Parámetros de la URL​

Encabezados​

Cuerpo de la solicitud​

Respuestas​

Ejemplo de solicitud​

Ejemplo de respuesta exitosa​

Endpoint: /michiQ/encounters​

Descripción​

Método​

Parámetros de URL​

Encabezados​

Respuesta exitosa​

Ejemplo de Llamada​

Estructura de los Encuentros (JSON)​

Estructura del tipo MichiqDocument​

Respuestas de error​

Endpoint: QueryCase​

Descripción​

Encabezados​

Parámetros​

Path Parameters​

Request Body​

Ejemplo de Solicitud​

Respuesta​

Ejemplo de Respuesta Exitosa​

Posibles Errores​

400 Bad Request​

401 Unauthorized​

500 Internal Server Error​

Ejemplo de Flujo​

Endpoint: `POST /michiQ/newCase`

Descripción:

Encabezados requeridos:

Archivos esperados en la solicitud:

Parámetros del cuerpo esperados:

Ejemplo de solicitud:

Ejemplo de respuesta:

Detalles del procesamiento:

Notas:

Opcional: Audio a Texto - Transcripción

URL de Acceso al Caso:

Ejemplo de Uso con cURL:

Autenticación y Autorización:

Validaciones:

Respuestas:

Endpoint: `/michiQ/speechToText/{id}`

Descripción

Método

Parámetros de la URL

Encabezados

Respuestas

Respuesta exitosa

Ejemplo de solicitud

Ejemplo de respuesta exitosa

Endpoint: `/michiQ/uploadAudio/{id}`

Descripción

Método

Parámetros de la URL

Encabezados

Cuerpo de la solicitud

Respuestas

Ejemplo de solicitud

Ejemplo de respuesta exitosa

Endpoint: `/michiQ/encounters`

Descripción

Método

Parámetros de URL

Encabezados

Respuesta exitosa

Ejemplo de Llamada

Estructura de los Encuentros (JSON)

Estructura del tipo `MichiqDocument`

Respuestas de error

Endpoint: QueryCase

Descripción

Encabezados

Parámetros

Path Parameters

Request Body

Ejemplo de Solicitud

Respuesta

Ejemplo de Respuesta Exitosa

Posibles Errores

400 Bad Request

401 Unauthorized

500 Internal Server Error

Ejemplo de Flujo