> ## 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. # 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 ```bash theme={null} POST /v1/codify ``` ### Headers requeridos ```http theme={null} Content-Type: application/json Authorization: Bearer TU_CLAVE_API ``` ### Headers opcionales ```http theme={null} 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 ```json theme={null} { "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) ```json theme={null} { "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:** ```json theme={null} { "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:** ```json theme={null} { "medical_note": "Paciente con diabetes...", "model": "high-quality" } ``` *** ## Estructura de la respuesta ### Respuesta exitosa (HTTP 200) ```json theme={null} { "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) ```json theme={null} { "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 ```python theme={null} # 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: ```python theme={null} 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:** ```python theme={null} 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: ```python theme={null} 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: ```python theme={null} 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](/sofia/es/api/operations#límites-y-cuotas) 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 Peticiones y respuestas reales Respuestas de error y cómo manejarlas Autenticación API y headers Especificación API completa