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

# API de Flujo de Documentación Clínica

> Guía completa de gestión de transcripciones, hilos de conversación con IA y generación de notas clínicas

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:

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

***

## 1. Crear Transcripción

### Endpoint

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

```http theme={null}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123
```

### Encabezados opcionales

```http theme={null}
x-patient: pt_456
```

### Cuerpo de la solicitud

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

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

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

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

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

```http theme={null}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123
```

### Encabezados opcionales

```http theme={null}
x-patient: pt_456
```

### Cuerpo de la solicitud

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

```json theme={null}
{}
```

### Respuesta exitosa (HTTP 201)

```json theme={null}
{
  "thread_id": "thread-abc123",
  "created_at": "2023-10-09T10:00:00.000Z",
  "status": "active"
}
```

### Ejemplo - Python

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

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

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

```http theme={null}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123
```

### Encabezados opcionales

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

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

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

### Ejemplo - Extracción clínica

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

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

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

```http theme={null}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-doctor: dr_123
```

### Encabezados opcionales

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

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

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

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

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

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

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

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

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

```json theme={null}
{
  "success": false,
  "error": "Bad Request",
  "details": "duration_seconds y original_transcript son requeridos"
}
```

***

## Próximos pasos

<Columns cols={2}>
  <Card title="Ver API Codify" href="/sofia/es/api/quickstart" icon="code">
    API de codificación médica ICD-10
  </Card>

  <Card title="Manejo de errores" href="/sofia/es/api/operations" icon="gear">
    Respuestas de error y estrategias de reintento
  </Card>

  <Card title="Autenticación" href="/sofia/es/api/auth" icon="key">
    Autenticación de API y encabezados
  </Card>

  <Card title="Referencia OpenAPI" href="/api-reference" icon="book">
    Especificación completa de la API
  </Card>
</Columns>