Estructura de Petición y Respuesta

Guía completa de peticiones y respuestas de la API Codify: codificación médica ICD-10 con análisis impulsado por IA

La API Codify proporciona servicios de codificación médica ICD-10 impulsados por IA. Procesa notas clínicas o archivos PDF y devuelve evaluaciones estructuradas de códigos médicos con puntuaciones de confianza y justificaciones.

---

​

Estructura de la petición

​

Endpoint

POST /v1/codify

​

Headers requeridos

Content-Type: application/json
Authorization: Bearer TU_CLAVE_API

​

Headers opcionales

x-doctor: dr_123      (para seguimiento)
x-patient: pt_456     (para seguimiento)

​

Estructura del cuerpo de la petición

El campo medical_note es requerido. Opcionalmente puede incluir pdf_file para contexto adicional:

​

Requerido: Entrada de texto

{
  "medical_note": "Paciente presenta Diabetes Mellitus tipo 2. Medicación actual: Metformina 500mg cada 12h, Glipizida 5mg al día. Niveles de glucosa estables. Sin complicaciones. Buena adherencia al tratamiento. HbA1c: 6.8%.",
  "model": "balanced"
}

​

Opcional: Entrada PDF (para contexto adicional)

{
  "pdf_file": {
    "type": "file",
    "source_type": "base64",
    "data": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9GaWx0ZXI...",
    "mime_type": "application/pdf",
    "filename": "informe_medico.pdf"
  },
  "model": "high-quality"
}

---

​

Campos requeridos

​

medical_note (string, REQUERIDO)

Texto narrativo clínico para procesar para codificación ICD-10. Este campo es siempre requerido.

Ejemplos:

• “Paciente ingresado con infarto agudo de miocardio”
• “Diabetes Mellitus tipo 2, controlada con medicamentos orales”
• “Paciente diabético con mal control glucémico, HbA1c 9.2%”

Restricciones:

• Tamaño máximo: 50 KB (~25,000 palabras)
• Codificación UTF-8
• Siempre requerido

​

pdf_file (objeto, opcional)

Objeto de archivo PDF opcional para proporcionar contexto adicional o documentos de soporte.

Estructura:

{
  "type": "file",
  "source_type": "base64",
  "data": "JVBERi0xLjQK...",
  "mime_type": "application/pdf",
  "filename": "informe_medico.pdf"
}

Restricciones de campos:

• type: Debe ser "file" (validado)
• source_type: Debe ser "base64" (validado)
• data: Contenido PDF codificado en base64 (máx 5MB decodificado)
• mime_type: Debe ser "application/pdf" (validado)
• filename: String (requerido)
• Opcional - se puede proporcionar junto con medical_note para contexto adicional

---

​

Campos opcionales

​

model (string, opcional)

Selección del nivel de calidad del modelo de IA para procesamiento.

Opciones disponibles:

• "fast" - Procesamiento más rápido con buena precisión (recomendado para alto volumen)
• "balanced" - Balance entre velocidad y precisión (predeterminado)
• "high-quality" - Máxima precisión con procesamiento más lento (recomendado para casos complejos)

Predeterminado: "balanced" si no se especifica

Ejemplo:

{
  "medical_note": "Paciente con diabetes...",
  "model": "high-quality"
}

---

​

Estructura de la respuesta

​

Respuesta exitosa (HTTP 200)

{
  "final_code_assessments": [
    {
      "code": "E11.9",
      "description": "Diabetes mellitus tipo 2 sin complicaciones",
      "justification": "La nota documenta Diabetes tipo 2 sin mención de descompensación ni complicaciones; corresponde a E11.9 (DM2 sin complicaciones). Los niveles estables de glucosa en sangre y HbA1c de 6.8% indican diabetes controlada sin evidencia de complicaciones.",
      "confidence_percent": 95.2
    },
    {
      "code": "Z79.84",
      "description": "Uso prolongado (actual) de medicamentos hipoglucemiantes orales",
      "justification": "El paciente usa metformina y glipizida de forma crónica; ambos son antidiabéticos orales.",
      "confidence_percent": 98.1
    }
  ],
  "discarded_code_assessments": [
    {
      "code": "E11.65",
      "description": "Diabetes mellitus tipo 2 con hiperglucemia",
      "justification": "Descartado porque los niveles de glucosa en sangre son estables y controlados (120-140 mg/dL en ayunas), no indicando hiperglucemia.",
      "confidence_percent": 12.3
    }
  ],
  "run_id": "1ef8e0d4-7890-6b3c-8f90-abcdef123456"
}

​

Respuesta de error (HTTP 4xx/5xx)

{
  "success": false,
  "error": "Bad Request",
  "details": "Se debe proporcionar medical_note o pdf_file"
}

---

​

Campos de respuesta explicados

​

final_code_assessments (array)

Array de evaluaciones de códigos ICD-10 aprobadas seleccionadas por la IA.

Cada evaluación contiene:

• code (string): Código médico ICD-10 (ej: “E11.9”)
• description (string): Descripción médica del código
• justification (string): Razonamiento de la IA para la selección del código
• confidence_percent (número): Puntuación de confianza (0-100)

​

discarded_code_assessments (array)

Array de evaluaciones de códigos consideradas pero rechazadas. Muestra el proceso de toma de decisiones de la IA y los códigos que fueron evaluados pero no incluidos.

Misma estructura que final_code_assessments

​

run_id (string)

Identificador único (UUID) para esta ejecución de codificación.

Usos:

• Seguimiento y auditoría
• Problemas de depuración
• Correlación con registros de backend
• Solicitudes de soporte

---

​

Casos especiales

​

Entrada muy larga

Si su texto clínico excede 50KB o el PDF excede 5MB:

Opción 1: Dividir en múltiples llamadas

# Procesar por secciones
sections = split_into_sections(long_text)
results = []
for section in sections:
    result = codify(section)
    results.append(result)

Opción 2: Comprimir y optimizar

• Para texto: Eliminar espacios en blanco innecesarios y formato
• Para PDFs: Comprimir PDF antes de codificar, eliminar páginas no esenciales

Opción 3: Solicitar límites enterprise Contacte a su representante de ventas para planes con límites superiores.

​

Codificación de archivo PDF

Para codificar un archivo PDF para la API:

import base64

def encode_pdf(file_path):
    """Codifica un archivo PDF a base64"""
    with open(file_path, 'rb') as file:
        pdf_bytes = file.read()
        base64_data = base64.b64encode(pdf_bytes).decode('utf-8')
    
    return {
        "type": "file",
        "source_type": "base64",
        "data": base64_data,
        "mime_type": "application/pdf",
        "filename": file_path.split('/')[-1]
    }

# Uso
pdf_file = encode_pdf("informe_medico.pdf")
payload = {"pdf_file": pdf_file}

​

Preprocesamiento de texto

Opcional pero recomendado:

def clean_clinical_text(text):
    """Limpia texto clínico para mejor procesamiento"""
    # Eliminar saltos de línea excesivos
    text = re.sub(r'\n{3,}', '\n\n', text)
    
    # Normalizar espacios
    text = re.sub(r'\s+', ' ', text)
    
    # Eliminar caracteres de control
    text = ''.join(char for char in text if char.isprintable() or char in '\n\t')
    
    return text.strip()

---

​

Optimización de peticiones

​

Procesamiento por lotes

Para procesar múltiples notas, envíe peticiones paralelas:

import concurrent.futures

def codify_note(note_text):
    """Procesar una sola nota médica"""
    return requests.post(
        f"{API_URL}/v1/codify",
        json={"medical_note": note_text},
        headers=headers
    ).json()

def process_batch(notes, max_workers=10):
    """Procesar múltiples notas en paralelo"""
    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
        futures = [executor.submit(codify_note, note) for note in notes]
        results = []
        for future in concurrent.futures.as_completed(futures):
            results.append(future.result())
    return results

# Uso
notes = ["Paciente con diabetes...", "Paciente con neumonía..."]
results = process_batch(notes)

​

Manejo de puntuaciones de confianza

Filtrar resultados basados en umbrales de confianza:

def filter_high_confidence(response, threshold=80):
    """Filtrar códigos con confianza superior al umbral"""
    return [
        assessment for assessment in response['final_code_assessments']
        if assessment['confidence_percent'] >= threshold
    ]

# Uso
result = codify_note("Paciente con diabetes...")
high_confidence_codes = filter_high_confidence(result, threshold=85)

---

​

Límites y restricciones

Ver Límites y cuotas completos para información detallada.

Límites principales:

• Tamaño máximo de medical_note: 50 KB (~25,000 palabras)
• Tamaño máximo de pdf_file: 5 MB (decodificado)
• Tiempo de espera de procesamiento: 10 minutos (600 segundos)
• Límite de velocidad: Varía según el plan del cliente

---

​

Próximos pasos

Ver ejemplos

Peticiones y respuestas reales

Manejo de errores

Respuestas de error y cómo manejarlas

Autenticación

Autenticación API y headers

Referencia OpenAPI

Especificación API completa