Guía de integración de OmniMed Consulta

OmniMed Consulta procesa la grabación completa de una consulta médica (médico, paciente y acompañantes) y devuelve, en un único JSON:

• la nota de la consulta en el formato elegido (SOAP por defecto), donde cada oración cita el momento de la conversación del que sale;
• los pedidos que hizo el médico (laboratorio, imágenes, otros estudios, derivaciones, terapias, procedimientos), cada uno con un borrador de orden listo para completar en tu plataforma;
• las sugerencias para el médico (diagnósticos para considerar con razones a favor y en contra, controles de seguridad de los pedidos, chequeos de guías clínicas), que nunca cambian la nota por sí solas;
• los códigos CIE-10 propuestos para la evaluación;
• la transcripción con el rol de cada hablante y sus tiempos.

Si enviás la historia clínica del paciente, el resultado la usa como contexto: trae los antecedentes relevantes citados y marca las discrepancias entre lo dicho hoy y lo registrado (por ejemplo, "no toma medicación" frente a un tratamiento activo). La nota sale solo de lo dicho en la consulta de hoy: la historia nunca entra en sus secciones como si se hubiera dicho.

Las decisiones del médico (aceptar una sugerencia, editar la nota, firmar las órdenes) ocurren en tu sistema, no en el nuestro.

El contrato completo está en OpenAPI 3.1.

Inicio rápido

URL base: https://api.omniai.com.ar

1. Pedí tu Partner Credential (credencial de partner) a santiago@omniai.com.ar, habilitada para Consulta en tus centros. Es un secreto omp_...: guardalo como variable de entorno de tu servidor. Si ya integrás el dictado de radiología, la misma credencial sirve cuando el centro tiene Consulta habilitada.

2. Enviá la consulta. Desde tu servidor, con la grabación y el consentimiento del paciente:

   curl -X POST https://api.omniai.com.ar/api/consulta/v1/consultations \
     -H "Authorization: Bearer $OMNI_PARTNER_CREDENTIAL" \
     -H "Idempotency-Key: 6f1c2a4e-0b9d-4d61-a3f2-7c5e8b1d9a20" \
     -F "audio=@consulta.m4a" \
     -F "medical_center_id=YOUR_CENTER_ID" \
     -F "doctor_id=med-1042" \
     -F "consent=true"

   Responde 202 enseguida, con el id de la consulta y status: "processing".

3. Consultá el resultado hasta que status sea done (o failed):

   curl https://api.omniai.com.ar/api/consulta/v1/consultations/3f6c1d2e-8a4b-4c7e-9f10-2b5d6e7a8c90 \
     -H "Authorization: Bearer $OMNI_PARTNER_CREDENTIAL"

4. Mostrá el resultado en tu sistema: la nota en note, los pedidos en orders, las sugerencias en suggestions (ver El resultado, campo por campo).

El procesamiento es asíncrono porque una consulta larga tarda más de lo que una conexión HTTP espera.

Autenticación

Partner Credential (servidor a servidor)

Cada llamada lleva la Partner Credential como Bearer:

Authorization: Bearer omp_...

• Es un secreto de servidor a servidor: nunca debe llegar al navegador ni a una app instalada. Guardala en una variable de entorno o en un gestor de secretos.
• Está habilitada para una lista de centros y, en cada centro, para los productos contratados. Una credencial de Dictado no sirve para Consulta salvo que el centro tenga Consulta habilitada para esa credencial.
• Cada llamada que crea una consulta nombra el centro con medical_center_id (su id o su slug en Omnimed AI).
• Esta API no tiene un token para el navegador: todas las llamadas salen de tu servidor.

Rotación

Si la credencial se filtra, pedinos rotarla a santiago@omniai.com.ar: la credencial vieja deja de funcionar en menos de 60 segundos. Una credencial rotada o revocada responde 401 con partner_credential_revoked.

Médico declarado

Tu sistema ya autenticó al médico; en cada consulta nos decís quién es. No creamos usuarios ni le pedimos al médico que inicie sesión con nosotros: confiamos en tu palabra dentro de los centros para los que tu credencial está habilitada.

Los cuatro vuelven en la consulta como doctor (id, name, license, specialty). Un campo que supera su largo máximo responde 422 con invalid_doctor.

Decidí el médico en tu backend a partir de tu propia sesión, nunca a partir de algo que mande el navegador: así un médico no puede actuar a nombre de otro.

Datos del paciente

No hace falta identificar al paciente. Podés enviar en el campo patient (JSON) datos opcionales que mejoran el resultado y una referencia opaca tuya para correlacionar:

{"ref": "hc-998877", "birth_date": "1988-04-12", "sex": "female", "coverage": {"name": "Obra social ejemplo", "plan": "210"}}

• Sin identidad. No mandes nombre ni documento: los datos de identidad del paciente los completa tu sistema sobre el borrador de orden.
• Tolerante. Los campos que no conocemos se ignoran, y también un campo conocido cuyo valor no respeta el formato (por ejemplo sex: "F", age: 200 o una fecha mal escrita): se descarta ese campo y se usa el resto. Guardamos solo los campos de esta lista.
• Hasta 1 MB. Un patient que no es JSON, no es un objeto o supera 1 MB responde 422 con invalid_patient.

Historia clínica

Opcional, en el campo history (JSON), organizada por secciones. Todas las secciones son opcionales. Cada registro lleva tu propio id: las citas del resultado (source_ids) usan esos mismos ids, así podés enlazar cada antecedente o discrepancia al registro de tu sistema.

Las fechas van como AAAA-MM-DD.

{
  "problems": [{"id": "pb-3", "text": "Hipertensión arterial", "code": "CIE-10 I10", "onset": "2019-05-01"}],
  "allergies": [{"id": "alg-17", "substance": "Penicilina", "reaction": "Urticaria"}],
  "medications": [{"id": "med-8", "name": "Enalapril", "dose": "10 mg cada 12 h", "since": "2019-05-01"}],
  "labs": [{"id": "lab-51", "name": "Glucemia", "value": "98", "unit": "mg/dL", "ref_range": "70-110", "date": "2026-08-20"}],
  "imaging_reports": [
    {"id": "img-4", "study": "Ecografía abdominal", "date": "2025-03-10", "text": "Hígado de forma y tamaño conservados...", "conclusion": "Sin hallazgos patológicos."}
  ],
  "visits": [{"id": "vis-22", "date": "2026-08-20", "reason": "Control de presión", "summary": "Buen control con enalapril."}]
}

• La historia que enviás se usa solo para esa consulta: nunca se mezcla con otra consulta ni con otro paciente.
• Hasta 1 MB de JSON. Los textos de más de 8.000 caracteres se recortan.
• Responde 422 con invalid_history si no es JSON, supera 1 MB o un registro no respeta su formato: campos requeridos, fechas, valores permitidos o ids repetidos dentro de una sección.

Consentimiento

Grabar una consulta requiere el consentimiento del paciente. Al enviar consent=true tu sistema declara que el paciente aceptó ser grabado. Sin eso la consulta se rechaza con 422 y consent_required.

Endpoints

Todas las llamadas llevan Authorization: Bearer omp_... y salen de tu servidor.

Enviar una consulta

POST https://api.omniai.com.ar/api/consulta/v1/consultations
Authorization: Bearer omp_...
Idempotency-Key: <UUID de este envío>
Content-Type: multipart/form-data

Recibe la grabación completa y responde de inmediato con el id; el procesamiento sigue en segundo plano.

Parámetros

audio y dictation aceptan m4a, mp3, wav, webm y ogg, hasta 100 MB cada uno. Mandá patient e history como partes JSON del formulario (type=application/json en curl).

Respuesta 202: consulta aceptada

{
  "id": "3f6c1d2e-8a4b-4c7e-9f10-2b5d6e7a8c90",
  "status": "processing",
  "stage": "transcribing",
  "medical_center_id": "9b2f4c1a-6d3e-4f5a-8b7c-1d2e3f4a5b6c",
  "doctor": {"id": "med-1042", "name": "Dra. Ana Pérez", "license": "MP 12345", "specialty": "Clínica médica"},
  "patient_ref": "hc-998877",
  "note_format": "soap",
  "created_at": "2026-11-03T13:05:12Z",
  "completed_at": null
}

• Guardá el id: es lo que vas a consultar.
• medical_center_id viene siempre como id del centro, aunque lo hayas enviado por su slug.
• Un reenvío con una Idempotency-Key ya usada responde 200 con la consulta existente, con la misma forma; si esa consulta había fallado o estaba trabada, se reprocesa y responde 202 con el mismo id (ver Idempotencia).

Ejemplo completo

Con dictado posterior, datos del médico, datos del paciente e historia clínica:

curl -X POST https://api.omniai.com.ar/api/consulta/v1/consultations \
  -H "Authorization: Bearer $OMNI_PARTNER_CREDENTIAL" \
  -H "Idempotency-Key: 6f1c2a4e-0b9d-4d61-a3f2-7c5e8b1d9a20" \
  -F "audio=@consulta.m4a" \
  -F "dictation=@dictado-posterior.m4a" \
  -F "medical_center_id=YOUR_CENTER_ID" \
  -F "doctor_id=med-1042" \
  -F "doctor_name=Dra. Ana Pérez" \
  -F "doctor_license=MP 12345" \
  -F "doctor_specialty=Clínica médica" \
  -F "consent=true" \
  -F "note_format=soap" \
  -F 'patient={"ref": "hc-998877", "age": 38, "sex": "female"};type=application/json' \
  -F "history=@historia.json;type=application/json"

En Python:

import json
import os
import uuid

import requests

API = "https://api.omniai.com.ar"
headers = {
    "Authorization": f"Bearer {os.environ['OMNI_PARTNER_CREDENTIAL']}",
    "Idempotency-Key": str(uuid.uuid4()),  # guardala para reintentar con la misma
}

with open("consulta.m4a", "rb") as audio:
    response = requests.post(
        f"{API}/api/consulta/v1/consultations",
        headers=headers,
        files={
            "audio": ("consulta.m4a", audio, "audio/mp4"),
            "patient": (None, json.dumps({"ref": "hc-998877", "age": 38}), "application/json"),
        },
        data={
            "medical_center_id": "YOUR_CENTER_ID",
            "doctor_id": "med-1042",
            "consent": "true",
        },
        timeout=120,
    )

response.raise_for_status()
consultation_id = response.json()["id"]

Obtener el estado y el resultado

GET https://api.omniai.com.ar/api/consulta/v1/consultations/{consultation_id}
Authorization: Bearer omp_...

consultation_id es el id que devolvió el envío.

Estados

Mientras status es processing, stage va pasando por transcribing, identifying_speakers y writing_note; al terminar vale done o failed. La lista de pasos puede crecer: tratá un valor que no conozcas como "procesando".

Con failed, error trae uno de estos códigos:

Un código que no conozcas trae el mensaje "No se pudo procesar la consulta.". Compará por error.code; error.message es para mostrarle al médico y puede cambiar.

{
  "id": "3f6c1d2e-8a4b-4c7e-9f10-2b5d6e7a8c90",
  "status": "failed",
  "stage": "failed",
  "error": {"code": "audio_empty", "message": "La grabación no tiene voz. Revisá que el micrófono no haya estado silenciado."},
  "...": "..."
}

En los tres casos podés reenviar con la misma Idempotency-Key: la consulta se procesa de nuevo con el audio de ese envío y responde 202 con el mismo id.

Cada cuánto consultar

Recomendamos consultar cada 5 segundos durante el primer minuto y después cada 15 segundos. El tiempo de procesamiento depende de la duración del audio; no hay un tiempo garantizado.

import time

def wait_for(consultation_id: str) -> dict:
    started = time.monotonic()
    while True:
        response = requests.get(
            f"{API}/api/consulta/v1/consultations/{consultation_id}",
            headers={"Authorization": f"Bearer {os.environ['OMNI_PARTNER_CREDENTIAL']}"},
            timeout=30,
        )
        response.raise_for_status()
        consultation = response.json()
        if consultation["status"] != "processing":
            return consultation  # "done" o "failed"
        time.sleep(5 if time.monotonic() - started < 60 else 15)

Respuesta 200 con status: "done"

{
  "id": "3f6c1d2e-8a4b-4c7e-9f10-2b5d6e7a8c90",
  "status": "done",
  "stage": "done",
  "error": null,
  "medical_center_id": "9b2f4c1a-6d3e-4f5a-8b7c-1d2e3f4a5b6c",
  "doctor": {"id": "med-1042", "name": "Dra. Ana Pérez", "license": "MP 12345", "specialty": "Clínica médica"},
  "patient_ref": "hc-998877",
  "note_format": "soap",
  "created_at": "2026-11-03T13:05:12Z",
  "completed_at": "2026-11-03T13:06:40Z",
  "audio_seconds": 312.4,
  "note": {
    "format": "soap",
    "sections": [
      {
        "key": "subjective",
        "title": "Subjetivo",
        "sentences": [
          {"text": "Dolor abdominal de 2 días de evolución, con diarrea, sin vómitos.", "turn_ids": ["t2", "t4"]},
          {"text": "Refiere cefalea leve.", "turn_ids": ["t4"]}
        ]
      },
      {
        "key": "objective",
        "title": "Objetivo",
        "sentences": [{"text": "Dolor que se irradia a fosa ilíaca derecha.", "turn_ids": ["t8"]}]
      },
      {
        "key": "assessment",
        "title": "Evaluación",
        "sentences": [{"text": "Se sospecha cuadro quirúrgico a descartar.", "turn_ids": ["t9"]}]
      },
      {
        "key": "plan",
        "title": "Plan",
        "sentences": [
          {"text": "Laboratorio con enzimas y ecografía abdominal; control con resultados.", "turn_ids": ["t9"]},
          {"text": "Pautas de alarma: fiebre alta, dolor abdominal intenso o abdomen duro.", "turn_ids": ["t11"]}
        ]
      }
    ],
    "history_context": [{"text": "Alergia a penicilina registrada.", "source_ids": ["alg-17"]}],
    "discrepancies": []
  },
  "orders": [
    {
      "id": "o1",
      "kind": "lab",
      "name": "Laboratorio",
      "said_as": "te vamos a sacar sangre, quiero ver si tenés elevadas algunas enzimas",
      "details": "Enzimas",
      "indication": "Descartar cuadro quirúrgico",
      "status": "firm",
      "needs_detail": true,
      "detail_question": "¿Qué determinaciones?",
      "detail_options": ["Hemograma", "Hepatograma", "Amilasa", "Lipasa"],
      "turn_ids": ["t9"],
      "missing": ["detail"],
      "draft": {
        "study": "Laboratorio, Enzimas",
        "presumptive_diagnosis": "Dolor abdominal, se sospecha cuadro quirúrgico",
        "clinical_data": "Dolor abdominal de 2 días con irradiación a fosa ilíaca derecha.",
        "cie10_codes": ["R10.3"]
      }
    },
    {
      "id": "o2",
      "kind": "imaging",
      "name": "Ecografía abdominal",
      "said_as": "vamos a hacer un eco rápido como para descartar que no sea el apéndice",
      "details": "",
      "indication": "Descartar apendicitis",
      "status": "firm",
      "needs_detail": false,
      "detail_question": "",
      "detail_options": [],
      "turn_ids": ["t9"],
      "missing": [],
      "draft": {
        "study": "Ecografía abdominal",
        "presumptive_diagnosis": "Dolor abdominal, se sospecha cuadro quirúrgico",
        "clinical_data": "Dolor abdominal de 2 días con irradiación a fosa ilíaca derecha.",
        "cie10_codes": ["R10.3"]
      }
    }
  ],
  "suggestions": [
    {
      "id": "s1",
      "kind": "diagnosis_to_consider",
      "severity": "info",
      "title": "Gastroenteritis aguda",
      "body": "",
      "question": "",
      "order_id": null,
      "proposed_actions": [
        {"key": "add_to_assessment", "label": "Agregar a la evaluación"},
        {"key": "dismiss", "label": "Descartar"}
      ],
      "reasons_for": [{"text": "Diarrea de 2 días", "turn_ids": ["t4"]}],
      "reasons_against": [{"text": "Dolor que se irradia a fosa ilíaca derecha", "turn_ids": ["t8"]}],
      "sources": {"turn_ids": ["t4", "t8"], "source_ids": [], "guideline": null},
      "ai_generated": true
    }
  ],
  "diagnosis_codes": [{"code": "R10.3", "description": "Dolor localizado en otras partes inferiores del abdomen"}],
  "transcript": {
    "turns": [
      {"id": "t1", "speaker_id": "speaker_0", "role": "doctor", "segment": "conversation", "text": "Hola, ¿cómo andás?", "start": 0.4, "end": 1.6},
      {"id": "t2", "speaker_id": "speaker_1", "role": "patient", "segment": "conversation", "text": "Vengo porque tengo dolor de panza hace dos días.", "start": 1.8, "end": 5.2}
    ]
  },
  "patient_instructions": null
}

La transcripción del ejemplo está recortada a sus dos primeros turnos. Cada campo se explica en El resultado, campo por campo.

Generar indicaciones para el paciente

POST https://api.omniai.com.ar/api/consulta/v1/consultations/{consultation_id}/instructions
Authorization: Bearer omp_...

Sin cuerpo. Reescribe el Plan de la nota en lenguaje simple para que el paciente se lo lleve (por ejemplo, por WhatsApp o impreso). No agrega nada que no esté en la nota.

• Solo con una consulta en done; antes responde 409 con consultation_not_done.
• Si la nota no tiene Plan del que partir, responde 422 con plan_empty.
• Llamarlo de nuevo genera una versión nueva, que reemplaza a la anterior en patient_instructions de la consulta.
• No cuenta como consulta.

Respuesta 200

{
  "patient_instructions": "Vas a hacerte un análisis de sangre y una ecografía de abdomen. Cuando tengas los resultados, volvé a la consulta.\nConsultá a la guardia si tenés fiebre alta, dolor fuerte en la panza o si la panza se pone dura de golpe.\n"
}

patient_instructions es texto plano, en segunda persona, para el paciente.

Ejemplo

curl -X POST https://api.omniai.com.ar/api/consulta/v1/consultations/3f6c1d2e-8a4b-4c7e-9f10-2b5d6e7a8c90/instructions \
  -H "Authorization: Bearer $OMNI_PARTNER_CREDENTIAL"

Listar los formatos de nota

GET https://api.omniai.com.ar/api/consulta/v1/note-formats
Authorization: Bearer omp_...

Los formatos en los que se puede escribir la nota, con sus secciones en orden. El id de cada formato es el valor de note_format al enviar la consulta, y las key de sus secciones son las de note.sections en el resultado.

Respuesta 200

{
  "formats": [
    {
      "id": "soap",
      "name": "SOAP",
      "sections": [
        {"key": "subjective", "title": "Subjetivo"},
        {"key": "objective", "title": "Objetivo"},
        {"key": "assessment", "title": "Evaluación"},
        {"key": "plan", "title": "Plan"}
      ]
    },
    {
      "id": "pediatric_checkup",
      "name": "Control pediátrico",
      "sections": [
        {"key": "reason", "title": "Motivo de consulta"},
        {"key": "growth", "title": "Crecimiento y desarrollo"},
        {"key": "feeding", "title": "Alimentación y hábitos"},
        {"key": "vaccines", "title": "Vacunas"},
        {"key": "exam", "title": "Examen físico"},
        {"key": "plan", "title": "Indicaciones"}
      ]
    }
  ]
}

Idempotencia

Una red que se corta a mitad de un envío de 15 MB deja la duda de si la consulta llegó. Con Idempotency-Key podés reenviar sin crear otra consulta ni pagarla dos veces.

• Generá un identificador único por consulta (recomendado un UUID, hasta 255 caracteres) y guardalo junto a la consulta en tu sistema antes de enviar.
• Reenvío con la misma key:
  • si la primera sigue en proceso o terminó, responde 200 con esa misma consulta;
  • si falló, o lleva más de 10 minutos sin avanzar, se procesa de nuevo con el audio de este envío y responde 202 con el mismo id: seguí consultando ese id.
• Fallida o trabada: para reintentar una consulta en failed (o una que no avanza), reenviala con la misma key.
• Keys por credencial: cada credencial tiene sus propias keys. Una key que ya se usó para otro centro responde 409 con idempotency_key_conflict.
• Sin key, cada envío crea una consulta nueva.
• Una key de más de 255 caracteres responde 422 con invalid_idempotency_key.

El resultado, campo por campo

Consulta

Parseá la respuesta de forma tolerante: pueden sumarse campos nuevos.

Nota (note)

history_context y discrepancies van aparte de sections: la historia nunca entra en la nota como si se hubiera dicho hoy.

Pedidos (orders)

Un pedido es algo que indicó el médico, citado a sus propias palabras. Lo que pide el paciente sin que el médico lo indique no es un pedido.

Borrador de orden (draft)

Lo que una plataforma de órdenes necesita, armado a partir del pedido y la nota. Nunca es una orden válida por sí misma: el médico la completa y la firma en tu sistema, y los datos del paciente (nombre, documento, cobertura) los agrega tu sistema.

Sugerencias (suggestions)

Una sugerencia es una propuesta para el médico sobre la consulta de hoy. No cambia nada por sí sola: el médico decide en tu sistema. Cada una explica por qué y cita sus fuentes.

La lista de tipos puede crecer: ignorá los que no conozcas.

Códigos CIE-10 (diagnosis_codes)

Hasta 4 códigos CIE-10 propuestos para la evaluación, cada uno con code (normalizado, ej. "K52.9") y description.

Transcripción (transcript)

transcript.turns es la conversación, turno por turno:

Cómo seguir una cita

• turn_ids apunta a transcript.turns[].id: con su role sabés quién lo dijo y con start y end, en qué momento.
• source_ids apunta a los id que vos pusiste en history: enlazá el antecedente o la discrepancia a tu propio registro.
• order_id apunta a orders[].id.

Errores

Todo error responde con un status no-2xx y este cuerpo:

{
  "detail": {
    "code": "consent_required",
    "message": "Falta el consentimiento del paciente (consent=true)."
  }
}

detail.code es estable y es lo que tu código debe comparar; detail.message es para personas y puede cambiar.

Credencial y disponibilidad (todos los endpoints)

Los 401 traen además el header WWW-Authenticate.

POST /api/consulta/v1/consultations

Los 403 son configuración de nuestro lado: escribinos. Los 400, 409, 413 y 422 no se reintentan sin corregir la llamada.

GET /api/consulta/v1/consultations/{consultation_id}

Una consulta que falló no es un error HTTP: responde 200 con status: "failed" y el motivo en error (ver Estados).

POST /api/consulta/v1/consultations/{consultation_id}/instructions

GET /api/consulta/v1/note-formats

Solo los errores de credencial y disponibilidad.

Límites

• Una consulta de 15 minutos en m4a pesa alrededor de 15 MB.
• El tiempo de procesamiento depende de la duración del audio; no hay un tiempo garantizado. Consultá cada 5 segundos durante el primer minuto y después cada 15.
• Reintentá los 5xx con espera creciente; los 4xx no se reintentan sin corregir la llamada.

Datos y seguridad

• Todo el tráfico va cifrado (TLS).
• Nuestros servidores y bases de datos están alojados en la Unión Europea.
• El audio se procesa y no se conserva salvo que el contrato del centro lo pida.
• Qué más se conserva (transcripción, nota, resultado) y por cuánto tiempo se define en el contrato con cada centro.
• La lista de subprocesadores y sus condiciones se entrega bajo acuerdo de confidencialidad.

Facturación

Cada consulta procesada con éxito cuenta como una consulta. No cuentan:

• reenviar con la misma Idempotency-Key;
• una consulta que falla por un problema de nuestro lado;
• generar indicaciones para el paciente.

Changelog

v1 (2026-10-30)

• Primera versión: POST /api/consulta/v1/consultations, GET /api/consulta/v1/consultations/{consultation_id}, POST .../instructions y GET /api/consulta/v1/note-formats.
• Partner Credential (omp_...) habilitada por centro y producto, con el médico declarado en cada consulta.
• Historia clínica opcional con citas a tus propios ids (source_ids) y discrepancias.
• Idempotencia con Idempotency-Key.

Soporte

Consultas, Partner Credentials y alta de centros: santiago@omniai.com.ar

• Contrato: OpenAPI 3.1 de Consulta
• Documentación de la API de radiología: /api-documentation/radiologia