Guía Definitiva de JSON para FEV-RIPS: Todo lo que Necesitas Saber

¿Qué es JSON y por qué es Importante para FEV-RIPS?

¿Qué es JSON?

Imagina que estás haciendo una lista de las características de la mesa que vas a comprar para tu consultorio: color, material, alto y ancho. Éstas serán nuestras claves, y a cada una de ellas vamos a asignarle el valor correspondiente: color: blanco, material: madera, alto: 75, ancho: 120.

JSON (JavaScript Object Notation) funciona de manera similar. Es un formato de texto simple que sigue unas reglas básicas para organizar la información en pares de clave-valor, agrupándolas a través de llaves ({}) en objetos. Así:

{
    "color": "blanco",
    "material": "madera",
    "alto": 75,
    "ancho": 120
}

Herramientas JSON para FEV-RIPS

Editor JSON en Línea Validador de Estructura

Los componentes básicos de JSON

Para entender JSON, necesitas conocer dos conceptos fundamentales:

Clave (Key)

Es la etiqueta que describe el dato (ej: "producto"). Siempre va entre comillas dobles.

Valor (Value)

Es el dato en sí (ej: "manzanas"). Puede ser texto, números, listas o incluso otros objetos.

¿Por qué el Ministerio eligió JSON?

El Ministerio de Salud y Protección Social eligió JSON para el nuevo RIPS porque es:

Ligero: Archivos más pequeños que XML
Legible: Fácil de leer tanto para humanos como para sistemas
Estándar moderno: Es el formato actual para intercambio de datos en la web
Compatible: Funciona con todos los lenguajes de programación

Anatomía Básica de un Archivo JSON

Todo archivo JSON se compone de elementos fundamentales definidos en el Anexo Técnico 1 de la Resolución 2275. Veamos cada uno:

Objetos { }

Colecciones de pares clave-valor encerradas en llaves. Representan una entidad, como un usuario o una consulta.

Arreglos [ ]

Listas de elementos encerradas en corchetes. En RIPS los usarás para listar usuarios, consultas, procedimientos, etc.

Cadenas "texto"

Texto entre comillas dobles. Ejemplo: "Bogotá D.C."

Números

Cifras sin comillas. Ejemplo: 36341

Nulo (null)

Representa la ausencia de un valor. Útil para campos opcionales que no aplican.

Ejemplo básico de estructura JSON

{
  "clave1": "valor como texto",
  "clave2": 123,
  "clave3": null,
  "objeto": {
    "subclave": "subvalor"
  },
  "lista": [
    "elemento1",
    "elemento2"
  ]
}

Cómo Crear y Editar tus Archivos JSON

No necesitas software costoso. Tienes varias opciones, desde las más básicas hasta las más recomendadas para FEV-RIPS.

Editores de Texto Plano

Gratis

Puedes usar programas que ya tienes en tu computador:

Bloc de notas (Windows)
TextEdit (Mac)
Gedit (Linux)

Ventaja: No requiere instalación adicional

Desventaja: No resalta errores de sintaxis

Editores de Código

Gratis

Programas gratuitos diseñados para escribir código. Te muestran elementos en colores y avisan si hay errores:

Visual Studio Code: El más popular
Sublime Text: Ligero y rápido
Atom: Muy personalizable

Ventajas: Resaltado de sintaxis, detección de errores, autocompletado

Descargar VS Code

Editor JSON en Línea

Recomendado

Nuestra herramienta dedicada para FEV-RIPS:

Validación específica para RIPS
Plantillas predefinidas
Detección de errores comunes
No requiere instalación

Ventaja: Diseñado específicamente para la estructura FEV-RIPS

Abrir Editor

Construyendo el JSON para FEV-RIPS: Paso a Paso

Según el Anexo Técnico 1 de la Resolución 2275, la estructura de tu archivo JSON debe seguir un orden específico. Vamos a construirlo paso a paso.

1

Datos de la Transacción

Información general de la factura que va al inicio del archivo

Número de documento del obligado
Número de factura
Tipo y número de nota (si aplica)

2

Arreglo de Usuarios

Lista de todos los usuarios atendidos en la factura

Un objeto por cada usuario
Datos de identificación y demografía
Servicios asociados a cada usuario

3

Servicios por Usuario

Dentro de cada usuario, un objeto que agrupa sus servicios

consultas, procedimientos, urgencias
hospitalizacion, recienNacidos
medicamentos, otrosServicios

Estructura General

{
  "numDocumentoIdObligado": "900000000",
  "numFactura": "FEV00000001",
  "tipoNota": null,
  "numNota": null,

  "usuarios": [
    {
      // ... datos del usuario ...
      "servicios": { ... }
    }
  ]
}

Paso 1: Datos de la Transacción

Información de la Factura

Son los datos generales que van al inicio del archivo, antes del listado de usuarios:

{
  "numDocumentoIdObligado": "123456789",
  "numFactura": "FE12345",
  "tipoNota": null,
  "numNota": null
  // ... resto del archivo
}

Paso 2: El Arreglo de Usuarios

Lista de Usuarios Atendidos

Aquí listas a todos los usuarios atendidos en esa factura. Cada usuario es un objeto {} dentro del arreglo [], y cada usuario incluye sus propios servicios. Los campos obligatorios incluyen datos de identificación, demografía y ubicación:

"usuarios": [
  {
    "tipoDocumentoIdentificacion": "CC",
    "numDocumentoIdentificacion": "987654321",
    "tipoUsuario": "12",
    "fechaNacimiento": "1985-05-10",
    "codSexo": "F",
    "codPaisResidencia": "170",
    "codMunicipioResidencia": "05001",
    "codZonaTerritorialResidencia": "02",
    "incapacidad": "NO",
    "codPaisOrigen": "170",
    "consecutivo": 1,
    "servicios": {
      // Los servicios van aquí, dentro de cada usuario
    }
  }
]

Importante: Aunque sea un solo usuario, debe ir dentro de los corchetes [], y los servicios van dentro de cada usuario.

Campos Obligatorios del Usuario

tipoUsuario: Tipo de usuario según el asegurador (01-Contributivo, 12-Subsidiado, etc.)
codZonaTerritorialResidencia: Zona territorial (01-Urbana, 02-Rural)
incapacidad: Indica si el usuario presenta incapacidad (SI/NO)
codPaisOrigen: País de origen del usuario (170 para Colombia)
consecutivo: Número consecutivo del usuario en la factura

Paso 3: Los Servicios Dentro de Cada Usuario

Servicios Prestados por Usuario

Dentro de cada usuario, el objeto servicios agrupa todos los servicios prestados a ese usuario específico. Cada tipo de servicio es un arreglo. Solo incluye los tipos que efectivamente prestaste a ese usuario. Cada servicio debe incluir campos obligatorios como autorización, códigos de prestador, diagnósticos y valores de recaudo:

{
  // ... datos del usuario ...
  "servicios": {
    "consultas": [
      {
        "codPrestador": "051234567801",
        "fechaInicioAtencion": "2025-07-01 10:00",
        "numAutorizacion": "AUT001",
        "codConsulta": "890201",
        "modalidadGrupoServicioTecSal": "01",
        "grupoServicios": "02",
        "codServicio": 328,
        "finalidadTecnologiaSalud": "44",
        "causaMotivoAtencion": "38",
        "codDiagnosticoPrincipal": "J069",
        "codDiagnosticoRelacionado1": null,
        "codDiagnosticoRelacionado2": null,
        "codDiagnosticoRelacionado3": null,
        "tipoDiagnosticoPrincipal": "01",
        "tipoDocumentoIdentificacion": "CC",
        "numDocumentoIdentificacion": "123456789",
        "vrServicio": 50000,
        "conceptoRecaudo": "01",
        "valorPagoModerador": 5000,
        "numFEVPagoModerador": "FEPM001",
        "consecutivo": 1
      }
    ],
    "medicamentos": [
      {
        "codPrestador": "051234567801",
        "numAutorizacion": "AUT003",
        "codMedicamento": "12345-67-89",
        "tipoMedicamento": "1",
        "nombreGenerico": "IBUPROFENO",
        "formaFarmaceutica": "TABLETA",
        "concentracion": "400 MG",
        "unidadMedida": "TABLETA",
        "numUnidades": 10,
        "vrUnitarioMedicamento": 500,
        "vrServicio": 5000,
        "conceptoRecaudo": "01",
        "valorPagoModerador": 500,
        "numFEVPagoModerador": "FEPM003",
        "fechaSuministro": "2025-07-01",
        "consecutivo": 1
      }
    ]
  }
}

Clave: Los servicios están asociados a cada usuario individual, no a nivel de factura.

Cambios en Medicamentos

La estructura de medicamentos ha cambiado respecto a versiones anteriores. Ahora incluye campos específicos como:

codMedicamento: Código del medicamento según el registro sanitario
nombreGenerico: Denominación común internacional (DCI)
formaFarmaceutica: Forma de presentación del medicamento
concentracion: Concentración del principio activo
numUnidades: Cantidad dispensada
fechaSuministro: Fecha en que se dispensó el medicamento

¡Atención a las comas!

Se usa una coma , para separar cada par clave-valor y cada objeto en una lista, excepto el último. Un error de coma es la falla más común en archivos JSON.

Poniéndolo Todo Junto: Un Ejemplo Completo

Aquí tienes un ejemplo completo que une todas las piezas. Este es el tipo de archivo que generarás para soportar tu factura electrónica:

{
  "numDocumentoIdObligado": "123456789",
  "numFactura": "FE12345",
  "tipoNota": null,
  "numNota": null,
  "usuarios": [
    {
      "tipoDocumentoIdentificacion": "CC",
      "numDocumentoIdentificacion": "987654321",
      "tipoUsuario": "12",
      "fechaNacimiento": "1985-05-10",
      "codSexo": "F",
      "codPaisResidencia": "170",
      "codMunicipioResidencia": "05001",
      "codZonaTerritorialResidencia": "02",
      "incapacidad": "NO",
      "codPaisOrigen": "170",
      "consecutivo": 1,
      "servicios": {
        "consultas": [
          {
            "codPrestador": "051234567801",
            "fechaInicioAtencion": "2025-07-01 10:00",
            "numAutorizacion": "AUT001",
            "codConsulta": "890201",
            "modalidadGrupoServicioTecSal": "01",
            "grupoServicios": "02",
            "codServicio": 328,
            "finalidadTecnologiaSalud": "44",
            "causaMotivoAtencion": "38",
            "codDiagnosticoPrincipal": "J069",
            "codDiagnosticoRelacionado1": null,
            "codDiagnosticoRelacionado2": null,
            "codDiagnosticoRelacionado3": null,
            "tipoDiagnosticoPrincipal": "01",
            "tipoDocumentoIdentificacion": "CC",
            "numDocumentoIdentificacion": "123456789",
            "vrServicio": 50000,
            "conceptoRecaudo": "01",
            "valorPagoModerador": 5000,
            "numFEVPagoModerador": "FEPM001",
            "consecutivo": 1
          }
        ],
        "medicamentos": [
          {
            "codPrestador": "051234567801",
            "numAutorizacion": "AUT003",
            "codMedicamento": "12345-67-89",
            "tipoMedicamento": "1",
            "nombreGenerico": "IBUPROFENO",
            "formaFarmaceutica": "TABLETA",
            "concentracion": "400 MG",
            "unidadMedida": "TABLETA",
            "numUnidades": 10,
            "vrUnitarioMedicamento": 500,
            "vrServicio": 5000,
            "conceptoRecaudo": "01",
            "valorPagoModerador": 500,
            "numFEVPagoModerador": "FEPM003",
            "fechaSuministro": "2025-07-01",
            "consecutivo": 1
          }
        ]
      }
    }
  ]
}

¡Felicitaciones!

Has creado un archivo JSON válido para FEV-RIPS que cumple con todos los requisitos de la Resolución 2275 de 2023.

Mejores Prácticas y Errores Comunes

Errores de Sintaxis

Los más comunes que debes evitar:

Comas faltantes o extras
Comillas dobles vs simples
Llaves o corchetes no cerrados
Caracteres especiales sin escapar

Mejores Prácticas

Recomendaciones para crear JSON de calidad:

Usa indentación consistente (2 o 4 espacios)
Valida antes de enviar
Mantén nombres de claves consistentes
Documenta tu estructura

Validación Obligatoria

Campos que siempre debes verificar:

Formatos de fecha (YYYY-MM-DD)
Códigos según maestros oficiales
Valores numéricos correctos
Campos obligatorios completos

Validación y Herramientas Recomendadas

Crear el archivo JSON es solo el primer paso. La validación es crucial para asegurar que tu archivo cumple con todos los requisitos de la Resolución 2275 de 2023 antes de enviarlo.

1

Valida la Sintaxis

Asegúrate de que tu JSON esté bien formado. Usa validadores en línea o editores que detecten errores de sintaxis automáticamente.

2

Verifica la Estructura

Confirma que tu archivo sigue la estructura exacta definida en el Anexo Técnico 1, con todos los campos obligatorios.

3

Prueba con Datos Reales

Haz pruebas con datos reales antes de la implementación completa. Esto te ayudará a identificar problemas específicos de tu operación.

¿Quieres acelerar tu implementación?

Nuestras herramientas especializadas para FEV-RIPS te permiten generar, validar y enviar archivos JSON de manera automática, cumpliendo al 100% con la normativa.

Conocer Soluciones