API y asistentes de IA

La API permite usar los datos del laboratorio desde otros programas: una planilla de Excel que se actualiza sola, un script en Python que arma un reporte, un equipo que registra sus muestras al terminar una corrida o un sistema del instituto que necesita saber dónde está una muestra o cuánto queda de un reactivo.

Cada programa se identifica con un token: una clave larga que empieza con trz_. Un token actúa en tu nombre, solo en este laboratorio y con el permiso que elijas al crearlo. Lo que hace queda en el historial como hecho por vos, vía API.

Con un token de Lector/a solo se consulta. Con uno de Editor/a también se carga y se modifica: muestras, equipos, mantenimientos, reservas, insumos, lotes, consumos, pedidos y alarmas de temperatura (ver Cargar y modificar datos). Cada cambio queda en el historial del registro con tu nombre y «vía API · <nombre del token>», igual que si lo hubieras hecho desde la web.

Encender la API (administración)

La API viene apagada en cada laboratorio. Para encenderla, la administración va a Acceso por API y toca Encender.

Desde esa misma pantalla la administración ve los tokens de todas las personas y puede revocar cualquiera. Si la apaga, todos los tokens dejan de funcionar hasta que la vuelva a encender (no se borran).

Crear un token

1. Andá a Acceso por API. Si no administrás el laboratorio, lo encontrás en el menú junto a Ayuda, cuando la API está encendida.
2. Tocá Crear token y completá:
   • Nombre: dónde lo vas a usar, por ejemplo «Planilla de stock».
   • Qué puede hacer: como mucho, tu propio rol. Para leer datos alcanza con Lector/a; para cargar o modificar, hace falta Editor/a.
   • Vence en: 30, 90, 180 días o un año.
3. Copiá el token y guardalo donde lo vayas a usar o en un gestor de contraseñas. Vialo no lo guarda y no lo vas a poder ver de nuevo. Si lo perdés, revocalo y creá otro.

Cada persona puede tener hasta 10 tokens vigentes por laboratorio.

Tratá el token como una contraseña: quien lo tenga puede ver los datos del laboratorio en tu nombre. No lo pegues en una planilla compartida ni en un mensaje. Si creés que se filtró, revocalo: deja de funcionar en ese mismo momento.

Qué podés consultar

La dirección de la API es la de Vialo seguida de /api/v1. En los ejemplos aparece como https://vialo.ejemplo.org/api/v1: reemplazala por la de tu laboratorio.

La lista completa, con todos los parámetros, está en /api/v1/openapi.json. Es una descripción estándar (OpenAPI) que muchas herramientas saben leer.

Filtros de muestras

Se agregan a la dirección después de un ? y se combinan con &. Una muestra aparece si cumple todos los filtros.

Filtros de equipos

Filtros de insumos

El stock de un insumo no cuenta los lotes vencidos y está en la unidad del insumo (unit).

Sensores y alarmas

Un sensor se indica por su id o, si su equipo tiene uno solo, por el código del equipo (/monitoring/sensors/EQ-0003). El período de /monitoring/sensors/<id> y de readings se elige con period (24h, 7d o 30d, hasta ahora; por defecto 24h) o con from y to (días AAAA-MM-DD en la hora del laboratorio, hasta un año). Las lecturas vienen resumidas: el período se divide en tramos y de cada uno llegan la más baja y la más alta, así un pico corto no se pierde. Las temperaturas están en °C.

El state de cada sensor es ok (en rango), out (fuera de rango, todavía dentro de la demora), alarm (fuera de rango más tiempo que la demora), offline (dejó de mandar lecturas o está desconectado) o waiting (nunca mandó). /monitoring/alarms devuelve solo lo que llegó a alarma; con pending=true, las que todavía no tienen anotado qué se hizo.

Las horas de las reservas y del registro de uso vienen en UTC (2026-10-24T13:00:00Z); la zona horaria del laboratorio está en /lab. Los días de from y to se toman en la hora del laboratorio.

Los valores de los campos personalizados vienen en custom_fields, con la clave de cada campo (la que devuelven /biobank/fields, /equipment/fields y /reagents/fields). En las listas se devuelve el texto de la opción elegida.

Cargar y modificar datos

Con un token de Editor/a también se puede escribir. Los datos van en el cuerpo del pedido, en JSON, con el encabezado Content-Type: application/json. Se aplican las mismas reglas que en la web: los campos obligatorios del laboratorio, que una posición esté libre, que haya stock para consumir, que una reserva no choque con otra.

• Historial. Cada cambio queda en el historial del registro con tu nombre y «vía API · <nombre del token>». Lo ve cualquiera que abra el registro en la web.
• Códigos. Los códigos nuevos (muestras, equipos, insumos, lotes) los asigna Vialo con el formato del laboratorio. La respuesta trae el registro creado, con su código y su id.
• Campos personalizados. Van en custom_fields, con la clave de cada campo. En las listas se puede mandar el texto de la opción («EDTA»). Al editar, solo cambian las claves que mandás; null borra un valor.
• Versión. Para editar (PATCH) hay que mandar la version que devolvió la API al leer el registro. Si otra persona lo cambió mientras tanto, la respuesta es 409 y no se pisa nada: volvé a leerlo y decidí.
• Reintentos sin duplicar. En los POST podés mandar el encabezado Idempotency-Key con una clave única por operación (por ejemplo un UUID). Si el pedido se repite con la misma clave en las 24 horas siguientes (porque se cortó la conexión, por ejemplo), no se vuelve a ejecutar: recibís la primera respuesta, con el encabezado Idempotent-Replayed: true.
• Borrar. Solo se pueden borrar muestras (DELETE), y es un borrado lógico: la administración las puede restaurar desde «Borradas». Los asistentes de IA no borran.

Biobanco

Con una caja y sin position, cada muestra va al primer lugar libre. El type va por nombre o por id (ver /biobank/sample-types) y la caja por su id (ver /biobank/locations).

Equipos

Las horas van como instantes ISO 8601 con zona (2026-10-24T10:00:00-03:00). Las personas (responsable, quién lo hizo, para quién es la reserva) se indican por id, nombre o email. Por API, reservar, registrar usos y reportar fallas también piden un token de Editor/a.

Insumos

Los lotes se indican por su id o por su código interno. Un lote vencido pide confirm_expired: true para consumirlo, y las sustancias controladas piden reason en cada movimiento, igual que en la web.

Monitoreo

Conectar un sensor nuevo y generar su clave se hace solo desde la web: la clave se muestra una vez y no conviene que pase por scripts ni asistentes.

Ejemplos

Probar el token

curl -H "Authorization: Bearer trz_tu_token" https://vialo.ejemplo.org/api/v1/lab

Python: todas las muestras de plasma disponibles

import requests

API = "https://vialo.ejemplo.org/api/v1"
HEADERS = {"Authorization": "Bearer trz_tu_token"}

muestras, pagina = [], 1
while True:
    r = requests.get(
        f"{API}/biobank/samples",
        headers=HEADERS,
        params={"type": "Plasma", "status": "available", "limit": 200, "page": pagina},
    )
    r.raise_for_status()
    datos = r.json()
    muestras += datos["data"]
    if pagina * datos["limit"] >= datos["total"]:
        break
    pagina += 1

for m in muestras:
    lugar = m["placement"]
    print(m["code"], lugar["path"] + " · " + lugar["position"] if lugar else "sin ubicar")

Python: cargar las muestras de una corrida

import csv, uuid, requests

API = "https://vialo.ejemplo.org/api/v1"
HEADERS = {"Authorization": "Bearer trz_token_de_editor"}

with open("corrida.csv", newline="", encoding="utf-8") as f:
    muestras = [
        {
            "type": "Plasma",
            "donor_code": fila["donante"],
            "collection_date": fila["fecha"],  # AAAA-MM-DD
            "quantity": float(fila["volumen"]),
            "box_id": "<id de la caja>",  # va al primer lugar libre
            "custom_fields": {"anticoagulante": "EDTA"},
        }
        for fila in csv.DictReader(f)
    ]

r = requests.post(
    f"{API}/biobank/samples",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={"samples": muestras[:100]},  # hasta 100 por pedido
)
if r.status_code != 201:
    print(r.json()["error"])  # el mensaje dice qué fila y qué campo revisar
else:
    for m in r.json()["data"]:
        print(m["code"], m["placement"]["position"] if m["placement"] else "sin ubicar")

Corregir un dato

curl -X PATCH https://vialo.ejemplo.org/api/v1/biobank/samples/PL-2026-00042   -H "Authorization: Bearer trz_token_de_editor"   -H "Content-Type: application/json"   -d '{"version": 3, "quantity": 180, "custom_fields": {"hemolisis": "Leve"}}'

Excel: una tabla que se actualiza

1. En Excel, Datos → Obtener datos → De otras fuentes → Desde la web.
2. Elegí Avanzado y pegá la dirección, por ejemplo https://vialo.ejemplo.org/api/v1/biobank/samples?limit=200.
3. En Parámetros de encabezado de solicitud HTTP, escribí Authorization y, al lado, Bearer trz_tu_token.
4. En el editor que se abre, expandí la columna data para tener una fila por muestra. Con Actualizar se vuelven a traer los datos.

El token queda guardado en el archivo de Excel. Usá uno de Lector/a creado solo para esa planilla y no la compartas fuera del laboratorio.

Límites y errores

Cada token puede hacer 60 pedidos por minuto para consultar y 20 por minuto para cargar o modificar (se cuentan por separado). Si se pasa, la respuesta dice cuántos segundos esperar. El cuerpo de un pedido puede tener hasta 1 MB. Las respuestas traen los encabezados X-RateLimit-Remaining (pedidos que quedan) y X-RateLimit-Reset (cuándo se renueva el minuto).

Cuando algo sale mal, la respuesta trae un código y un mensaje en español:

Sensores de temperatura

Los sensores de heladeras y freezers no usan un token de persona: cada sensor tiene su propia clave (empieza con vsn_), que se genera en Vialo al conectarlo en el módulo Monitoreo. La clave no vence y solo sirve para cargar lecturas de ese sensor; no hace falta encender el acceso por API.

POST /api/v1/monitoring/readings
Authorization: Bearer vsn_…        (o X-Sensor-Key: vsn_…)
Content-Type: application/json

{ "value": -18.4 }

Para mandar varias lecturas con su hora (por ejemplo, las que el dispositivo guardó sin conexión): { "readings": [{ "measured_at": "2026-10-25T10:00:00Z", "value": -18.4 }, …] }. measured_at es opcional (ISO o segundos desde 1970); sin hora se usa la de llegada. Hasta 500 lecturas por pedido y 30 pedidos por minuto por sensor. Una lectura con la misma hora que otra ya guardada se ignora, así que reintentar es seguro. La respuesta dice cuántas llegaron y cuántas eran nuevas:

{ "sensor_id": "…", "received": 1, "accepted": 1, "duplicates": 0 }

Las alarmas (fuera de rango más tiempo que la demora del sensor) y el aviso de «sin datos» los calcula Vialo. Hay un ejemplo para armar un sensor con un ESP32 en la guía Armar o conectar un sensor del centro de ayuda.

Para consultar las temperaturas y las alarmas, o anotar qué se hizo con una alarma, desde un script o un asistente de IA, se usa un token de persona como en el resto de la API (ver Sensores y alarmas y Monitoreo).

Asistentes de IA (MCP)

El mismo token sirve para conectar un asistente de IA (Claude, Cursor, VS Code y otros compatibles con MCP) y pedirle cosas sobre el laboratorio en lenguaje natural:

• «¿Dónde están las alícuotas de plasma del donante PAC-0012?»
• «¿Cuántos lugares libres quedan en la caja de ácidos nucleicos?»
• «¿Quién movió la muestra PL-2026-00042 y cuándo?»
• «Listame las muestras de suero extraídas en marzo que siguen disponibles.»
• «¿Qué calibraciones vencen este mes y quién se ocupa de cada una?»
• «¿Está libre la centrífuga refrigerada mañana a las 10?»
• «¿Qué reactivos vencen este mes y en qué heladera están?»
• «¿Qué hay que pedir esta semana y a qué proveedor?»
• «¿Cómo están las temperaturas de los freezers? ¿Hubo alarmas esta semana?»

Con un token de Editor/a, también le podés pedir que cargue o modifique:

• «Cargá estas 12 muestras de plasma del donante PAC-0031 en la caja 4.»
• «Registrá la calibración de la balanza EQ-0007 de hoy: conforme, válida por un año.»
• «Usé 2 frascos de etanol 96 %: descontalos del lote que vence primero.»
• «Pedí 10 cajas de puntas de 200 µL al proveedor de siempre.»
• «Registrá la alarma de la heladera EQ-0003: quedó la puerta abierta, la cerramos y volvió a rango en 20 minutos.»

Antes de cada cambio, el asistente te dice qué va a hacer y tu programa (Claude, Cursor…) te pide confirmación. Lo que haga queda en el historial a tu nombre, «vía MCP». No puede borrar nada. Con un token de Lector/a, el asistente solo consulta: ni siquiera ve las herramientas para cargar.

El asistente ve solo este laboratorio, con el permiso del token, y solo los módulos habilitados.

La dirección del servidor MCP es la de Vialo seguida de /api/mcp, por ejemplo https://vialo.ejemplo.org/api/mcp.

Con qué Claude se puede usar

En Claude Desktop, Configuración → Conectores → Agregar conector personalizado tampoco sirve por ahora, por lo mismo: no deja mandar el token. Usá el archivo de configuración. Si tu laboratorio necesita los conectores web, pedíselo a la administración de Vialo.

Antes de empezar

1. La API tiene que estar encendida en el laboratorio (ver Encender la API).
2. Creá un token solo para Claude, con un nombre que diga dónde lo usás, por ejemplo «Claude Desktop · notebook». Si cambiás de computadora o la perdés, revocás solo ese. Elegí Lector/a si solo vas a consultar y Editor/a si querés que también cargue datos.
3. Tené a mano la dirección de Vialo de tu laboratorio: la que ves en el navegador al entrar, hasta el dominio (https://vialo.ejemplo.org). La del servidor MCP es esa misma seguida de /api/mcp.

Claude Desktop, paso a paso

1. Instalá Node.js. Claude Desktop se conecta a Vialo a través de un programa chico (mcp-remote) que necesita Node.js. Bajá la versión LTS e instalala con las opciones que trae. Para comprobarlo, abrí una terminal (en Windows, PowerShell o «Símbolo del sistema»; en Mac, Terminal) y escribí node -v: tiene que mostrar un número de versión.

2. Abrí la configuración. En Claude Desktop, andá a Configuración → Desarrollador y tocá Editar configuración. Se abre la carpeta del archivo claude_desktop_config.json; abrilo con un editor de texto (el Bloc de notas sirve). El archivo está en:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Pegá la configuración. Si el archivo está vacío o solo tiene {}, reemplazalo por esto, con la dirección de tu laboratorio y tu token:

   {
     "mcpServers": {
       "vialo": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://vialo.ejemplo.org/api/mcp",
           "--header",
           "Authorization:${VIALO_TOKEN}"
         ],
         "env": { "VIALO_TOKEN": "Bearer trz_tu_token" }
       }
     }
   }
   

   Si el archivo ya tiene otras cosas, no las borres: agregá el bloque "vialo": { … } dentro de mcpServers (separado de los demás servidores con una coma), o creá mcpServers si no está.

   Dejá Authorization:${VIALO_TOKEN} tal cual, sin espacios. El token va solo en env, después de Bearer y un espacio. Así se evita un problema de Windows con los espacios en los argumentos.

4. Guardá y cerrá Claude del todo. Cerrar la ventana no alcanza. En Windows, hacé clic derecho en el ícono de Claude junto al reloj y elegí Salir; en Mac, Claude → Salir (⌘Q). Después volvé a abrirlo.

5. Comprobá que conectó. En Configuración → Desarrollador tiene que aparecer vialo como running. En una conversación nueva, abrí el menú de herramientas del cuadro de texto: tiene que estar vialo, con sus herramientas.

La primera vez que Claude usa cada herramienta, te pide permiso: Permitir una vez o Permitir siempre. Para las que consultan podés elegir siempre; para las que cargan o modifican, conviene una vez, así ves cada cambio antes de que se haga.

Claude Code

En una terminal:

claude mcp add --transport http --scope user vialo https://vialo.ejemplo.org/api/mcp --header "Authorization: Bearer trz_tu_token"

Con --scope user queda disponible en todas tus carpetas; sin eso, solo en la carpeta donde corriste el comando. La pestaña Code de la app de escritorio usa esta misma configuración.

Para ver si conectó, corré claude mcp list (tiene que decir que vialo está conectado) o escribí /mcp dentro de Claude Code. Para sacarlo, claude mcp remove vialo.

Para dejar la configuración en un proyecto que comparte un equipo, sin escribir el token en el archivo, usá un .mcp.json en la carpeta del proyecto. Cada persona define la variable de entorno VIALO_TOKEN con su propio token:

{
  "mcpServers": {
    "vialo": {
      "type": "http",
      "url": "https://vialo.ejemplo.org/api/mcp",
      "headers": { "Authorization": "Bearer ${VIALO_TOKEN}" }
    }
  }
}

Probar la conexión

Empezá con una pregunta que no toca datos:

• «¿A qué laboratorio de Vialo estás conectado y qué podés hacer?»

Claude usa laboratorio_ver y responde con el nombre del laboratorio, los módulos habilitados y si el acceso es solo de consulta o también de carga. Después probá con algo real, como «¿Qué calibraciones vencen este mes?».

Cómo sacarle provecho

• Pedí como se lo pedirías a alguien del laboratorio. Claude busca, cruza y resume: «Armame una tabla con los equipos que tienen una falla abierta, desde cuándo y quién la reportó».
• Usá los códigos. Si nombrás PL-2026-00042 o EQ-0004, va directo a ese registro.
• Leé antes de confirmar. Antes de cargar algo, Claude te dice qué va a hacer. Si falta un dato obligatorio, te lo pregunta en vez de inventarlo.
• Acotá lo que pedís. «Revisá todas las muestras» gasta muchas consultas; «las de plasma de 2026 que siguen disponibles» llega antes y con menos pedidos.
• Usá un proyecto. En Claude Desktop podés armar un Proyecto para el laboratorio y dejar en sus instrucciones lo que Claude tiene que saber siempre, por ejemplo «Si no te digo otra cosa, las muestras nuevas van a la caja 4 del freezer de −80 °C».
• Varios laboratorios. Cada token es de un solo laboratorio. Si trabajás en más de uno, creá un token en cada uno y agregá un servidor por laboratorio, con nombres distintos (vialo-biobanco, vialo-genetica).
• Cuando el token vence, Claude deja de conectarse. Creá uno nuevo, reemplazalo en la configuración y reiniciá Claude.

El token queda guardado en un archivo de tu computadora. No lo configures en una computadora compartida y, si dejás de usarla, revocalo desde Acceso por API.

Si algo no anda

Cursor

En .cursor/mcp.json (del proyecto) o en la configuración de MCP de Cursor:

{
  "mcpServers": {
    "vialo": {
      "url": "https://vialo.ejemplo.org/api/mcp",
      "headers": { "Authorization": "Bearer trz_tu_token" }
    }
  }
}

VS Code

En .vscode/mcp.json:

{
  "servers": {
    "vialo": {
      "type": "http",
      "url": "https://vialo.ejemplo.org/api/mcp",
      "headers": { "Authorization": "Bearer trz_tu_token" }
    }
  }
}

ChatGPT todavía no se puede conectar: pide OAuth, igual que los conectores web de Claude.

Qué puede hacer el asistente

Para consultar:

Para cargar y modificar (solo con un token de Editor/a):

El asistente solo ve las herramientas de los módulos habilitados en el laboratorio.

Cada consulta del asistente cuenta para el límite de 60 pedidos por minuto del token, y cada carga o cambio, para el de 20.

Lo que le preguntás al asistente y lo que Vialo le responde pasa por el servicio de IA que uses (Anthropic, OpenAI, etc.). Antes de conectarlo, confirmá que tu institución permite compartir esos datos con ese servicio. Los códigos de donante están pseudonimizados, pero el resto de los datos de las muestras sí se envía.