cs-arl-xapi

🛡️cs-arl-xapi

Esta API funciona como capa de experiencia (xapi) proporcionando acceso integral a los servicios de ARL Colmena. Expone métodos esenciales para gestión de trabajadores y consulta de datos de referencia:

Operaciones Principales:

• Ingreso de Trabajadores (Crear Trabajador Dependiente)
• Retiro de Trabajadores (Trabajadores Dependientes Retirados)

Servicios de Datos de Referencia:

• Ciudades (Catálogo de Ciudades por Departamento)
• Departamentos (Divisiones Administrativas de Colombia)
• Sedes (Información de Sedes de Empresa)

Como capa de experiencia, esta API es el único punto de entrada autorizado para entidades externas que requieren acceso al sistema ARL Colmena.

🎯 Objetivo

Proveer información técnica completa y detallada para facilitar la integración exitosa con la API cs-ARL-xapi, proporcionando:

• Guía paso a paso para la implementación de los servicios
• Documentación técnica detallada de cada endpoint disponible
• Ejemplos prácticos de uso y casos de implementación
• Especificaciones de seguridad y autenticación
• Códigos de respuesta y manejo de errores
• Tablas de referencia para una implementación correcta

Este manual está dirigido a desarrolladores y equipos técnicos que necesiten integrar sus sistemas con la plataforma ARL de Colmena para la gestión de trabajadores dependientes.

🌐 Información Base

• Título de la API: cs-ARL-xapi
• Versión: 1.0.0
• URL Base: https://cs-ARL-xapi-v1-{env}.us-e1.cloudhub.io/api/
• Opciones de Ambiente: dev, qa

🏗️ Arquitectura

La API cs-ARL-xapi es un servicio web que funciona como capa de experiencia (xapi) para el sistema de la ARL de Colmena. Esta API proporciona acceso controlado y seguro a las funcionalidades principales de gestión de trabajadores dependientes, sirviendo como único punto de entrada para entidades externas que requieren integración con el sistema ARL.

El sistema procesa las solicitudes de las empresas a través de endpoints seguros, valida los contratos, genera trazabilidad de auditoría y devuelve resultados verificados mediante hash. La autenticación por token utiliza cifrado SHA-256 con parámetros del contrato y de la operación del usuario.

🚀 Comenzando

Requisitos Previos

1. Credenciales de Connected App (proporcionadas por el equipo de Colmena durante el onboarding):

   • client_id de Connected App
   • client_secret de Connected App

2. Credenciales de Aplicación (obtenidas en Anypoint Platform):

   • client_id de Aplicación
   • client_secret de Aplicación

⚠️ IMPORTANTE: Las credenciales de Connected App son diferentes a las credenciales de Aplicación. Usar credenciales incorrectas resultará en error "invalid client".

Headers Obligatorios

Todas las solicitudes deben incluir el siguiente header:

"invoker": {
  "application": "Portal",
  "addressIPUser": "192.168.80.13",
  "loginUser": "User",
  "userName": "User Name"
}

🔐 Autenticación

La API cs-arl-xapi utiliza autenticación OAuth 2.0 para garantizar la seguridad de las comunicaciones. Este proceso de autenticación es obligatorio para todos los endpoints disponibles.

Paso 1: Configuración del Entorno

Determinar el entorno a utilizar y construir la URL base:

• Desarrollo: https://authentication-services-colmena-dev.us-e1.cloudhub.io/
• Control de Calidad: https://authentication-services-colmena-qa.us-e1.cloudhub.io/
• Producción: https://authentication-services-colmena-prod.us-e1.cloudhub.io/

Paso 2: Solicitud del Token

Realizar una petición POST al endpoint /token:

URL completa: https://authentication-services-colmena-{env}.us-e1.cloudhub.io/token

Método HTTP: POST

Headers requeridos:

• client_id: [TU_CLIENT_ID_DE_CONNECTED_APP]
• client_secret: [TU_CLIENT_SECRET_DE_CONNECTED_APP]
• grant_type: CLIENT_CREDENTIALS

Ejemplo de solicitud:

curl -X POST "https://authentication-services-colmena-dev.us-e1.cloudhub.io/token" \
-H "client_id: TU_CLIENT_ID_DE_CONNECTED_APP" \
-H "client_secret: TU_CLIENT_SECRET_DE_CONNECTED_APP" \
-H "grant_type: CLIENT_CREDENTIALS"

Paso 3: Recepción del Token

La respuesta exitosa contendrá:

• access_token: Token de acceso tipo Bearer
• token_type: Tipo de token (Bearer)
• expires_in: Tiempo de expiración en segundos (3600 = 1 hora)

Paso 4: Uso del Token

Para realizar llamadas a la API cs-arl-xapi, incluir los siguientes headers:

• client_id: [TU_CLIENT_ID_DE_APLICACIÓN]
• client_secret: [TU_CLIENT_SECRET_DE_APLICACIÓN]
• Authorization: Bearer [TU_ACCESS_TOKEN]

Control de Excepciones

Token Expirado (401)

Cuando se envía un access_token vencido, solicitar un nuevo token utilizando las credenciales originales.

Token Inválido (401)

Cuando se envía un access_token inválido o malformado, verificar las credenciales y solicitar un nuevo token.

Mejores Prácticas de Seguridad

• El token tiene una duración de 1 hora (3600 segundos)
• Guardar el token de forma segura para reutilizarlo durante su periodo de validez
• NUNCA hardcodear el client_secret en el código fuente
• Almacenar tokens de forma segura (variables de entorno, vault)
• Implementar renovación automática de tokens antes del vencimiento
• Usar HTTPS exclusivamente para todas las comunicaciones

📲 Cómo Consumir

Puedes acceder y consumir esta API a través de las siguientes plataformas:

• 🔗 MuleSoft Exchange (ARL API)
• 🔗 Portal Público

📍 Endpoints Disponibles

Operaciones de Gestión de Trabajadores

Servicios de Consulta de Catálogos y Datos de Referencia

📤 Ejemplos de Solicitudes

Gestión de Trabajadores (POST)

curl -X POST "https://cs-ARL-xapi-v1-dev.us-e1.cloudhub.io/api/create-dependent-worker" \
-H "client_id: TU_CLIENT_ID" \
-H "Authorization: Bearer TU_TOKEN_OAUTH2" \
-H "invoker: { \"application\": \"Portal\", \"addressIPUser\": \"192.168.80.13\", \"loginUser\": \"User\", \"userName\": \"User Name\" }" \
-H "Content-Type: application/json" \
-d '{
  "requestData": {
    "tus_parametros_de_solicitud": "aqui"
  }
}'

Consulta de Datos de Referencia (GET)

curl -X GET "https://cs-ARL-xapi-v1-dev.us-e1.cloudhub.io/api/Departments" \
-H "client_id: TU_CLIENT_ID" \
-H "Authorization: Bearer TU_TOKEN_OAUTH2" \
-H "invoker: { \"application\": \"Portal\", \"addressIPUser\": \"192.168.80.13\", \"loginUser\": \"User\", \"userName\": \"User Name\" }" \
-H "Content-Type: application/json"

🔄 Flujo de Integración Recomendado

1. Inicializar Datos de Referencia: Comience llamando endpoints de referencia (Departments, Cities, Headquarters) para poblar los catálogos de su aplicación
2. Configuración de Empresa: Use /Headquarters para obtener información de sedes de la empresa
3. Operaciones de Trabajadores: Use /create-dependent-worker para nuevos registros de trabajadores
4. Procesamiento de Retiros: Use /retired-dependent-workers-cancelled para operaciones de retiro de trabajadores

🔄 Flujo de Integración Recomendado

1. Inicializar Datos de Referencia: Comience llamando endpoints de referencia (Departments, Cities, Headquarters) para poblar los catálogos de su aplicación
2. Configuración de Empresa: Use /Headquarters para obtener información de sedes de la empresa
3. Operaciones de Trabajadores: Use /create-dependent-worker para nuevos registros de trabajadores
4. Procesamiento de Retiros: Use /retired-dependent-workers-cancelled para operaciones de retiro de trabajadores

📋 Nota Importante - Consecutivo de Contrato

ℹ️ Información Clave:
El campo consecutiveContract corresponde al número consecutivo del contrato asignado por el sistema ARP. Este valor específico es informado oficialmente en la carta de instrucciones que la empresa recibe al momento de la afiliación o contratación de servicios.
Recomendaciones:
- Consulte la carta de instrucciones oficial de su empresa para obtener el número consecutivo correcto
- Este valor es único por contrato y debe ser conservado para todas las operaciones relacionadas
- En caso de no contar con la carta de instrucciones, utilice el endpoint GET /company para obtener el consecutivo mediante la identificación de la empresa
Ubicación del dato: Documento oficial de afiliación → Carta de instrucciones → Número consecutivo de contrato

⚠️ Manejo de Errores

Se devuelven códigos de estado HTTP estándar:

• 200 OK – Operación exitosa
• 400 Bad Request – Parámetros inválidos o faltantes
• 401 Unauthorized – Token expirado o inválido
• 404 Not Found – Recurso no existe
• 500 Internal Server Error – Problema interno del servidor

📊 Validaciones Automáticas

Validaciones de Sintaxis y Formato

• Fechas válidas: Formato ISO 8601 (YYYY-MM-DD o YYYY-MM-DDTHH:MM:SS)
• Correo electrónico: Formato válido usuario@dominio.com
• Números de identificación: Solo caracteres numéricos
• Números de teléfono: Solo dígitos, mínimo 7 y máximo 15 caracteres

Validaciones de Reglas de Negocio

• Identificación obligatoria: Los campos identification e identificationType son obligatorios
• Validación del hash: Debe corresponder con contractId + workerId + tipoTransacción + fechaTransacción cifrada en SHA256
• Aseguradoras válidas: Los objetos afp, eps, contractType, etc. deben contener códigos válidos
• Consistencia de fechas: Las fechas deben seguir un orden lógico temporal
• Salario básico: Debe ser positivo y mayor al salario mínimo legal vigente

📞 Soporte

Para soporte técnico, contactar:

Coordinación de Servicios de Integración y Aplicaciones

📧 epalma@fgs.co

📅 Notas

• Documentación última actualización: Junio 2025
• Versión de la API: 1.0.0 (incluye servicios expandidos de datos de referencia)
• Para actualizaciones futuras, visite el Portal API Exchange
• Todos los endpoints de datos de referencia requieren la misma autenticación y headers que las operaciones transaccionales

📋 Consideraciones Generales y Reglas de Uso

• Este manual es confidencial y de uso exclusivo para clientes autorizados de Colmena
• Las URLs, códigos y estructuras pueden actualizarse sin previo aviso
• Se recomienda implementar manejo robusto de errores y retry logic
• Todos los requests y responses son auditados por el sistema Colmena
• El incumplimiento de las especificaciones puede resultar en bloqueo de acceso

💡 Nota: Esta API proporciona tanto operaciones transaccionales (gestión de trabajadores) como servicios de datos de referencia (catálogos de ciudades, departamentos y sedes) para soportar flujos de integración completos para consumidores externos.