cs-arl-xapi
home
🛡️ cs-arl-xapi
Esta API proporciona servicios integrales para la gestión de trabajadores, dependientes y autorizaciones médicas en el sistema ARL. Incluye endpoints para:
- Gestión completa de trabajadores dependientes y su información laboral
- Consulta de datos de trabajadores y dependientes activos
- Registro y retiro de trabajadores del sistema
- Autorizaciones médicas y seguimiento sanitario
- Consulta de información geográfica (departamentos, ciudades, IPS)
- Consulta de sedes empresariales y datos de afiliación
- Consulta de usuarios integrados con Azure B2C
- Registro de auditorías y trazabilidad de operaciones
Todos los servicios están diseñados para integrarse con sistemas APOLO SAPI, SENDA SAPI y servicios de autenticación empresarial, proporcionando acceso seguro y trazable a datos críticos de Riesgos Laborales.
🌐 Información Base
- Título de la API: cs-arl-xapi
- Versión: 1.0.0
- Plataforma: MuleSoft Anypoint Platform
- URL Base Dev:
https://cs-arl-xapi-v1-dev.us-e1.cloudhub.io/api/ - URL Base QA:
https://cs-arl-xapi-v1-qa.us-e1.cloudhub.io/api/ - Protocolo: HTTPS/REST
- Formato de Datos: JSON
- Autenticación: OAuth 2.0 + Client ID Enforcement
🚀 Cómo Comenzar
- Autenticación: Asegúrate de tener el
client_idrequerido y el token BearerOAuth 2.0para acceso seguro. - URL Base: Usa la URL Base proporcionada como prefijo para todos los endpoints de la API.
- Encabezados: Agrega los siguientes encabezados en tus solicitudes de API:
-H "Content-Type: application/json"
-H "client_id: TU_CLIENT_ID"
-H "Authorization: Bearer TU_ACCESS_TOKEN"
-H "invoker: {\"application\":\"TU_APP\",\"addressIPUser\":\"IP\",\"loginUser\":\"USER\",\"userName\":\"NAME\"}"🚀 Cómo Consumir
Puedes acceder y consumir esta API a través de las siguientes plataformas:
📍 Endpoints Disponibles
| Método | Endpoint | Descripción |
|---|---|---|
| POST | /create-dependent-worker | Crear trabajador dependiente con información completa laboral y personal |
| POST | /retired-dependent-workers-cancelled | Obtener reporte PDF de trabajadores dependientes retirados o cancelados |
| GET | /workers/dependent/data | Consultar datos completos de trabajadores dependientes activos |
| GET | /companies/headquarters/{contractConsecutive} | Consultar información de sedes de empresa por contrato |
| GET | /obtain-departments | Listar todos los departamentos disponibles en el sistema |
| GET | /cities | Consultar ciudades disponibles filtradas por departamento |
| GET | /ips-location | Obtener ubicación geográfica de IPS (Instituciones Prestadoras de Salud) |
| POST | /authorization/medical-authorizations | Crear autorización médica para trabajadores con validaciones de cobertura |
⚠️ Manejo de Errores
Se utilizan códigos de estado HTTP estándar para el manejo de errores:
📊 Códigos de Respuesta
| Código | Estado | Descripción | Causa Común | Acción Recomendada |
|---|---|---|---|---|
200 | ✅ OK | La solicitud fue exitosa | Operación completada correctamente | Continuar con el procesamiento |
400 | ❌ Bad Request | Parámetros faltantes o inválidos | Formato de datos incorrecto | Revisar estructura del JSON y campos requeridos |
401 | 🔒 Unauthorized | Autenticación fallida | Token expirado o client_id inválido | Renovar token de autenticación |
403 | 🚫 Forbidden | Sin permisos suficientes | Client_id sin permisos para el endpoint | Verificar permisos asignados al client_id |
404 | 🔍 Not Found | Endpoint o recurso no encontrado | URL incorrecta o recurso inexistente | Verificar la URL y documentación |
405 | 🚷 Method Not Allowed | Método HTTP no permitido | Usar POST en lugar de GET o viceversa | Verificar el método HTTP correcto |
406 | ⚠️ Not Acceptable | Formato de respuesta no aceptable | Headers Accept incorrectos | Agregar "Accept: application/json" |
415 | 📝 Unsupported Media Type | Tipo de contenido no soportado | Content-Type incorrecto | Usar "Content-Type: application/json" |
429 | ⏰ Rate Limited | Demasiadas solicitudes | Exceso de requests por minuto | Implementar retry con exponential backoff |
500 | 💥 Internal Server Error | Error inesperado en el servidor | Fallo interno del sistema | Contactar soporte técnico con correlationId |
501 | 🛠️ Not Implemented | Funcionalidad no implementada | Endpoint en desarrollo | Verificar documentación actualizada |
503 | 🔧 Service Unavailable | Servicio temporalmente no disponible | Mantenimiento o sobrecarga | Reintentar más tarde |
❓ Preguntas Frecuentes
🔑 Error 401 - Unauthorized
- Síntomas: Respuesta "Authentication failed" o "Invalid credentials"
- Causas: Token OAuth expirado, client_id incorrecto, headers malformados
- Solución: Verificar y renovar credenciales OAuth, validar formato de headers, confirmar client_id activo
📋 Error 400 - Bad Request con campos faltantes
- Síntomas: "Missing required field" o "Invalid data format"
- Causas: Campos obligatorios omitidos, formato de fecha incorrecto, tipos de datos inválidos
- Solución: Revisar documentación de campos requeridos, validar formatos de fecha (ISO 8601), verificar tipos de datos
⏰ Error 504 - Gateway Timeout
- Síntomas: Timeout después de 30 segundos sin respuesta
- Causas: Servicios APOLO/SENDA lentos, sobrecarga del sistema, queries complejas
- Solución: Implementar timeouts más cortos (15-20s), usar retry con backoff, contactar soporte
📊 Error 429 - Rate Limiting
- Síntomas: "Too Many Requests" o "Rate limit exceeded"
- Causas: Exceso de requests por minuto (límite: 100/min por client_id)
- Solución: Implementar queue con rate limiting, espaciar requests, considerar caché local
🔍 Error 404 - Not Found en recursos
- Síntomas: "Resource not found" al consultar trabajadores o contratos
- Causas: IDs inexistentes, trabajador dado de baja, contrato inactivo
- Solución: Validar existencia de IDs antes de consultar, verificar estado del recurso
📞 Soporte
Para asistencia técnica, contacta al equipo de Coordinación de Servicios de Integración y Aplicaciones.
Correo electrónico: epalma@fgs.co
📅 Información Adicional
Documentación creada y actualizada en Noviembre 2025 por epalma@fgs.co - Edna Nayibe Palma
© 2025 Fundación Grupo Social - Colmena. Archivo generado para la API cs-arl-xapi
📋 Nota Importante: Esta documentación se actualiza continuamente. Para la versión más reciente y cambios en tiempo real, consulta siempre el Portal de Exchange oficial.
🔒 Aviso de Seguridad: Nunca compartas credenciales de API en repositorios públicos o documentación. Usa siempre variables de entorno para información sensible y rota tokens regularmente.
⚡ Rendimiento: Esta API está optimizada para alta disponibilidad con workers configurados en CloudHub. Tiempos de respuesta típicos: 200-800ms dependiendo de la complejidad de la consulta.