Carga por archivos

Cómo se ha indicado en esta sección, el esquema de asegurados/beneficiarios dentro de la plataforma de Osigu es amplia con el objetivo de brindar flexibilidad a los distintos modelos de negocio y configuración de planes y pólizas de un Payer.

Para cada una de las entidades dentro del modelo de datos de Osigu, existe un archivo CSV equivalente que puede ser trasladado y procesado.

El Payer deberá crear cada uno de los archivos que desea cargar y trasladarlos en un zip por le medio determinado en la fase de integración (NFS, SFTP).

Estructura de datos

El siguiente diagrama presenta la estructura de datos y archivos CSV que pueden recibirse. Usualmente no todos los archivos presentados en este diagrama son utilizados o enviados en una integración.

En el diagrama se marcan las estructuras que usualmente son utilizadas en una integración.

El esquema permite que se puedan realizar configuraciones a nivel de póliza o plan, a nivel de grupo o a nivel de beneficiario, es decir que, el Payer puede decidir si los costos compartidos , exclusiones y coberturas deben de ser las mismas para todos los miembros de un plan, para un grupo o únicamente para un beneficiario.

Conexión y traslado

Podrá realizar la carga de los archivos a través del protocolo SFTP sobre la dirección sftp.plans.osigu.com. Osigu le proveerá de un usuario y certificado por ambiente (Uno para producción y otro para sandbox) para poder autenticarse en el servidor de SFTP.

Una vez autenticado, dentro del directorio raíz al que tiene acceso verá la siguiente estructura:

• input, en este directorio deben de colocarse los archivos de carga.
• output, el sistema colocará en este directorio el resultado del procesamiento de carga.

Archivo de carga

Los distintos archivos CSV deben de ser trasladados como un solo archivo empaquetado, en formato zip, gzip o rar sobre el directorio input.

Cada archivo que se traslade al directorio input a través del protocolo SFTP debe de tener un nombre único, de tal forma que el sistema no lo identifique como un archivo ya procesado. Se recomienda que el nombre del archivo tenga la siguiente estructura:

• <código_pais>-<nombre>_<fecha_y_hora>.<zip | gzip | rar>

Por ejemplo:

• us-umbrellacorp-20210110T060001.zip

Una vez concluido el proceso de carga, el proceso colocará un archivo *.log dentro del directorio output, este contiene el resultado del proceso con un detalle por cada archivo de las líneas procesadas con éxito y de las líneas que tuvieron algún error en el procesamiento. Un archivo de log podría verse como en el siguiente ejemplo:

Este archivo de log también se encontrará cómo *.zip y ambos tendrá el mismo nombre que el archivo zip original depositado en el directorio de input.

Procesamiento

El diagrama anterior muestra el flujo de trabajo que sucede cuando se deposita aun archivo *.zip en el directorio input.

Cada vez que se traslada un archivo al directorio de entrada, dentro de la plataforma se emite un evento a la cola de trabajo de Plans API, la cual es la encargada de la gestión de la información de planes y beneficiarios de un Payer.

Esto quiere decir que el sistema detecta cuando un nuevo archivo es depositado y es trabajado de forma inmediata.

Archivos CSV

Dentro del *.zip que se deposite debe de existir al menos un archivo CSV. El proceso no espera que vengan todos los archivos, puede enviar únicamente aquellos sobre los cuales quiera que haya una afectación del registro en la base de datos.

Sin embargo, es usual que se envíen siempre los mismos archivos para evitar que el Payer agregue controles para identificar cambios en la información y determinar qué archivos debe de enviar. Por tal razón, el proceso de Osigu se encargará de verificar por cada línea de un archivo, si la información ha variado desde la última carga para determinar si debe de actualizarse, insertarse o eliminarse.

❗️

Los registros que ya no se encuentren en subsiguientes cargas, serán considerados por el proceso como una baja y dejarán de estar disponibles para futuras autorizaciones.

Requisitos

Los archivos CSV deben de cumplir con los siguientes requisitos:

1. Los archivos deben de estar codificados en UTF-8, de tal forma que caracteres especiales en los campos que contengan algún nombre se muestren correctamente en la plataforma.
2. La primer línea de cada archivo siempre corresponderá a los encabezados.
3. El separador admitido únicamente sera la coma ( , ).
4. Todos los valores que son cadena de texto deben de estar en comillas dobles ( " ), de esta manera una coma puede usarse como separador en campos como dirección, nombres u otros tipos de atributos.
5. Cómo las cadenas de texto están dentro de comillas dobles ( " ), cualquier comilla doble incrustada o incluida como parte del valor de la columna debe de ser escapada mediante una barra invertida.

Procesadores de archivos

Existe en total 27 procesadores, el Payer según el dominio de su información, deberá decidir cuál utilizar, según su conveniencia.

Cómo se indicó al inicio de este documento hay varias configuraciones que pueden realizarse en distintos niveles, el Payer debe de seleccionar la que más le convenga o una combinación de estas. Por ejemplo, las exclusiones de enfermedades pueden realizarse en tres niveles:

• Plan/Póliza, las exclusiones que se agreguen a este nivel afectarán a todos los grupos de la póliza y a todos los beneficiarios de cada grupo.
• Grupo, las exclusiones que se agreguen a este nivel solo afectarán al los beneficiarios que pertenezcan al grupo.
• Beneficiario, las exclusiones que se agreguen a este nivel solo afectarán a un individuo en particular.

Y si el Payer decide configurar exclusiones en los tres niveles, el sistema lo tomará de forma acumulativa, es decir, todas las exclusiones a nivel de Plan/Póliza y de grupo formarán parte de las exclusiones del beneficiario sumadas a aquellas que hayan sido indicadas de forma directa al beneficiario.

De igual forma funcionarán las configuraciones de coberturas y costos compartidos, el Payer tiene la posibilidad de realizar las configuraciones en tres niveles distintos.

A continuación se muestra una tabla con los distintos procesadores disponibles en su segunda versión. Cada uno de estos contiene un enlace que lo dirije al documento con la estructura del archivo correspondiente.

El equipo de Osigu puede asesorarle a encontrar la mejor combinación de archivos a enviar según su modelo de datos y necesidades.

Tipo de datos

Los tipos de datos utilizados en los distintos archivo son los siguientes:

String

Cadena de texto, estos valores deben de aparecer entre comillas dobles ( " ) dentro del CSV. Los campos con este tipo indican entre corchetes ( [ ] ) la cantidad máxima de caracteres que son aceptados.

Timestamp

Esta es una cadena de texto que representa una fecha y hora en formato ISO 8601 en su forma extendida, de esta forma puede indicar la zona horaria en que esta trabajando las fechas en su sistema.

Es importante que indique para cada fecha la zona horaria en la que se esta trabajando, de tal manera que la plataforma pueda luego hacer uso de este dato y dar la representación exacta según la zona horaria en que trabaje el Payer.

Los siguientes ejemplos muestran como se podría enviar la fecha 2022-01-01 a las 0 horas para la zona horaria GMT-06:

• "2022-01-01T06:00:00.000Z", UTC.
• "2022-01-01T00:00:00.000-06:00", para la región de America/Central.
• "2022-01-01T04:00:00.000+02:00", para la región de Europe/Spain.

Note que los valores están encerrados entre comillas dobles ( " ), pues estos primero serán tratados como String, para luego verificar formato y convertirlo finalmente en el tipo de dato correspondiente.

Enum

Este es un tipo de dato String, por lo tanto también debe de ir encerrado entre comillas dobles ( " ). Pero en este caso la guía no indicará la longitud máxima, sino que los valores aceptados por el campo.

Los valores aceptados por el campo de tipo Enum estarán entre paréntesis y separados por el caracter pleca o como se conoce en inglés, pipe ( | ).

Por ejemplo, para el campo sex estará definido por un enum de la siguiente manera:

• Enum ( MALE | FEMALE | NOT_KNOWN )

Lo que quiere decir que el campo podrá tener uno de dichos valores y este valor deberá ser encerrado entre comillas dobles, como por ejemplo:

• "NOT_KNOWN".

Boolean

Este es un valor que debe de ir encerrado entre comillas dobles ( " ). Los campos de este tipo solo pueden tener uno de los siguientes valores.

• "true"
• "false"

Integer

Este tipo de dato representa un valor numérico de tipo entero, y
debe de ir encerrado también entre comillas dobles. Tampoco podrá incluir decimales y el rango de admitidos estan entre -2,147,483,648 y +2,147,483,647.

Dependiendo de la naturaleza del campo, es posible que algunos campos tengan alguna validación, como aceptar valores mayores o igual a un número por dar un ejemplo.

Cuando no cuente con un valor que es requerido por la estructura de uno de los archivos, se recomienda mandar el valor cero ( 0 ).

Decimal

Este tipo de dato representa un valor numérico decimal, este tipo de dato tendrá especificado la presión y la escala, de la siguiente forma: Decimal(<presición>, <escala>).

La presión indica la cantidad máxima de dígitos que puede ser admitido y la escala la cantidad de digitos que puede ir en la fracción del número.

Por ejemplo, para la siguiente definción de campo Decimal(15,5) los siguientes valores serían válidos:

• 0987654321.12345, El número tiene 15 dígitos en total de los cuales 5 corresponden a la fracción.
• 210987654321.123, De igual forma este número contiene 15 dígitos en total, 3 de ellos pertenecen a la fracción.

🚧

¿Qué pasa si un número excede la precisión?

Si el número contiene fracción, el sistema truncará la parte fraccionaria, por ejemplo:

El número 3210987654321.555888 sería almacenado como 3210987654321.55.

Si el número no contiene fracción la línea y campo quedarán marcados con error y podrá ver el mensaje de error dentro del resultado del proceso.

Dependiendo de la naturaleza del campo, es posible que algunos campos tengan alguna validación, como aceptar valores mayores o igual a un número por dar un ejemplo.

Cuando no cuente con un valor que es requerido por la estructura de uno de los archivos, se recomienda mandar el valor cero ( 0 ).

Este tipo de dato también deberá ir dentro de comillas dobles ( " ).