API de Flujo de Documentación Clínica

La API de Flujo de Documentación Clínica proporciona una solución integral para gestionar transcripciones de conversaciones médico-paciente, extracción de notas clínicas con IA y documentación clínica estructurada.

Resumen del Flujo de Trabajo

El flujo de documentación clínica consta de tres etapas principales:

Crear Transcripción - Almacenar transcripción de audio a texto de conversaciones médico-paciente
Crear Hilo y Ejecutar Runs - Procesar transcripciones con IA para extraer información clínica
Actualizar Notas Clínicas - Almacenar y gestionar documentación clínica generada por IA

1. Crear Transcripción

Endpoint

POST https://{your_api_url}/v1/transcriptions/create

Propósito

Crea un nuevo registro de transcripción para la conversión de audio a texto de conversaciones médico-paciente. Este es el primer paso en el flujo de documentación clínica: almacena la transcripción sin procesar antes del procesamiento de IA.

Encabezados requeridos

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123

Encabezados opcionales

x-patient: pt_456

Cuerpo de la solicitud

{
  "duration_seconds": 180,
  "original_transcript": "El paciente es un hombre de 45 años que presenta dolor torácico que se irradia al brazo izquierdo durante las últimas 2 horas. El dolor comenzó al subir escaleras. Sin antecedentes cardíacos previos. Signos vitales: PA 140/90, FC 88, FR 18, saturación O2 98% en aire ambiente.",
  "language_used": "es"
}

Campos de la solicitud

Campo	Tipo	Requerido	Descripción
`duration_seconds`	número	Sí	Duración de la grabación en segundos (mín: 0)
`original_transcript`	string	Sí	El texto transcrito de la conversación
`language_used`	string	No	Código de idioma (ej., ‘en’, ‘es’, ‘fr’)

Respuesta exitosa (HTTP 201)

{
  "message": "Transcription created successfully",
  "transcription": {
    "id": "trans_abc123xyz",
    "user_id": "usr_123456789",
    "group_id": "grp_987654321",
    "duration_seconds": 180,
    "language_used": "es",
    "original_transcript": "El paciente es un hombre de 45 años...",
    "created_at": "2023-10-09T10:00:00.000Z",
    "updated_at": "2023-10-09T10:00:00.000Z"
  }
}

Ejemplo - Python

import requests

url = "https://{your_api_url}/v1/transcriptions/create"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "x-doctor": "dr_123",  # REQUIRED
    "x-patient": "pt_456"  # OPTIONAL
}

payload = {
    "duration_seconds": 180,
    "original_transcript": "El paciente es un hombre de 45 años que presenta dolor torácico...",
    "language_used": "es"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"Transcripción creada: {result['transcription']['id']}")

Ejemplo - JavaScript

const axios = require('axios');

const url = 'https://{your_api_url}/v1/transcriptions/create';
const headers = {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json',
  'x-doctor': 'dr_123',   // REQUIRED
  'x-patient': 'pt_456'   // OPTIONAL
};

const payload = {
  duration_seconds: 180,
  original_transcript: 'El paciente es un hombre de 45 años que presenta dolor torácico...',
  language_used: 'es'
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log('Transcripción creada:', response.data.transcription.id);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

2. Crear Hilo de Conversación

Endpoint

POST https://{your_api_url}/v1/lang-graph/threads

Propósito

Crea un nuevo hilo de conversación para interacciones con IA (chat o extracción clínica). Inicializa una sesión de conversación con estado con el asistente de IA. El hilo mantiene el contexto a través de múltiples interacciones y es requerido antes de ejecutar cualquier run de conversación.

Encabezados requeridos

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123

Encabezados opcionales

x-patient: pt_456

Cuerpo de la solicitud

No se requiere cuerpo de solicitud (POST vacío).

{}

Respuesta exitosa (HTTP 201)

{
  "thread_id": "thread-abc123",
  "created_at": "2023-10-09T10:00:00.000Z",
  "status": "active"
}

Ejemplo - Python

import requests

url = "https://{your_api_url}/v1/lang-graph/threads"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "x-doctor": "dr_123",  # REQUIRED
    "x-patient": "pt_456"  # OPTIONAL
}

response = requests.post(url, json={}, headers=headers)
result = response.json()

print(f"Hilo creado: {result['thread_id']}")

Ejemplo - JavaScript

const axios = require('axios');

const url = 'https://{your_api_url}/v1/lang-graph/threads';
const headers = {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json',
  'x-doctor': 'dr_123',   // REQUIRED
  'x-patient': 'pt_456'   // OPTIONAL
};

axios.post(url, {}, { headers })
  .then(response => {
    console.log('Hilo creado:', response.data.thread_id);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

3. Ejecutar Run de Conversación

Endpoint

POST https://{your_api_url}/v1/lang-graph/threads/{threadId}/runs

Propósito

Ejecuta un run de conversación dentro de un hilo existente para procesar interacciones con IA. Este es el endpoint central de procesamiento de IA: envía mensajes al asistente de IA e inicia el procesamiento. Se utiliza tanto para interacciones de chat en tiempo real como para extracción de notas clínicas de transcripciones. El run se ejecuta de forma asíncrona y puede ser monitoreado a través del endpoint join.

Encabezados requeridos

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123

Encabezados opcionales

x-is-chat: true      (Bandera booleana: true = chat/escriba, false = extracción)
x-patient: pt_456    (Identificador del paciente para seguimiento y auditoría)

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`threadId`	string	Sí	El identificador del hilo en el que ejecutar el run

Cuerpo de la solicitud

{
  "input": {
    "messages": [
      {
        "role": "user",
        "content": "Hola, ¿cómo puedes ayudarme hoy?"
      }
    ]
  },
  "config": {
    "configurable": {
      "thread_id": "thread-abc123"
    }
  }
}

Campos de la solicitud

Campo	Tipo	Requerido	Descripción
`input.messages`	array	Sí	Array de mensajes de conversación
`input.messages[].role`	string	Sí	Rol del remitente del mensaje (user, assistant, system)
`input.messages[].content`	string	Sí	Contenido del mensaje
`config.configurable.thread_id`	string	Sí	Identificador del hilo para este run

Respuesta exitosa (HTTP 201)

{
  "run_id": "run-xyz789",
  "thread_id": "thread-abc123",
  "status": "pending",
  "created_at": "2023-10-09T10:00:00.000Z"
}

Ejemplo - Extracción clínica

import requests

base_headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "x-doctor": "dr_123",  # REQUIRED
    "x-patient": "pt_456"  # OPTIONAL
}

# Primero, crear un hilo
thread_url = "https://{your_api_url}/v1/lang-graph/threads"
thread_response = requests.post(thread_url, json={}, headers=base_headers)
thread_id = thread_response.json()['thread_id']

# Ejecutar un run para extracción clínica (x-is-chat: false)
run_url = f"https://{your_api_url}/v1/lang-graph/threads/{thread_id}/runs"
run_headers = {
    **base_headers,
    "x-is-chat": "false"  # false = extracción clínica
}

payload = {
    "input": {
        "messages": [
            {
                "role": "user",
                "content": "Extraer información clínica de: El paciente reporta dolor torácico que se irradia al brazo izquierdo..."
            }
        ]
    },
    "config": {
        "configurable": {
            "thread_id": thread_id
        }
    }
}

response = requests.post(run_url, json=payload, headers=run_headers)
result = response.json()

print(f"Run creado: {result['run_id']}")
print(f"Estado: {result['status']}")

Ejemplo - Interacción de chat

const axios = require('axios');

// Crear hilo primero
const threadUrl = 'https://{your_api_url}/v1/lang-graph/threads';

const baseHeaders = {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json',
  'x-doctor': 'dr_123',   // REQUIRED
  'x-patient': 'pt_456'   // OPTIONAL
};

const threadResponse = await axios.post(threadUrl, {}, { headers: baseHeaders });
const threadId = threadResponse.data.thread_id;

// Ejecutar un run de chat (x-is-chat: true)
const runUrl = `https://{your_api_url}/v1/lang-graph/threads/${threadId}/runs`;
const runHeaders = {
  ...baseHeaders,
  'x-is-chat': 'true'  // true = modo chat/escriba
};

const payload = {
  input: {
    messages: [
      {
        role: 'user',
        content: 'Hola, ¿cómo puedes ayudarme hoy?'
      }
    ]
  },
  config: {
    configurable: {
      thread_id: threadId
    }
  }
};

axios.post(runUrl, payload, { headers: runHeaders })
  .then(response => {
    console.log('Run creado:', response.data.run_id);
    console.log('Estado:', response.data.status);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

4. Actualizar Nota Clínica

Endpoint

PATCH https://{your_api_url}/v1/clinical-notes/{id}

Propósito

Actualiza una nota clínica existente con contenido generado por IA, retroalimentación o metadatos. Se utiliza para almacenar documentación clínica generada por IA, vincular a hilos de conversación y capturar retroalimentación del usuario para mejora de calidad.

Encabezados requeridos

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123

Encabezados opcionales

x-patient: pt_456

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`id`	string (UUID)	Sí	El UUID de la nota clínica

Cuerpo de la solicitud

Todos los campos son opcionales - actualice solo lo necesario:

{
  "template": "SOAP",
  "ai_generated_content": {
    "subjective": "Paciente reporta dolor torácico que se irradia al brazo izquierdo",
    "objective": "PA 140/90, FC 88, FR 18, saturación O2 98% en aire ambiente",
    "assessment": "R/O infarto de miocardio",
    "plan": "Admitir a UCI, troponinas seriadas, consulta de cardiología"
  },
  "feedback": "Nota bien estructurada",
  "report_thread_id": "thread_xyz789",
  "report_run_id": ["run_001", "run_002"]
}

Campos de la solicitud

Campo	Tipo	Requerido	Descripción
`template`	string	No	Formato de nota clínica (SOAP, BIRP, DAP, GIRP)
`ai_generated_content`	object	No	Datos clínicos estructurados (el esquema varía por plantilla)
`feedback`	string	No	Comentarios o retroalimentación del usuario sobre la nota
`report_thread_id`	string	No	ID del hilo que generó este contenido
`report_run_id`	array	No	Array de IDs de run involucrados en generar contenido

Respuesta exitosa (HTTP 200)

{
  "id": "note_def456ghi",
  "user_id": "usr_123456789",
  "group_id": "grp_987654321",
  "transcription_id": "trans_abc123xyz",
  "template": "SOAP",
  "ai_generated_content": {
    "subjective": "Paciente reporta dolor torácico que se irradia al brazo izquierdo",
    "objective": "PA 140/90, FC 88, FR 18, saturación O2 98% en aire ambiente",
    "assessment": "R/O infarto de miocardio",
    "plan": "Admitir a UCI, troponinas seriadas, consulta de cardiología"
  },
  "feedback": "Nota bien estructurada",
  "report_thread_id": "thread_xyz789",
  "report_run_id": ["run_001", "run_002"],
  "created_at": "2023-10-09T10:00:00.000Z",
  "updated_at": "2023-10-09T10:05:00.000Z"
}

Ejemplo - Python

import requests

note_id = "note_def456ghi"
url = f"https://{your_api_url}/v1/clinical-notes/{note_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "x-doctor": "dr_123",  # REQUIRED
    "x-patient": "pt_456"  # OPTIONAL
}

payload = {
    "template": "SOAP",
    "ai_generated_content": {
        "subjective": "Paciente reporta dolor torácico que se irradia al brazo izquierdo",
        "objective": "PA 140/90, FC 88, FR 18, saturación O2 98% en aire ambiente",
        "assessment": "R/O infarto de miocardio",
        "plan": "Admitir a UCI, troponinas seriadas, consulta de cardiología"
    },
    "feedback": "Nota bien estructurada",
    "report_thread_id": "thread_xyz789",
    "report_run_id": ["run_001", "run_002"]
}

response = requests.patch(url, json=payload, headers=headers)
result = response.json()

print(f"Nota clínica actualizada: {result['id']}")
print(f"Plantilla: {result['template']}")

Ejemplo - JavaScript

const axios = require('axios');

const noteId = 'note_def456ghi';
const url = `https://{your_api_url}/v1/clinical-notes/${noteId}`;
const headers = {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json',
  'x-doctor': 'dr_123',   // REQUIRED
  'x-patient': 'pt_456'   // OPTIONAL
};

const payload = {
  template: 'SOAP',
  ai_generated_content: {
    subjective: 'Paciente reporta dolor torácico que se irradia al brazo izquierdo',
    objective: 'PA 140/90, FC 88, FR 18, saturación O2 98% en aire ambiente',
    assessment: 'R/O infarto de miocardio',
    plan: 'Admitir a UCI, troponinas seriadas, consulta de cardiología'
  },
  feedback: 'Nota bien estructurada',
  report_thread_id: 'thread_xyz789',
  report_run_id: ['run_001', 'run_002']
};

axios.patch(url, payload, { headers })
  .then(response => {
    console.log('Nota clínica actualizada:', response.data.id);
    console.log('Plantilla:', response.data.template);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

Ejemplo de Flujo de Trabajo Completo

Aquí hay un ejemplo completo de todo el flujo de documentación clínica:

Python - Flujo de trabajo completo

import requests

BASE_URL = "https://{your_api_url}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "x-doctor": "dr_123",  # REQUIRED
    "x-patient": "pt_456"  # OPTIONAL
}

# Paso 1: Crear transcripción
transcription_data = {
    "duration_seconds": 180,
    "original_transcript": "El paciente es un hombre de 45 años que presenta dolor torácico...",
    "language_used": "es"
}

transcription_response = requests.post(
    f"{BASE_URL}/v1/transcriptions/create",
    json=transcription_data,
    headers=headers
)
transcription = transcription_response.json()
transcription_id = transcription['transcription']['id']
print(f"✅ Paso 1: Transcripción creada: {transcription_id}")

# Paso 2: Crear hilo
thread_response = requests.post(
    f"{BASE_URL}/v1/lang-graph/threads",
    json={},
    headers=headers
)
thread = thread_response.json()
thread_id = thread['thread_id']
print(f"✅ Paso 2: Hilo creado: {thread_id}")

# Paso 3: Ejecutar run para extracción clínica
run_headers = {
    **headers,
    "x-is-chat": "false"  # Modo de extracción clínica
}

run_data = {
    "input": {
        "messages": [
            {
                "role": "user",
                "content": f"Extraer información clínica: {transcription_data['original_transcript']}"
            }
        ]
    },
    "config": {
        "configurable": {
            "thread_id": thread_id
        }
    }
}

run_response = requests.post(
    f"{BASE_URL}/v1/lang-graph/threads/{thread_id}/runs",
    json=run_data,
    headers=run_headers
)
run = run_response.json()
run_id = run['run_id']
print(f"✅ Paso 3: Run ejecutado: {run_id}")

# Paso 4: Actualizar nota clínica (asumiendo que note_id existe)
note_id = "note_def456ghi"  # Esto se crearía en otro lugar
note_data = {
    "template": "SOAP",
    "ai_generated_content": {
        "subjective": "Paciente reporta dolor torácico que se irradia al brazo izquierdo",
        "objective": "PA 140/90, FC 88, FR 18, saturación O2 98% en aire ambiente",
        "assessment": "R/O infarto de miocardio",
        "plan": "Admitir a UCI, troponinas seriadas, consulta de cardiología"
    },
    "report_thread_id": thread_id,
    "report_run_id": [run_id]
}

note_response = requests.patch(
    f"{BASE_URL}/v1/clinical-notes/{note_id}",
    json=note_data,
    headers=headers
)
note = note_response.json()
print(f"✅ Paso 4: Nota clínica actualizada: {note['id']}")
print(f"\n🎉 Flujo de trabajo completo!")

Plantillas Clínicas Compatibles

El campo template en las notas clínicas admite múltiples formatos:

SOAP (Subjetivo, Objetivo, Evaluación, Plan)

{
  "subjective": "Síntomas reportados por el paciente e historial",
  "objective": "Hallazgos del examen físico y signos vitales",
  "assessment": "Diagnóstico clínico o impresión",
  "plan": "Plan de tratamiento y seguimiento"
}

BIRP (Comportamiento, Intervención, Respuesta, Plan)

{
  "behavior": "Comportamientos del paciente observados",
  "intervention": "Acciones tomadas por el proveedor de atención médica",
  "response": "Respuesta del paciente a la intervención",
  "plan": "Plan de tratamiento futuro"
}

DAP (Datos, Evaluación, Plan)

{
  "data": "Datos objetivos y subjetivos recopilados",
  "assessment": "Evaluación clínica y diagnóstico",
  "plan": "Plan de tratamiento y seguimiento"
}

Plantillas Personalizadas

También puede usar plantillas personalizadas basadas en los requisitos de su organización. El campo ai_generated_content acepta cualquier estructura de objeto JSON válida.

Manejo de Errores

Errores comunes

Código	Error	Descripción	Solución
400	Bad Request	Faltan campos requeridos o datos inválidos	Verificar que todos los campos requeridos estén proporcionados
401	Unauthorized	Token inválido o expirado	Verificar su Bearer token
404	Not Found	Hilo o nota clínica no encontrado	Verificar que el ID existe
500	Internal Server Error	Error del servidor	Reintentar con retroceso exponencial

Formato de respuesta de error

{
  "success": false,
  "error": "Bad Request",
  "details": "duration_seconds y original_transcript son requeridos"
}

Próximos pasos

Ver API Codify

API de codificación médica ICD-10

Manejo de errores

Respuestas de error y estrategias de reintento

Autenticación

Autenticación de API y encabezados

Referencia OpenAPI

Especificación completa de la API

​Resumen del Flujo de Trabajo

​1. Crear Transcripción

​Endpoint

​Propósito

​Encabezados requeridos

​Encabezados opcionales

​Cuerpo de la solicitud

​Campos de la solicitud

​Respuesta exitosa (HTTP 201)

​Ejemplo - Python

​Ejemplo - JavaScript

​2. Crear Hilo de Conversación

​Endpoint

​Propósito

​Encabezados requeridos

​Encabezados opcionales

​Cuerpo de la solicitud

​Respuesta exitosa (HTTP 201)

​Ejemplo - Python

​Ejemplo - JavaScript

​3. Ejecutar Run de Conversación

​Endpoint

​Propósito

​Encabezados requeridos

​Encabezados opcionales

​Parámetros de ruta

​Cuerpo de la solicitud

​Campos de la solicitud

​Respuesta exitosa (HTTP 201)

​Ejemplo - Extracción clínica

​Ejemplo - Interacción de chat

​4. Actualizar Nota Clínica

​Endpoint

​Propósito

​Encabezados requeridos

​Encabezados opcionales

​Parámetros de ruta

​Cuerpo de la solicitud

​Campos de la solicitud

​Respuesta exitosa (HTTP 200)

​Ejemplo - Python

​Ejemplo - JavaScript

​Ejemplo de Flujo de Trabajo Completo

​Python - Flujo de trabajo completo

​Plantillas Clínicas Compatibles

​SOAP (Subjetivo, Objetivo, Evaluación, Plan)

​BIRP (Comportamiento, Intervención, Respuesta, Plan)

​DAP (Datos, Evaluación, Plan)

​Plantillas Personalizadas

​Manejo de Errores

​Errores comunes

​Formato de respuesta de error

​Próximos pasos

Ver API Codify

Manejo de errores

Autenticación

Referencia OpenAPI

Resumen del Flujo de Trabajo

1. Crear Transcripción

Endpoint

Propósito

Encabezados requeridos

Encabezados opcionales

Cuerpo de la solicitud

Campos de la solicitud

Respuesta exitosa (HTTP 201)

Ejemplo - Python

Ejemplo - JavaScript

2. Crear Hilo de Conversación

Endpoint

Propósito

Encabezados requeridos

Encabezados opcionales

Cuerpo de la solicitud

Respuesta exitosa (HTTP 201)

Ejemplo - Python

Ejemplo - JavaScript

3. Ejecutar Run de Conversación

Endpoint

Propósito

Encabezados requeridos

Encabezados opcionales

Parámetros de ruta

Cuerpo de la solicitud

Campos de la solicitud

Respuesta exitosa (HTTP 201)

Ejemplo - Extracción clínica

Ejemplo - Interacción de chat

4. Actualizar Nota Clínica

Endpoint

Propósito

Encabezados requeridos

Encabezados opcionales

Parámetros de ruta

Cuerpo de la solicitud

Campos de la solicitud

Respuesta exitosa (HTTP 200)

Ejemplo - Python

Ejemplo - JavaScript

Ejemplo de Flujo de Trabajo Completo

Python - Flujo de trabajo completo

Plantillas Clínicas Compatibles

SOAP (Subjetivo, Objetivo, Evaluación, Plan)

BIRP (Comportamiento, Intervención, Respuesta, Plan)

DAP (Datos, Evaluación, Plan)

Plantillas Personalizadas

Manejo de Errores

Errores comunes

Formato de respuesta de error

Próximos pasos