EHR
Guía de integración con nuestra aplicación de EHR
En esta guía encontrarás cómo puedes realizar la integración con nuestra aplicación de EHR, permitiendo la suscripción de Doctores, acceso y sincronización de pacientes.
Para la integración con nuestra plataforma deberás de utilizar y proveer lo siguiente:
- Utilización de nuestro auth-service para la obtención de un access token.
- Implementación de nuestro widget para la suscripción de doctores.
- Uso de nuestro endpoint para registro de pacientes.
- Poder realizar una re-dirección desde tu aplicación WEB a nuestro EHR.
- Debes de proporcionar a Osigu un servicio REST que podamos utilizar para registrar de regreso un paciente creado desde nuestro EHR.
En esta integración existen cuatro puntos de integración en donde haremos uso de cada uno de los puntos mencionados antes.
1. Suscripción de doctores
Para la suscripción de doctores contamos con un widget que puedes implementar en tu sitio WEB (third-party JavaScript), este widget creará dentro de tu sitio un formulario para que el doctor complete cierta información requerida para la creación de su perfil.
La implementación del widget requiere de 2 pasos únicamente:
1.1 Implementación de nuestro JS, que contiene el código html, JavaScript y estilos en un solo paquete, necesarios para el despliegue de nuestro formulario que incluye también el consumo de nuestros servicios REST para el registro del mismo.
1.2 Creación del componente DoctorEnrollmentWidget, el cual requerirá el envío de cierta información del doctor, para que el usuario complete únicamente la información adicional que requerimos.
Implementación de JS
Para la implementación de nuestro JS debes únicamente agregar nuestro script a tu página, como puedes ver en el siguiente ejemplo.
<HTML>
<HEAD>
</HEAD>
<BODY>
<script type="text/javascript"
src="https://doctorenrollment.widgets.osigu.com/sandbox/1.1.1/widget.js">
</script>
</BODY>
</HTML>
Ambientes
El ejemplo muestra la implementación de nuestro widget, en él puedes observar que se esta realizando la implementación de la versión 0.1.0 del ambiente de sandbox. Nuestro ambiente de sandbox es utilizado para desarrollo y pruebas de integración con nuestros clientes.
Contamos con dos ambientes:
- sandbox, como se ha mencionado antes, este ambiente es utilizado con nuestros clientes para desarrollo y pruebas de integración.
- production, este ambiente es el que debe ser utilizado por tus aplicaciones una vez la integración haya sido probada, certificada y puesta en producción en tu ambiente productivo.
Atención
La comunicación con nuestros servicios WEB y widgets requieren de la implementación de mecanismos de autenticación realizada a través de nuestro OAuth2 server. Para esto te proporcionaremos las credenciales correspondientes para cada ambiente.
Versiones
Debes de realizar la implementación de nuestros widgets utilizando la última versión de los mismos. En el ejemplo 1.1 vemos que el script hace referencia a la versión 0.1.0 de nuestro componente.
Cada vez que liberemos una nueva versión que incluya un cambio ya sea mayor, menor o que incluya correción de errores estaremos notificando estos cambios por las vías de comunicación definidas con nuestros clientes, además agregamos en nuestra sección de noticias de este sitio un comunicado que indica la liberación de la nueva versión y los cambios que incluye la nueva versión liberada.
Cuando una nueva versión es liberada, se realiza para los dos ambientes, sandbox y production.
Instancia del componente
Cuando desees que nuestro formulario sea mostrado en tu sitio debes de crear la instancia de nuestro componente a través de JavaScript. Para esto debes de proporcionarnos los siguientes parámetros:
| Nombre | Tipo | Descripción | Req |
|---|---|---|---|
| containerId | String | Este es el ID de la tag de HTML donde deseas que sea cargado el widget. | Si |
| clientId | String | Este es el ID que se proporciona a cada cliente que integra nuestros widget. Este es un valor distinto por ambiente. | Si |
| clientSecret | String | Acompañado con cada clientID entregamos un llave llamada clientSecret, y con ambas llaves generamos un token de autorización. De igual forma este es un valor distinto por ambiente. | Si |
| locale | String | Esto sirve para desplegar los widgets en el idioma correspondiente hasta especificar el país, ejemplo: ´es´, ´en´ | Si |
| primaryColor | String | Código de color hexadecimal, para ser utilizado como color primario. | No |
| secondaryColor | String | Código de color hexadecimal, para ser utilizado como color secundario. | No |
| errorColor | String | Código de color hexadecimal, para ser utilizado para despliegue de errores. | No |
| doctor | Object | Este objeto contiene la información del doctor necesaria para que pueda crearse el perfil de nuestro lado y que documentos como la receta electrónica se visualicen de manera correcta. | Si |
| doctor.givenName | String | Primer nombre del especialista médico. | Si |
| doctor.middleName | String | Segundo nombre del especialista. | No |
| doctor.firstSurname | String | Apellido del especialista médico. | Si |
| doctor.secondSurname | String | Segundo apellido del médico. | No |
| doctor.countryCode | String | País en que practica el especialista. ISO 3166-1 alpha-2 | Si |
| doctor.emailAddress | String | Correo electrónico del doctor. | Si |
| doctor.sex | String (Enum) | Sexo del doctor. los valores admitivos son, FEMALE o MALE. | No |
| doctor.salutation | String | Saludo del especialista, por ejemplo: Dr. o Dra. | Si |
| doctor.medicalLicenseNumber | String | Número de licencia médica, también es conocido como cédula profesional o colegiado. | Si |
| doctor.issuingInstitution | String | Institución en donde fue obtenido el grado. | No |
| doctor.taxIdentificationNumber | String | Número de contribuyente fiscal. | Si |
| doctor.address | String | Dirección del doctor, esta dirección será visualizada en la receta que se genere. | Si |
| doctor.phoneNumber | String | Número de teléfono del doctor, esta información también se visualizará en la receta generada. | Si |
| doctor.cellPhoneNumber | String | Número de teléfono móvil del doctor, esta información también se visualizará en la receta generada. | No |
| doctor.timeZone | String | Zona horaria del Doctor, por ejemplo: America/Guatemala o Europe/Madrid. | Si |
| doctor.specialties | String | Arreglo de objetos que contiene información adicional de las especialidades del doctor. La primer especialidad que vaya indicada en este arreglo se tomará como especialidad principal. | No |
| doctor.specialties[].name | String | Nombre de la especialidad. | Si |
| doctor.specialties[].issuingInstitution | String | En algunos países es necesario saber la institución en donde fue obtenido la especialidad médica. | No |
| doctor.specialties[].licenseNumber | String | En algunos países es necesario saber la institución en donde fue obtenido la especialidad médica. | No |
Información
Para la creación de la instancia del widget puedes enviar tres colores hexadecimales de forma opcional, esto con el objetivo de que el formulario de registro se visualice utilizando los colores de tu marca. Si no proporcionas estos valores, no pasa nada, nuestro formulario se desplegará utilizando los valores que hemos definido por defecto.
El ejemplo 1.2 muestra la manera en que debe de crearse la instancia de nuestro widget. Al ejecutarse el código de JavaScript provocará que nuevas etiquetas de html correspondientes a nuestro formulario sea desplegado dentro de la etiqueta que hayas definido en la propiedad llamada containerId.
<HTML>
<HEAD>
</HEAD>
<BODY>
<script type="text/javascript"
src="https://doctorenrollment.widgets.osigu.com/sandbox/1.1.1/widget.js">
</script>
<noscript>
<strong>Lo sentimos pero este sitio no trabaja apropiadamente sin
JavaScript. Por favor habilitelo para continuar.</strong>
<div id="widget_container"></div>
<script>
DoctorEnrollmentWidget.createWidget({
containerId: "widget_container",
primaryColor: "#2fa6ff",
errorColor: "#ee6f6f",
clientId: "gt-test-third-party-application-slug",
clientSecret: "9a1b783b-a5d5-4194-8d10-ba15906e3bb0",
locale: 'es',
doctor: {
givenName: 'Juan',
middleName: 'Francisco',
firstSurname: 'Bassi',
secondSurname: 'López',
countryCode: 'GT',
emailAddress: '[email protected]',
sex: 'MALE',
salutation: 'Dr.',
medicalLicenseNumber: '2012-468',
issuingInstitution: 'Universidad Francisco Marroquin',
taxIdentificationNumber: '64578-K',
address: 'Ruta 2, 4-71 Zona 4, Cuatro Venezia',
phoneNumber: '(502) 4578-6581',
cellPhoneNumber: '+502 49290808',
timeZone: 'America/Guatemala',
specialties: [{
name: 'Ginecología y Obstetricia',
licenseNumber: '2016-547',
issuingInstitution: 'Universidad de San Carlos de Guatemala'
}]
}
});
</script>
</noscript>
</BODY>
</HTML>
De parte de nuestro widget, las siguientes tareas serán realizadas.
- Validación de credenciales según los valores de los atributos llamados
clientIdyclientSecret. - Verificación de registro según licencia médica (cédula profesional/colegiado) y código de país.
- Despliegue de formulario de registro o mensaje de estado de registro.
Doctor no registrado
Dependiendo si el doctor aún no se encuentra registrado dentro de la plataforma Osigu, veremos que el Widget mostrá un formulario como se ve a continuación:
En él se le pide una contraseña y confirmación de la misma, esta contraseña es utilizada para la firma electrónica y además para poder crearle un usuario y acceder más adelante al EHR.
También tiene la posibilidad de generar una imagen con su firma manuscrita, esta firma será incluída dentro de la receta. Esto es opcional.
Al guardar esta información, el widget emitirá un evento al contenedor de tu aplicación WEB donde, el nombre del evento es onDoctorRegistered. Esto puede ser útil si quieres tener el control de qué usuarios han sido registrados en nuestra plataforma. Además en este evento debes de iniciar la sincronización de los pacientes del doctor registrados en tu plataforma hacia la nuestra, esto utilizando nuestro servicio web del cuál vablamos en el inciso dos de esta guía.
Evento onDoctorRegistered
Este es un pequeño ejemplo del evento emitido por el widget, su captura y la información que en él se contiene. En el evento podrás obtener el número de licencia médica principal del doctor y el país al que pertenece.
const container = document.getElementById('widget_container')
container.addEventListener("onDoctorRegistered", function (e) {
console.log(e.detail.medicalLicenseNumber);
console.log(e.detail.medicalLicenseNumber);
});
Es en este listener que debes de hace la sincronización de pacientes hacia nuestra plataforma.
Doctor registrado
Si el doctor ya se encuentra registrado en nuestra plataforma, el Widget muestra un mensaje indicando que ya se encuentra registrado.
2. Creación de pacientes fuera de EHR
Debe de realizarse una sincronización de pacientes en dos ocaciones:
- Cuando un doctor acaba de ser registrado desde tu aplicación.
- Cuando acaba de agregarse un usuario nuevo como paciente de un doctor que se ha dado de alta con nosotros desde tu aplicación.
Para ambos casos cuentas con un endpoint nuestro con el que puedes enviar el registro de uno o más pacientes para un doctor determinado. Este es un servicio que creará un mensaje dentro de nuestra cola de trabajo de EHR para que se inicie el registro de pacientes para el doctor especificado.
Puedes encontrar en nuestra referencia el contrato del servicio en el cual se especifica cada uno de los atributos requeridos de cada paciente.
Este servicio iniciará un proceso asíncrono de nuestro lado, por lo tanto recibirás una respuesta inmediata con un código de estado HTTP 201 y un identificador del proceso que se ha agregado a la cola de trabajo.
Ejemplo de solicitud
curl --request POST \
--url https://sandbox.osigu.com/ehr-api/v1/patients/bulk \
--header 'authorization: Bearer 99a801b4-6e34-4f64-94a9-c59ffc525c84' \
--header 'content-type: application/json' \
--data '{"doctor_country_code":"GT","medical_license_number":"2012-654","patients":[{"given_name":"Juan","first_surname":"Padilla","second_surname":"Rivera","sex":"MALE","date_of_birth":"1984-06-14","residence_country_code":"GT","phone_number":"53135485","cell_phone_number":"25468787","residence_address":"Ruta 2, 4-71 Zona 4, Cuatro Venezia, apto 102","related_patient":"false","email_address":"[email protected]","identity_document_type":"NATIONAL_IDENTITY_CARD","identity_document_id":"2515-67444-0102"}]}'
Para hacer uso de este endpoint debes de obtener un access token por medio de nuestro servidor OAuth2, puedes ver más información aquí de cómo obtener un access token.
Ejemplo de respuesta exitósa
{
'id': '645c1c99-38a6-4cef-b924-858f280dfda9'
}
Verificando el estado
Ponemos a tu disposición también un servicio con el que puedes dar seguimiento del proceso de carga. Puedes encontrar más información del contrato aquí.
El proceso de carga puede estar en cualquiera de los siguientes estados:
| Estado | Descripción |
|---|---|
| PENDING | El proceso ha sido registrado, pero aún no ha iniciado la carga. |
| IN_PROGRESS | La carga ha sido iniciada. |
| COMPLETED | El proceso de carga ha finalizado, los resultados ya pueden ser visualizados. |
Una vez se haya completado el proceso de carga, la respuesta del servicio dará indicadores del total de pacientes cargados satisfactoriamente y el total de pacientes que no pudieron ser registrados.
Cuando exista uno o mas pacientes que no pudieron ser cargados retornaremos un arreglo de pacientes (patients_not_registered) en donde podrá encontrar el error y la descripción, los dos posibles errores serán:
| Error | Descripción |
|---|---|
| ALREADY_EXISTS | Quiere decir que el paciente ya se encuentra registrado de lado de Osigu para el doctor indicado. |
| UNKNOW_ERROR | Ocurrió un error inesperado en nuestro sistema, la descripción del error mostrará más detalles. |
El siguiente es un ejemplo de un proceso completado.
{
'id': '645c1c99-38a6-4cef-b924-858f280dfda9',
'status': 'COMPLETED',
'total_patients': 250,
'succesfully_registered': 249,
'registered_with_errors: 1,
'doctor_country_code': 'GT',
'medical_license_number': '2012-654'
'patients_not_registered': [{
'given_name': 'John',
'middle_name': null,
'first_surname': 'Doe',
'second_surname': null,
'related_patient': false,
'email_address': '[email protected]',
'identity_document_type': 'NATIONAL_IDENTITY_CARD',
'identity_document_id': '2515-85781-0101',
'error': 'ALREADY_EXISTS',
'error_description': 'The patient already exists for this doctor'
}]
}
3. Creación de pacientes desde el EHR
Cuando un doctor previamente suscrito en nuestra plataforma entre a EHR, y cree un paciente nuevo nosotros estaremos notificando hacia tu plataforma acerca de este paciente nuevo creado, para que ambas plataformas se encuentren sincronizadas.
El método de autenticación para este servicio queda a tu preferencia, pero el servicio que proveas debe de ser un servicio tipo REST o bien un servicio SOAP.
La información que estaremos enviando a tu servicio será la siguiente:
| Atributo | Tipo | Descripción |
|---|---|---|
| doctor_country_code | String | Código donde ejerce el doctor |
| medical_license_number | String | Número de licencia médica del doctor |
| patient.given_name | String | Nombre del paciente |
| patient.middle_name | String | Segundo nombre del paciente |
| patient.first_surname | String | Primer apellido del paciente |
| patient.second_surname | String | Segundo apellido del paciente |
| patient.sex | String | Sexo del paciente |
| patient.date_of_birdth | String | Fecha de nacimiento del paciente |
| patient.residence_country_code | String | País donde se encuentra reside el paciente, |
| patient.phone_number | String | Teléfono residencial o fijo del paciente |
| patient.cell_phone_number | String | Número de teléfono móvil del paciente. |
| patient.residence_address | String | Dirección de residencia del paciente |
| patient.related_patient | Boolean | Indicador de si el paciente es un paciente relacionado |
| patient.email_address | String | Dirección de correo del paciente |
| patient.tutor_identification | Boolean | Identifica si los documentos de identificación son del tutor. |
| patient.identity_document_type | String | Tipo de documento de Identidad del paciente |
| patient.identity_document_id | String | Número de documento que identifica a un paciente |
4. Dirigiendo hacia EHR
Si deseas dirigir hacia el EHR en una nueva pestaña del navegador a tu usuario puedes hacerlo de la siguiente manera:
-
Consumir el endpoint especificado en esta sección, el cual según la información proporcionada del paciente intentará ubicar al paciente con la información más básica, si no lo encuentra lo crea inmediatamente. Este servicio te devolverá un identificador único y temporal para el paciente, de forma que puedas pasar este identificador temporal del paciente como parámetro dentro de la URL del EHR, este identificador solo puede ser usado una vez.
-
Dirigir en una nueva pestaña al usuario usando una URL como la que se ejemplifica a continuación.
https://ehr.sandbox.osigu.com?patient=390a2d91-3f6b-4ff6-b56a-816430161356
Es importante notar que en el ejemplo se puede observar que se esta apuntando al ambiente de sandbox, pero la URL cambiaría a la hora de hacer el despliegue en el ambiente producto, la URL quedaría de la siguiente forma, https://ehr.osigu.com?patient=390a2d91-3f6b-4ff6-b56a-816430161356
El UUID 390a2d91-3f6b-4ff6-b56a-816430161356 que se observa en el ejemplo es el ID temporal del paciente.
Cuando EHR reciba el request, el doctor deberá iniciar sesión si aún no lo ha hecho, luego la aplicación lo dirige a la sala de espera en donde procede con la atención del paciente.
Ambientes República Dominicana
Para el caso de República Dominicana, se cuenta un stack propio, por lo tanto las credenciales de OAuth2 y las URLs varían, quedando de la siguiente manera:
Updated over 3 years ago