Saltar al contenido principal
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