Integración por REST API

Para poder utilizar el sistema de ePrescription Osigu pone a disposición servicios que ayudan desde el registro de los prescriptores (Doctores) hasta el registro de la recetas y su disponibilidad para la dispensación de los medicamentos.

Nuestra API siempre requerirá que se realice un mecanismo de autenticación por medio de nuestro servidor de OAuth2. En síntesis es necesario primero obtener un Access Token a través de nuestro servidor utilizando las credenciales proporcionados a cada cliente que utiliza nuestros servicios.

En esta guía se detallan cada una de las integraciones que deben de realizarse, enumerados de la siguiente manera:

Registro de Doctor, en esta etapa se utiliza nuestro servicio para el registro del proveedor médico dentro de nuestra plataforma, el objetivo es proporcionar información básica del doctor, especialidades y firma manuscrita.
Uso de nuestro catálogo de productos, este es un servicio que permite buscar productos disponibles en el mercado para un país determinado, este servicio realiza una búsqueda full-text search con tolerancia tipográfica.
Uso de nuestro servicio de diagnósticos, este servicio permite la búsqueda de diagnósticos por medio del código ICD/CIE o nombre del diagnóstico.
Servicio de receta, este es el servicio que permitirá que el doctor emita su receta y esta sea enviada al paciente o bien pueda ser descargada.

Registro de doctor

Para poder generar las recetas primero debe de existir información del doctor que va a emitir la receta, esta información es la que será plasmada dentro del documento PDF que contiene la prescripción realizada por el doctor.

Para obtener descripción y detalle de los tipos de datos esperados en el contrato del servicio puede dirigirse a la referencia para obtener mayor información.

Abajo encontrarás un ejemplo del request body y de la respuesta que obtendrás al realizar el registro de un Doctor por medio de nuestro servicio.

📘
NOTA
Recuerda que para poder realizar el registro del doctor, es necesario que ya hayas obtenido tu Access Token utilizando el Client ID y Client Secret que te proporcionamos.

{
  "name": "John Doe",
  "status": "ENABLED",
  "provider_type": "DOCTOR",
  "entity_type": "LEGAL",
  "country_code": "MX",
  "legal_name": "Farmacias MX S.A. de C.V.",
  "tax_identification_number": "83495702-92",
  "physical_address": "Cervantes Saavedra #301 Torre Sur",
  "email_address": "[email protected]",
  "phone_number": "+52 5255 9200",
  "bank_slug": "MX-BANAMEX",
  "bank_account_type": "CHECKING_ACCOUNT",
  "bank_account_number": "00011835971",
  "standarized_bank_account_number": "002-180-00011835971",
  "card_number": "xxx-2910",
  "external_registry": true,
  "sponsors": null,
  "salutation": "MD",
  "locale": "es_MX",
  "time_zone": "`America/Mexico_City'",
  "medical_license_number": "12349",
  "main_specialty_slug": "general-practitioner",
  "main_specialty_name": "General Practitioner",
  "handwirtten_signature": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAcHBwcHBwg...",
  "certificates": null,
  "specialties": [
    {
      "specialty_slug": "anesthesiology",
      "name": "Anesthesiology",
      "license_number": "3984209",
      "issuing_institution": "UNAM",
      "valid_from": "2018-01-02T00:00:00.000Z",
      "verification_status": "'CERTIFIED'"
    }
  ]
}

{
  "slug": "mx-12349",
  "name": "John Doe",
  "status": "ENABLED",
  "provider_type": "DOCTOR",
  "entity_type": "LEGAL",
  "country_code": "MX",
  "legal_name": "Farmacias MX S.A. de C.V.",
  "tax_identification_number": "83495702-92",
  "physical_address": "Cervantes Saavedra #301 Torre Sur",
  "email_address": "[email protected]",
  "phone_number": "+52 5255 9200",
  "bank_slug": "MX-BANAMEX",
  "bank_account_type": "CHECKING_ACCOUNT",
  "bank_account_number": "00011835971",
  "standarized_bank_account_number": "002-180-00011835971",
  "external_registry": true,
  "registry_status": "COMPLETED",
  "sponsors": null,
  "salutation": "MD",
  "locale": "es_MX",
  "time_zone": "`America/Mexico_City'",
  "medical_license_number": "12349",
  "main_specialty_slug": "general-practitioner",
  "main_specialty_name": "General Practitioner",
  "handwirtten_signature": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAcHBwcHBwg...",
  "certificates": null,
  "specialties": [
    {
      "specialty_slug": "anesthesiology",
      "name": "Anesthesiology",
      "license_number": "3984209",
      "issuing_institution": "UNAM",
      "valid_from": "2018-01-02T00:00:00.000Z",
      "verification_status": "'CERTIFIED'"
    }
  ]
}

Catálogo de Productos

Nuestro servicio para la creación de ePrescription requiere el uso de códigos de productos de nuestro catálogo. El uso de este catálogo permite que la plataforma de Osigu pueda realizar las siguientes tareas:

Desglose de los medicamentos en marcas, composición, formato o presentación y cantidad.
Calculo de medicamentos a dispensar según tratamiento, con el menor remanente o desperdicio para la disminución de gasto y siniestralidad (Seguros LATAM).
Conversión a códigos de producto procesables por los sistemas de POS de las farmacias.
Conversión a códigos de producto nacionales definidos por la legislación de cada país.
Conversión a códigos utilizados por los sponsors.

Adicional, permite la búsqueda dentro de nuestro catálogo aplicando diversos filtros según la necesidad y utilizando mecanismo de full-text search y de tolerancia tipográfica.

Puedes obtener mayor información sobre el contrato de este servicio en la referencia que se encuentra en este portal.

Abajo encontrarás la llamada a este servicio en donde se realiza una búsqueda de un medicamentos que contenta la palabra Nexium.

curl --request GET \
  --url 'https://sandbox.osigu.com/medical-catalogs/v1/products/search?product_name=Nexium&product_type_slug=DRUG' \
  --header 'authorization: Bearer 99a801b4-6e34-4f64-94a9-c59ffc525c84'

Es necesario el uso de este servicio para poder realizar la receta por método abreviado. Si deseas utilizar el método extendido de receta (El que usa nuestro widget), deberás de implementar el servicio de consulta de medicamentos.

El servicio de consulta de medicamentos te brindará mayor información sobre presentación del medicamento y concentraciones con la que podrás generar los formularios para obtener la información requerida por nuestro servicio de receta.

Catálogo de dianósticos

La implementación de este servicio no es requerido para la emisión de la receta electrónica, sin embargo, sí deseas que se quede registrado los diagnósticos asociados al paciente y receta, deberás implementar ese servicio.

Este servicio permite la búsqueda con un mecanismo de full-text search con tolerancia tipográfica pero además permite la búsqueda no solo por el nombre del estándar internacional, sino también por el uso de sinónimos, coloquialismos o siglas asociados a los diagnósticos.

Podrás encontrar mayor información de este servicio en este enlace.

curl --request GET \
  --url 'https://sandbox.osigu.com/medical-catalogs/v1/diagnoses/search?name=ca' \
  --header 'authorization: Bearer 99a801b4-6e34-4f64-94a9-c59ffc525c84'

Generación de receta electrónica

El servicio de receta electrónica podrá ser utilizado únicamente para aquellos doctores que ya han sido registrados en nuestra plataforma y supone el uso de los servicios de Osigu para la búsqueda de productos, medicamentos y diagnósticos.

La documentación del servicio la puedes encontrar en este enlace. Este servicio básicamente requiere que se traslade en el request body la siguiente información:

Atributo	Descripción	Requerido
doctor	Este inner object contiene la licencia médica y el país con lo que nosotros iremos a verificar si el doctor ya se encuentra registrado y la pertenencia según el `Access Token`.	Si
patient	Información del paciente al que se prescribe.	Si
diagnoses	Listado de diagnósticos asociados a la receta.	No
products	Listado de exámenes de laboratorio, exámenes por imagen y procedimientos en clínica indicados al paciente.	No
treatments	Este inner object representa los medicamentos recetados por el doctor. Este objeto necesita que se proporcione la información según el formato del medicamento y con respecto a la posología indicada Osigu hará el calculo de medicamentos a dispensar (LATAM)	No
simplified_treatments	Este inner object también representa medicamentos recetados, la diferencia es que permite una fácil integración en donde el médico indica la cantidad necesaria a dispensar. (España y donde no se requiera calculo de dispensación).	No

📘
NOTA
En el request body se indica que los exámenes y tratamientos no son requeridos, pero al menos un elemento de ambos atributos deben de ser indicado, o bien, que al menos un elemento para productos o tratamientos simplificados debe de ser indicado.

Receta con tratamientos simplificados

A continuación veremos la forma de recetar utilizando los tratamientos simplificados, este mecanismo es requerido para la generación de recetas y dispensación para España y para aquellas integraciones donde la cantidad a dispensar es indicada por el doctor que realiza la prescripción.

Para esta modalidad es necesario haber cumplido con los siguientes requisitos:

Obtener un access token por medio de nuestro servicio de OAuth2.
Que el doctor ya se encuentre registrado.
En caso desee almacenar los diagnósticos del paciente, proporcionar uno o más de estos diagnósticos según nuestro servicio de diagnósticos (opcional).
Haber seleccionado uno o más productos proporcionado por nuestro servicio de búsqueda de productos.

En el siguiente ejemplo se demuestra cómo sería la receta médica de dos medicamentos bajo esta modalidad, y uno de estos dos medicamentos con tratamiento extendido por 2 meses más y otro medicamento con un tratamiento con duración de 14 días.

{
  "doctor": {
    "medical_license_number": "789874256481",
    "country_code": "GT"
  },
  "patient": {
    "id": 9085,
    "first_name": "Paul",
    "middle_name": "Daniel",
    "first_surname": "Smith",
    "second_surname": "Jones",
    "sex": "MALE",
    "date_of_birth": "1990-08-05T08:50:51.620Z",
    "identity_document_type": "DNI",
    "identity_document_code": "1234567890",
    "nationality_country_code": "GT",
    "area_code": 502,
    "phone_number": "12345678",
    "email_address": "[email protected]"
  },
  "diagnoses": [{
      "id": 9085,
      "code": "D-K58",
      "name": "Colon irritable a descartar (en estudio)",
      "coding_system": "ICD-10",
      "synonym_id": 5874,
      "type": "CHIEF_COMPLAINT"
    }],
  "simplified_treatments": [{
    "product_id": 832,
    "single_dose": false,
    "frequency_in_hours": 24, 
    "dosage": 1,
    "unit_of_measure": "tabletas",
    "treatment_duration_days": 28,
    "quantity": 1,
    "treatment_extended": true,
    "extended_by": 2,
    "additional_notes": null
  },{
    "product_id": 980,
    "single_dose": false,
    "frequency_in_hours": 24, 
    "dosage": 10,
    "unit_of_measure": "mililitros",
    "treatment_duration_days": 14,
    "quantity": 1,
    "treatment_extended": false,
    "extended_by": null,
    "additional_notes": null
  }],
  "additional_notes": "Próxima cita 10 de enero de 2021"
}

El request anterior realizará las siguientes tareas:

Verifica que el doctor ya se encuentre registrado y que el registro pertenece a la entidad asociada al access token proporcionado.
Valida la información del paciente y determina si el paciente ya existe para el Doctor o es un paciente nuevo. Cada doctor cuenta con su propio repositorio de pacientes y esta información no puede ser vista por otras cuentas.
Si dentro del payload se informan diagnósticos, el servicio verificará que la información requerida este presente y corresponda a nuestro catálogo de diagnósticos.
Para cada uno de los tratamientos realizará las siguientes validaciones:

4.1 Se verificará que el ID del producto corresponda a un producto del catálogo de Osigu.
4.2 En el caso de España, se verificará la composición del medicamento y en caso sea psicótropo o narcótico se validará que el tratamiento no sea mayor a tres meses. Caso contrario el tratamiento no puede exceder de doce meses.

Se crea las recetas electrónicas y se envía al sistema de dispensación de Osigu.
Para España se crea la hoja de información de paciente (HIP) acompañada cada receta a dispensar y su código de Datamatrix.
Si en la información del paciente es incluída la dirección de correo electrónico, el sistema procede con el envío de la receta.

El servicio como confirmación retornará la información del doctor, paciente registrado y prescripción, cada uno de estos elementos con sus identificadores. El identificador de la receta puede ser utilizado para poder obtener luego el PDF correspondiente a la receta, por medio de los servicios que se detallan más adelante en esta guía.

{
  "id": 9875,
  "code": "ABC12345",
  "status": "READY",
  "confidential": false,
  "signed_document_id": "1eadc6f0-d4b0-4648-b789-b3f9e81e93ec",
  "additional_notes": "Próxima cita 10 de enero de 2021",  
  "doctor": {
    "id": 568,
    "name": "Edward George Armstrong",
    "medical_license_number": "789874256481",
    "country_code": "GT",
    "medical_specialty": "Pediatrics",
    "phone_number": "8974841-87465",
    "address": "1640 Riverside Drive, Hill Valley, California",
    "email_address": "[email protected]",
    "salutation": "Dr.",
    "enabled": true
  },
  "patient": {
    "id": 9085,
    "first_name": "Paul",
    "middle_name": "Daniel",
    "first_surname": "Smith",
    "second_surname": "Jones",
    "full_name": "Paul Daniel Smith Jones",
    "age": 25,
    "sex": "MALE",
    "date_of_birth": "1990-08-05T08:50:51.620Z",
    "identity_document_type": "DNI",
    "identity_document_code": "1234567890",
    "nationality_country_code": "GT",
    "area_code": 502,
    "phone_number": "12345678",
    "email_address": "[email protected]",
    "enabled": true,
    "manually_created": true
  },
  "diagnoses": [
    {
      "id": 6547,
      "diagnosis_id": 9085,
      "code": "D-K58",
      "name": "Colon irritable a descartar (en estudio)",
      "coding_system": "ICD-10",
      "synonym_id": 5874,
      "type": "CHIEF_COMPLAINT"
    }
  ],
  "simplified_treatments": [{
    "id": 382,
    "code": "ACFEJ234",
    "product_id": 832,
    "product_name": "NEXIUM 40 MGS X 28 COMPRIMIDOS",
    "single_dose": false,
    "frequency_in_hours": 24, 
    "dosage": 1,
    "unit_of_measure": "tabletas",
    "treatment_duration_days": 28,
    "quantity": 1,
    "treatment_extended": true,
    "extended_by": 2,
    "additional_notes": null,
    "posology": "Tomar 1 tableta cada 24 horas por 84 días",
    "dispensable_items": [{
    	  "id": 563,
        "code": "JDRU8343",
        "start_date": "2020-05-12",
        "end_date": "2020-06-09",
        "expires_at": "2020-05-22",
        "quantity": 1
    },{
        "id": 564,
        "code": "ZBDS8765",
        "start_date": "2020-06-09",
        "end_date": "2020-07-07",
        "expires_at": "2020-06-19",
        "quantity": 1
    },{
        "id": 565,
        "code": "KGOE5912",
        "start_date": "2020-07-07",
        "end_date": "2020-08-04",
        "expires_at": "2020-07-17",
        "quantity": 1
    }]
  },{
    "id": 383,
    "code": "DTRA1926",
    "product_id": 980,
    "product_name": "RANITIDINA INFASA JARABE DE 150 MGS/10 MLS X 1 FRASCO DE 150 MLS",
    "single_dose": false,
    "frequency_in_hours": 24, 
    "dosage": 10,
    "unit_of_measure": "mililitros",
    "treatment_duration_days": 14,
    "quantity": 1,
    "treatment_extended": false,
    "extended_by": null,
    "additional_notes": null,
    "posology": "Tomar 10 mililitros cada 24 horas por 14 días",
    "dispensable_items": [{
    	  "id": 566,
        "code": "ITRG7634",
        "start_date": "2020-05-12",
        "end_date": "2020-05-26",
        "expires_at": "2020-05-22",
        "quantity": 1
    }]
  }],
  "created_at": "2020-05-12T08:50:51.620Z",
  "created_by": "the-client-id"
}

Listado de recetas y descarga de PDF

Adicional ponemos a tu disposición los siguientes endpoints.

1. Servicio para listar las recetas que corresponden a un doctor.

El servicio anteriormente mencionado te retornará las recetas que correspondan al país y licencia médica indicada como query parameters, además permite la búsqueda por nombre o identificación del paciente.

Por ser un listado, este endpoint retorna la información de forma paginada, por lo tanto puedes indicar como query parameters la cantidad de elementos que deseas por página y el número de página deseada.

El servicio también te dará información como el total de elementos, total de páginas, número de página actual y numero de elementos incluídos en la página actual.

Servicio para obtener la información completa de una receta en formato JSON o PDF utilizando el ID numérico proporcionado al momento de crearla.

Este servicio te permitirá obtener la información completa de una receta en particular, pero además dependiendo del valor indicado en el encabezado Content-Type podrás obtener el PDF que fue generado y de esta forma permitir la descarga del documento al doctor.