Ver el código de «Generalidades HKA Facil RIPS»

= Generalidades - HKA Fácil RIPS =

<includeonly>=</includeonly>==<font color="blue"> Historial de versiones </font>==<includeonly>=</includeonly>

{| class="wikitable"
|-
! Versión !! Fecha lanzamiento !! Descripción
|-
| 1.0.0 || 2025 || Versión inicial de la API REST HKA Fácil RIPS
|-
| 1.1.0 || 2025 || Mejoras en los códigos de negocio y documentación de respuestas
|}

----

== Cómo obtener soporte ==

* '''Soporte de 1er nivel:'''

Soporte telefónico / email / chat o tele-conferencias en horario 5×8 para atención de consultas y fallas de usuario.

* '''Soporte de 2do nivel:'''

Soporte resolución remota de incidencias en el sistema en horario 5×8.<br/>
Escriba a [mailto:soporte@thefactoryhka.com.co soporte@thefactoryhka.com.co]

'''Líneas de atención telefónica:'''

+57 (1) 311.3063

* Soporte Técnico → Opción 2
* Integración → Opción 5, luego Opción 1

=== Sesiones de Soporte ===

Dirigido a: Agencias Comerciales – Casas de Software Aliadas – Clientes Finales.

Horario: Martes y Jueves a partir de las 8:30 AM.

=== Sesiones Área Integración ===

Solución de casos de integración.

Dirigido a: Clientes que realicen desarrollos de software para integrarse con TFHKA, Casas de Software Aliadas.

Horario: Martes y Jueves a partir de las 8:30 AM.

----

== Descripción general ==

=== ¿Qué es HKA Fácil RIPS? ===

'''HKA Fácil RIPS''' es un servicio API REST (middleware) desarrollado por The Factory HKA Colombia que actúa como intermediario para la integración de los RIPS (Registro Individual de Prestación de Servicios) con el '''Ministerio de Salud y Protección Social de Colombia'''.

El servicio simplifica el proceso de generación, validación y envío de RIPS al Ministerio de Salud, ofreciendo un único punto de integración que maneja internamente la autenticación, la creación del paquete RIPS y la comunicación con el Ministerio.

=== ¿Qué son los RIPS? ===

Los '''RIPS''' (Registro Individual de Prestación de Servicios de Salud) son el conjunto de datos mínimos que el Sistema General de Seguridad Social en Salud requiere para el procesamiento de las reclamaciones de los servicios de salud prestados.

Toda Institución Prestadora de Servicios de Salud (IPS) o entidad que preste servicios de salud está obligada a reportar los RIPS al Ministerio de Salud conforme a la normativa vigente.

=== Tipos de RIPS soportados ===

El campo <code>tipoRips</code> indica el tipo de documento RIPS a generar:

{| class="wikitable"
|-
! Valor !! Descripción
|-
| <code>01</code> || RIPS con Factura Electrónica de Venta (FEV)
|-
| <code>02</code> || RIPS sin Factura Electrónica de Venta (Sin FEV)
|-
| <code>03</code> || RIPS con Nota Crédito
|-
| <code>04</code> || RIPS con Nota Débito
|-
| <code>05</code> || RIPS con documento de contingencia
|}


<font color="red">@IMPORTANTE:</font> El valor del campo <code>tipoRips</code> debe ser uno de los valores listados anteriormente. Un valor inválido retornará el código de negocio <code>109</code>.

----

== Ambientes de integración ==

La API HKA Fácil RIPS está disponible en dos ambientes:

=== Ambiente Demo (Pruebas) ===

Ambiente en el cual las operaciones '''no son transmitidas''' al Ministerio de Salud. Úselo durante el desarrollo y las pruebas de su integración.

 URL Base: https://demoapi-facilrips.thefactoryhka.com.co

Endpoints disponibles:
* <code>POST https://demoapi-facilrips.thefactoryhka.com.co/api/rips/enviar</code>
* <code>POST https://demoapi-facilrips.thefactoryhka.com.co/api/rips/estado</code>

=== Ambiente Productivo ===

Ambiente en el cual se realizan las operaciones reales que son transmitidas al Ministerio de Salud.

 URL Base: https://api-facilrips.thefactoryhka.com.co

Endpoints disponibles:
* <code>POST https://api-facilrips.thefactoryhka.com.co/api/rips/enviar</code>
* <code>POST https://api-facilrips.thefactoryhka.com.co/api/rips/estado</code>


<font color="red">@IMPORTANTE:</font> La URL del servicio en producción solo funciona bajo el protocolo '''HTTPS'''.

----

== Autenticación ==

La API HKA Fácil RIPS utiliza un modelo de autenticación basado en '''tokens de empresa'''. Cada petición debe incluir los siguientes campos en el cuerpo del request (body):

{| class="wikitable"
|-
! Campo !! Tipo !! Descripción
|-
| <code>tokenEmpresa</code> || <code>string</code> || Token de identificación de la empresa. Debe tener exactamente '''40 caracteres alfanuméricos'''.
|-
| <code>tokenPassword</code> || <code>string</code> || Token contraseña de acceso. Debe tener exactamente '''40 caracteres alfanuméricos'''.
|}

Estos tokens son proporcionados por el equipo de Integración de The Factory HKA Colombia al momento de la habilitación de la empresa en la plataforma.


<font color="red">@IMPORTANTE:</font> Si alguno de los tokens no cumple con el formato requerido (40 caracteres alfanuméricos), el servicio retornará el '''código de negocio 111'''. Si las credenciales son incorrectas o inválidas, retornará el '''código de negocio 101'''.

'''Ejemplo de tokens (formato):'''
 tokenEmpresa:  abc123def456ghi789jkl012mno345pqr678stu9
 tokenPassword: xyz987wvu654tsr321qpo098nml765kji432hgf1

----

== Requerimientos técnicos ==

HKA Fácil RIPS es una plataforma tipo '''SaaS (Software as a Service)'''. Los servicios, la información, el procesamiento y los resultados están alojados en los servidores de The Factory HKA Colombia.

Para integrarse con la API, el sistema de facturación o ERP del cliente debe tener:

* Capacidad de consumir '''servicios REST''' con peticiones HTTP/HTTPS tipo <code>POST</code>.
* Capacidad de enviar y recibir cuerpos en formato '''JSON'''.
* Capacidad de capturar y validar los datos de entrada antes del envío.
* Conexión a internet con acceso saliente a los puertos '''TCP 443 (HTTPS)'''.
* Acceso habilitado a los dominios:
** <code>*.thefactoryhka.com.co</code>
** <code>demoapi-facilrips.thefactoryhka.com.co</code> (Integración – Demo)
** <code>api-facilrips.thefactoryhka.com.co</code> (Integración – Producción)

No se requiere infraestructura adicional de procesamiento ni almacenamiento propio, ya que The Factory HKA Colombia se encarga del mantenimiento, operación, cambios normativos y soporte de la solución.

[[Categoría:Manuales]]