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 clientId y clientSecret.
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:

Recurso	URL
Widgets	https://doctorenrollment.widgets.osigudr.com
API	https://api.osigudr.com
EHR	https://ehr.koneksi.com.do