cs-beyond-health-sapi
🛡️ cs-beyond-health-sapi
La API cs-beyond-health-sapi provee una solución integral para la integración directa con el sistema Beyond Health, permitiendo la consulta y gestión de información relacionada con contratos, afiliados, prestadores, órdenes médicas y documentos certificados.
Expone operaciones REST para:
- Consulta y gestión de contratos, facturas, estados de cuenta y tarifas de pólizas
- Inclusión y retiro de titulares y beneficiarios en pólizas colectivas e individuales
- Carga masiva de titulares y beneficiarios
- Consulta de información de clientes/afiliados y actualización de datos de contacto
- Consulta del directorio médico y sucursales de prestadores
- Consulta de catálogos paramétricos del core de Beyond Health
- Consulta de planes, productos, coberturas, beneficios y topes
- Creación y consulta de órdenes médicas, adjuntos y documentos asociados
- Generación de certificaciones tributarias, de afiliación y de preexistencias
- Consulta y descarga de documentos médicos
La API actúa como una System API (SAPI), gestionada desde MuleSoft Anypoint Platform.
🌐 Información Básica
- Nombre de la API: cs-beyond-health-sapi
- Versión: 1
- Plataforma: MuleSoft Anypoint Platform
- Tipo: System API
- URL Base QA:
https://cs-beyond-health-sapi-qa-v1.us-e1.cloudhub.io/api/ - URL Base Producción:
https://cs-beyond-health-sapi-prod-v1.us-e1.cloudhub.io/api/ - Protocolo: HTTPS / REST
- Formato de Datos: JSON / multipart/form-data (según endpoint)
🔐 Autenticación
Para consumir esta API, el consumidor debe enviar obligatoriamente en cada solicitud los siguientes mecanismos de seguridad:
Client ID Enforcement
Headers requeridos:
client_idclient_secret
- Las credenciales son asignadas a la aplicación consumidora en MuleSoft Anypoint Platform.
Bearer Token (OAuth 2.0)
Header requerido:
Authorization: Bearer <access_token>
- El token debe ser obtenido desde el servicio corporativo de autenticación.
- El token debe estar vigente al momento de la solicitud.
Ambos mecanismos son requeridos para que la solicitud sea aceptada por la plataforma.
Adicionalmente, varios endpoints requieren headers propios de trazabilidad de negocio, como
TransactionId/transactionIdyClientDt/clientDt, según se detalla en la documentación individual de cada método.
🔒 Aviso de Seguridad
Las credenciales (client_id,client_secret) y los tokens OAuth son información sensible y no deben compartirse ni almacenarse en repositorios públicos.
🚀 Cómo Consumir
La API se encuentra publicada en las siguientes plataformas:
- 🔗 MuleSoft Exchange – cs-beyond-health-sapi https://anypoint.mulesoft.com/exchange/portals/fundacion-grupo-social/
- 🔗 Portal Público FGS https://anypoint.mulesoft.com/exchange/portals/fundacion-grupo-social/
📋 Para consultar detalles de cada método:
1. Navegar en el menú izquierdo de la documentación
2. Expandir la sección "Summary"
3. Seleccionar el método específico que requiere consultar
📍 Endpoints Disponibles
| Método | Endpoint | Descripción |
|---|---|---|
| POST | /contracts/members | Consultar contratos asociados (tomador, titular o beneficiario) |
| GET | /contracts/invoices | Consultar facturas de una póliza |
| GET | /contracts/account-statement | Consultar el estado de cuenta de un contrato de póliza |
| GET | /contracts/{consultId}/collective-families | Consultar información de asegurados de un contrato |
| POST | /contracts/bulk-families | Carga masiva de titulares y beneficiarios a una póliza colectiva PV |
| POST | /contracts/holders | Incluir titulares a una póliza colectiva PV |
| POST | /contracts/holders/cancellation | Retirar un titular de una póliza colectiva PV por desvinculación laboral |
| POST | /contracts/payments | Aplicar pago a factura, saldo de contrato o inclusiones de medicina prepagada |
| POST | /contracts/rates | Consultar una póliza junto con sus tarifas asociadas |
| PUT | /contracts/beneficiaries/designated | Permite actualizar o agregar beneficiarios designados en una póliza |
| POST | /providers/{consultId}/medical-staff | Consultar el directorio médico de Beyond Health |
| POST | /providers/branches/search | Consultar sucursales de prestadores por código de tipo de servicio |
| GET | /parametrics/{parametricType} | Consultar catálogos existentes en el core de Beyond Health |
| GET | /customer/contacts | Consultar información del cliente |
| PATCH | /customer/contacts/information | Actualizar información básica de contacto del cliente |
| GET | /customer/{queryType}/basic-data | Consultar información básica del cliente |
| POST | /family/beneficiaries | Incluir beneficiarios a una póliza colectiva o individual PV |
| GET | /products | Consultar información general de un plan (coberturas, beneficios, topes) |
| GET | /plans/coverage | Consultar la cobertura de planes y productos disponibles |
| PATCH | /contacts/information | Actualizar información básica de contacto |
| POST | /service-requests/medical-orders | Crear una orden médica asociada a un paciente y contrato |
| POST | /service-requests/medical-orders/search | Consultar órdenes médicas de un paciente y su contrato |
| POST | /service-requests/medical-attachments | Adjuntar documento a una orden médica |
| POST | /documents/tax-certification | Generar la certificación tributaria de un afiliado |
| POST | /documents/membership-certification | Generar la certificación de afiliación de un usuario |
| POST | /documents/preexistence-certification | Generar la certificación de preexistencias de un usuario |
| POST | /documents/medical-document-list/search | Consultar metadata de documento (OM-HM-ETC) |
| GET | /documents/medical-document | Descargar resultados médicos |
⚠️ Manejo de Errores
La API utiliza códigos HTTP estándar para indicar el resultado del procesamiento de las solicitudes.
Estos códigos representan condiciones de autenticación, autorización, formato o disponibilidad del servicio, y no validaciones funcionales propias del negocio.
| Código | Estado | Descripción |
|---|---|---|
| 200 | OK | Solicitud procesada correctamente |
| 202 | Accepted | Solicitud aceptada para procesamiento asíncrono |
| 400 | Bad Request | Solicitud inválida o mal formada |
| 401 | Unauthorized | Credenciales inválidas o ausentes |
| 403 | Forbidden | Client ID sin permisos |
| 404 | Not Found | Recurso no encontrado |
| 405 | Method Not Allowed | Método HTTP no permitido |
| 415 | Unsupported Media Type | Tipo de contenido no soportado |
| 429 | Too Many Requests | Límite de solicitudes excedido |
| 500 | Internal Server Error | Error interno inesperado |
| 503 | Service Unavailable | Servicio temporalmente no disponible |
| 504 | Gateway Timeout | Tiempo de espera agotado |
📞 Soporte
Para soporte técnico o incidencias relacionadas con la integración:
Coordinación de Servicios de Integración y Aplicaciones
📅 Información Adicional
Documentación creada en Julio 2026 – Fundación Grupo Social – Colmena
epalma@fgs.co
© 2026 Fundación Grupo Social – Colmena
Esta documentación se mantiene actualizada conforme se incorporan nuevos servicios o endpoints relacionados con la integración a Beyond Health.