Estructura del archivo RIPS JSON: qué va en cada campo y por qué te lo glosan

Si alguna vez abriste un archivo RIPS JSON y sentiste que era un bloque de texto incomprensible, este artículo es para ti. No vamos a hablar de teoría ni de normas generales: vamos a desarmar el archivo sección por sección, explicarte qué va en cada campo y mostrarte los errores que te lo rechazan.

Si quieres el contexto general de por qué cambió el formato y cuáles son los errores más comunes, revisa nuestra guía de RIPS JSON sin glosas. Acá vamos directo a la estructura.

Los bloques que componen un RIPS JSON

Un archivo RIPS JSON tiene tres niveles:

1. Encabezado (header): datos de la IPS que envía.
2. Usuarios (rips_usuario): datos de cada paciente atendido.
3. Servicios: uno o más arreglos según el tipo de atención (consulta, procedimiento, medicamento, etc.).

El orden importa. El validador recorre el archivo en secuencia y si la estructura no coincide con lo que espera, rechaza todo.

Encabezado del archivo: lo primero que ve el validador

El encabezado identifica quién envía los RIPS. Los campos obligatorios:

• codigoPrestador: código habilitación de tu IPS en el REPS. Si está mal digitado o no corresponde al departamento, rechazo inmediato.
• razonSocial: nombre exacto de la IPS como aparece en el registro.
• tipoIdentificacion + numeroIdentificacion: NIT con dígito de verificación. Ojo: el tipo debe ser “NI” para NIT, no “CC” ni “NIT”.
• departamento + municipio: deben coincidir con el código de habilitación del prestador.
• periodo: mes y año de los servicios reportados (formato YYYY-MM).

Error frecuente: enviar el NIT sin dígito de verificación. El validador lo detecta porque cruza con el REPS y si no cuadra, glosa.

rips_usuario: los datos de cada paciente

Este es el arreglo donde se reportan todas las personas atendidas. Cada registro tiene:

Campos obligatorios

• tipoDocumentIdentificacion: CC, TI, CE, PA, MS, RC, AS, CN, CD, SC, PE, PT. Cada uno tiene reglas de uso según la edad y nacionalidad.
• numeroDocumentIdentificacion: debe ser válido para el tipo de documento. CC de 6 a 10 dígitos, TI con formato específico.
• primerApellido, primerNombre: obligatorios. Los segundos apellidos y nombres son opcionales pero recomendados.
• fechaNacimiento: formato YYYY-MM-DD. El validador cruza esta fecha con la edad reportada.
• sexo: M o F. No se acepta otro valor.
• departamento + municipio de residencia: códigos DIVIPOLA. Si el paciente es extranjero sin residencia definida, hay un código específico.

Los 3 errores que más duelen en esta sección

1. Tipo de documento no corresponde a la edad. TI para mayores de 18, CC para menores. El sistema cruza automáticamente tipoDocumentIdentificacion con fechaNacimiento.

2. Edad inconsistente con la fecha de nacimiento. Si el paciente nació el 15 de marzo de 1990 y la fecha de corte es junio de 2026, la edad debe ser 36. Si pones 35 o 37, glosa.

3. Campos vacíos en nombres o apellidos. El validador no acepta primerApellido: "". Si el paciente solo tiene un apellido (caso de algunos ciudadanos extranjeros), se debe usar el campo de segundo apellido como vacío pero el primero siempre debe tener contenido.

rips_consulta: consultas y valoraciones

Para cada consulta médica reportada:

Campos obligatorios

• numeroConsultas: cantidad de consultas de ese tipo en el período.
• tipoDiagnosticoPrincipal: código CIE-10 completo (hasta 4 caracteres, ej: J06.9). No se aceptan categorías solas (poner “J06” sin el decimal cuenta como error).
• tipoDiagnosticoPrincipal (relación): puede ser “1” (confirmado), “2” (sospechoso) o “3” (queja).
• valorConsulta + valorCuotaModeradora + valorPagoModerador: valores monetarios en enteros, sin decimales, sin puntos de miles.
• consecutivo: número único de la factura asociada.

Lo que más se equivoca aquí

Diagnóstico CIE-10 incompleto. Poner “K30” en vez de “K30.9” cuando el código específico existe. El validador cruza contra el catálogo completo y si existe una versión más específica, la requiere.

Valores que no coinciden con la factura. El sistema cruza el valor de la consulta en RIPS con el valor en la factura electrónica de venta. Si no son iguales, glosa.

Consecutivo que no existe en la FEV. Cada consulta debe estar vinculada a una factura electrónica válida. Si el consecutivo no aparece en la DIAN, rechazo.

rips_procedimiento: cirugías y procedimientos

Para procedimientos quirúrgicos y no quirúrgicos:

Campos clave

• codigoProcedimiento: código CUPS completo, sin puntos ni espacios. “891203” no es lo mismo que “891.203”.
• ambito: “1” ambulatorio, “2” hospitalario.
• finalidad: “1” diagnóstico, “2” terapéutico, “3” profiláctico, “4” rehabilitación.
• personalAtiende: “1” médico, “2” odontólogo, “3” enfermera, etc.
• diagnosticoPrincipal + diagnosticoRelacionado: CIE-10 del diagnóstico que motivó el procedimiento.

Errores típicos

CUPS que no corresponde al diagnóstico. Si reportas un procedimiento de cardiología (código CUPS 89xxxx) con un diagnóstico dermatológico (código Lxx), el validador lo detecta porque cruza rangos de códigos.

Finalidad vacía o incorrecta. Si el procedimiento fue terapéutico pero marcas “diagnóstico”, el cruce con el diagnóstico principal no tiene sentido y se genera glosa.

Falta de diagnóstico relacionado cuando es obligatorio. Algunos procedimientos exigen un segundo diagnóstico. El Anexo Técnico especifica cuáles.

rips_medicamento: medicamentos dispensados o formulados

Campos que importan

• codigoMedicamento: código del medicamento en el catálogo oficial (Cum o Invima).
• tipoMedicamento: “1” pos, “2” no pos.
• cantidadMedicamento + valorMedicamento: cantidad y costo unitario.
• diagnosticoPrincipal: CIE-10 que justifica la formulación.

Lo que más se rechaza

Medicamento sin justificación diagnóstica. Cada medicamento debe tener un diagnóstico que lo respalde. Si formulas omeprazol (para gastritis) pero el diagnóstico es J06.9 (infección respiratoria), no pasa.

Cantidad inconsistente. Si la cantidad no corresponde a las unidades del medicamento (cajas vs tabletas), el validador lo detecta según el catálogo.

Otros arreglos: urgencias, hospitalización, otros servicios

El JSON puede incluir arreglos adicionales según los servicios prestados:

• rips_urgencias: atención en servicio de urgencias. Incluye destino del paciente (alta, observación, hospitalización).
• rips_hospitalizacion: ingresos y egresos hospitalarios. Requiere causa externa, estado al egreso y días de estancia.
• rips_recienNacido: datos del recién nacido (peso, edad gestacional, diagnóstico al nacer).
• rips_otrosServicios: servicios que no clasifican en los arreglos anteriores.

Cada uno tiene sus propios campos obligatorios y validaciones específicas. La lógica es la misma: si un campo cruza con otro, el validador verifica que sean consistentes.

Campos opcionales que conviene llenar

El validador no exige estos campos, pero llenarlos reduce observaciones futuras:

• diagnosticoRelacionado en consultas y procedimientos: facilita auditorías y demuestra trazabilidad.
• fechaConsulta / fechaProcedimiento: si no se envían, el sistema asume que corresponden al período del encabezado. Si hubo servicios en fechas diferentes, es mejor especificar.
• numeroAutorizacion: para servicios que requieren autorización previa de la EPS. Si se omite y la EPS lo requiere, generarás una observación.

Antes de enviar: checklist rápido

Pasa por esta lista cada vez que vayas a generar un archivo RIPS JSON:

1. El NIT del encabezado tiene dígito de verificación y coincide con el REPS.
2. Todos los pacientes tienen tipo de documento correcto según su edad.
3. Todos los diagnósticos CIE-10 tienen 3 o 4 caracteres (categoría completa).
4. Todos los códigos CUPS están sin puntos ni espacios.
5. Los valores monetarios coinciden con las facturas electrónicas.
6. Cada servicio tiene al menos un diagnóstico asociado.
7. El período del encabezado corresponde al mes que estás reportando.

Si quieres profundizar en los errores más frecuentes y cómo corregirlos, nuestra guía de RIPS JSON sin glosas tiene el detalle de cada uno. Y si necesitas contexto sobre los cambios recientes en la normatividad, revisa lo que cambió con la Resolución 948 de 2026.

Si facturas en una IPS y quieres ver cómo se ve un sistema que arma el JSON completo con todos los campos validados desde el inicio, escríbenos por WhatsApp. La demo toma 15 minutos y es sin compromiso.