Métodos API REST HKA Fácil RIPS - Indice Manual Integración Directa HKA Fácil RIPS

Método Servicio Emisión Web HKA Fácil RIPS

Los parámetros a incorporar en los métodos de esta API deberán cumplir con el formato y las directivas que correspondan según las siguientes reglas:

Formato	Descripción
AN	Carácter alfanumérico
UUID	Identificador único universal (formato: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
date	Fecha en formato ISO 8601: YYYY-MM-DD
datetime	Fecha y hora en formato ISO 8601: YYYY-MM-DDThh:mm:ssZ
boolean	Valor lógico: true o false
integer	Número entero (INT32). Valor máximo: 2,147,483,647
decimal	Número decimal
base64	Cadena codificada en Base64

Requerido	Descripción
SI	Campo obligatorio
NO	Campo opcional
C/C	Requerido cuando corresponda (bajo una condición específica)

Método Enviar

La función encargada de enviar un RIPS (Registro Individual de Prestación de Servicios) al Ministerio de Salud de Colombia. El proceso incluye autenticación automática, creación del RIPS (si no se proporciona idRips) y generación/envío al Ministerio.

Request Método Enviar

Atributo	Tipo Dato	Formato	Requerido	Descripción
tokenEmpresa	String	40	SI	Token de identificación de la empresa en la plataforma HKA Fácil RIPS. Suministrado por The Factory HKA Colombia al momento de la habilitación. Rechazo Si el token no tiene exactamente 40 caracteres alfanuméricos (ver código de negocio 111)
tokenPassword	String	40	SI	Token contraseña de acceso a la plataforma HKA Fácil RIPS. Suministrado por The Factory HKA Colombia al momento de la habilitación. Rechazo Si el token no tiene exactamente 40 caracteres alfanuméricos (ver código de negocio 111)
tipoRips	String	2	SI	Tipo de documento RIPS a generar y enviar. Valores permitidos: 01 RIPS con Factura Electrónica de Venta (FEV) 02 RIPS sin Factura Electrónica de Venta (Sin FEV) 03 RIPS con Nota Crédito 04 RIPS con Nota Débito 05 RIPS con documento de contingencia Rechazo Si el valor no corresponde a uno de los tipos permitidos (ver código de negocio 109)
idRips	String	UUID	NO	Identificador único (UUID) de un RIPS previamente creado en el sistema. Si se omite o se envía nulo, el sistema crea un nuevo RIPS automáticamente y retorna el idRips generado en la respuesta. Usar este campo para reintentar el envío de un RIPS ya creado pero no enviado al Ministerio. Rechazo Si el UUID proporcionado no existe en el sistema (ver código de negocio 102)
ripsJson	Object	-	SI	Objeto JSON con la estructura de datos del RIPS a enviar al Ministerio de Salud. Contiene dos propiedades: rips (estructura del RIPS) y xmlFevFile (archivo XML de la FEV en Base64). (ver detalle en Object.ripsJson)

Object.ripsJson

Atributo	Tipo Dato	Formato	Requerido	Descripción
rips	Object	-	SI	Objeto con la estructura de datos del RIPS según la normativa del Ministerio de Salud. (ver detalle en Object.rips)
xmlFevFile	String	base64	C/C	Contenido del archivo XML de la Factura Electrónica de Venta (FEV) codificado en Base64. Obligatorio cuando tipoRips es 01 (RIPS con FEV). Enviar cadena vacía "" cuando tipoRips es 02 (sin FEV).

Object.rips

Atributo	Tipo Dato	Formato	Requerido	Descripción
numDocumentoIdObligado	String	..20	SI	NIT o número de identificación del prestador de servicios de salud obligado a reportar RIPS.
numNota	String	..50	SI	Número de la nota, factura o documento asociado al RIPS.
tipoNota	String	2	SI	Tipo del documento asociado al RIPS. Valores ejemplo: NC Nota Crédito FV Factura de Venta
usuarios	Array <Object.usuario>	-	SI	Lista de usuarios/pacientes con los servicios de salud prestados. Debe contener al menos un usuario. (ver detalle en Object.usuario)

Ejemplo de Request

<syntaxhighlight lang="json"> {

 "tokenEmpresa": "abc123def456ghi789jkl012mno345pqr678stu9",
 "tokenPassword": "xyz987wvu654tsr321qpo098nml765kji432hgf1",
 "tipoRips": "02",
 "idRips": null,
 "ripsJson": {
   "rips": {
     "numDocumentoIdObligado": "900390126",
     "numNota": "RT45657",
     "tipoNota": "NC",
     "usuarios": [
       {
         "tipoDocumentoIdentificacion": "CC",
         "numDocumentoIdentificacion": "1234567890",
         "tipoUsuario": "12",
         "fechaNacimiento": "1990-01-01",
         "codSexo": "M",
         "servicios": {
           "otrosServicios": [
             {
               "codPrestador": "900390126",
               "fechaInicioAtencion": "2025-10-16",
               "numAutorizacion": "12345",
               "codServicio": "890201",
               "finalidadTecnologiaSalud": "01",
               "causaMotivoAtencion": "01",
               "codDiagnosticoPrincipal": "Z000",
               "tipoDiagnosticoPrincipal": "01",
               "vrServicio": 0,
               "conceptoRecaudo": "05",
               "valorPagoModerador": 0,
               "numFEVPagoModerador": ""
             }
           ]
         }
       }
     ]
   },
   "xmlFevFile": ""
 }

} </syntaxhighlight>

Response Método Enviar

Atributo	Tipo Dato	Formato	Descripción
codigo	integer	INT32	Código de negocio del resultado de la operación. Ver Códigos de Respuesta - Método Enviar
mensaje	String	AN	Mensaje descriptivo del resultado de la operación.
estado	boolean	boolean	Indica si la operación fue exitosa. true El RIPS fue enviado y aceptado por el Ministerio. false La operación falló o el RIPS fue rechazado.
idRips	String	UUID	Identificador único del RIPS procesado. Conservar este valor para consultas posteriores con el método EstadoRIPS.
archivoRetornado	Object	-	Objeto con los detalles del resultado retornado por el Ministerio de Salud. null si la operación falló antes de llegar al Ministerio. (ver detalle en Object.archivoRetornado)
errors	Array <String>	AN	Lista de mensajes de error de validación de campos del request. Solo presente cuando el código de negocio es 109 o 111.

Método EstadoRIPS

La función encargada de consultar el estado actual de un RIPS que fue enviado previamente al Ministerio de Salud de Colombia. Un RIPS puede estar en uno de los siguientes estados: VALIDADO, RECHAZADO o CREADO.

@NOTA:' Este método es útil para verificar el resultado de un envío cuando el método Enviar no retornó una respuesta definitiva (por ejemplo, por timeout de red).

Request Método EstadoRIPS

Atributo	Tipo Dato	Formato	Requerido	Descripción
tokenEmpresa	String	40	SI	Token de identificación de la empresa en la plataforma HKA Fácil RIPS. Suministrado por The Factory HKA Colombia al momento de la habilitación. Rechazo Si el token no tiene exactamente 40 caracteres alfanuméricos (ver código de negocio 111)
tokenPassword	String	40	SI	Token contraseña de acceso a la plataforma HKA Fácil RIPS. Suministrado por The Factory HKA Colombia al momento de la habilitación. Rechazo Si el token no tiene exactamente 40 caracteres alfanuméricos (ver código de negocio 111)
idRips	String	UUID	SI	Identificador único (UUID) del RIPS a consultar. Este valor es retornado por el método Enviar en el campo idRips de la respuesta. Formato: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Ejemplo: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Rechazo Si el UUID proporcionado no existe en el sistema (ver código de negocio 102)

Ejemplo de Request

<syntaxhighlight lang="json"> {

 "tokenEmpresa": "abc123def456ghi789jkl012mno345pqr678stu9",
 "tokenPassword": "xyz987wvu654tsr321qpo098nml765kji432hgf1",
 "idRips": "3fa85f64-5717-4562-b3fc-2c963f66afa6"

} </syntaxhighlight>

Response Método EstadoRIPS

Atributo	Tipo Dato	Formato	Descripción
codigo	integer	INT32	Código de negocio del resultado de la operación. Ver Códigos de Respuesta - Método EstadoRIPS
mensaje	String	AN	Mensaje descriptivo del estado actual del RIPS.
estado	boolean	boolean	Indica si la consulta fue exitosa y el RIPS está validado. true El RIPS fue aceptado por el Ministerio (estado: VALIDADO). false En cualquier otro caso (RECHAZADO, CREADO, no encontrado, error).
idRips	String	UUID	Identificador único del RIPS consultado.
archivoRetornado	Object	-	Objeto con los detalles del resultado retornado por el Ministerio de Salud. null cuando el RIPS está en estado CREADO, no fue encontrado, o hubo error de autenticación. (ver detalle en Object.archivoRetornado)
errors	Array <String>	AN	Lista de mensajes de error de validación de campos del request. Solo presente cuando el código de negocio es 109 o 111.