Integration via REST API

To utilize the ePrescription system, Osigu provides services that assist with registering prescribers (doctors) to record prescriptions and make them available for medication dispensing.

Our API requires authentication through our OAuth2 server. In summary, you must first obtain an Access Token from our server using the credentials provided to each client using our services.

This guide details each of the integrations that must be implemented, as outlined below:

1. Doctor Registration: This stage involves using our service to register the medical provider on our platform. The goal is to provide basic doctor information, specialties, and handwritten signatures.

2. Use of our Product Catalog: This is a service that allows searching for products available in a specific country's market. This service performs a full-text search with typo tolerance.

3. Use of our Diagnoses Service: This service enables the search of diagnoses using ICD/CIE codes or diagnosis names.

4. Prescription Service: The service allows doctors to issue prescriptions, which are sent to the patient or made available for download.

Doctor Registration

Before generating prescriptions, you must register the doctor who will issue them. This information is reflected in the PDF document containing the doctor's prescription.

For detailed descriptions and data types expected by the service contract, refer to the documentation.

Below is an example of the request body and the response you will receive when registering a doctor using our service.

📘

Note

Remember, to register a doctor, you must first obtain your Access Token using the Client ID and Client Secret we provided.

Example 1.1 - Request Body

{
  "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'"
    }
  ]
}

Example 1.2 - Response Body

{
  "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'"
    }
  ]
}

Product Catalog

Our ePrescription creation service requires the use of product codes from our catalog. Utilizing this catalog allows the Osigu platform to perform the following tasks:

• Break down medications by brand, composition, format or presentation, and quantity.
• Calculate medications to dispense according to treatment, minimizing waste and reducing costs and risks (especially for LATAM insurance).
• Convert product codes into those processable by pharmacy POS systems.
• Translate product codes into national codes defined by the legislation of each country.
• Convert codes to those used by sponsors.

Additionally, it supports searching within our catalog with various filters as needed, employing mechanisms such as full-text search and typo tolerance.

More information about this service's contract can be found in this reference on this portal.

Below is an example service call to search for medications containing the word 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'

Using this service is necessary to create prescriptions via the abbreviated method. If you want to use the extended prescription method (the one supported by our widget), you must implement the medication search service.

The medication search service will provide more information about the medication's presentation and concentrations, enabling you to generate forms and gather the information needed for our prescription service.

Diagnosis Catalog

Implementing this service is not required for issuing electronic prescriptions. However, if you wish to record the diagnoses associated with the patient and prescription, you should implement this service.

This service allows searching using a full-text search mechanism with typo tolerance. It also supports searching not only by the name of the international standard but also by using synonyms, colloquialisms, or acronyms associated with diagnoses.

You can find more details about this service in this reference.

Below is an example of a service call for searching diagnoses containing the term ca.

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

Electronic Prescription Generation

The electronic prescription service can only be used for doctors already registered on our platform and assumes the use of Osigu services for searching products, medications, and diagnoses.

The service documentation is available at this link. Essentially, this service requires the following information in the request body:

📘

Note

While the request body does not mandate the inclusion of tests or treatments, at least one element in either attribute must be provided. Alternatively, at least one element for products or simplified treatments must be specified.

Prescription with Simplified Treatments

This section demonstrates how to prescribe using simplified treatments. This mechanism is required for generating prescriptions and dispensing in Spain and for integrations where the prescribing doctor specifies the dispensing quantity.

Prerequisites

To use this modality, the following prerequisites must be met:

1. Obtain an access token through our OAuth2 service.
2. Ensure the doctor is already registered.
3. If you wish to store patient diagnoses, provide one or more diagnoses using our diagnostics service (optional).
4. Select one or more products using our product search service.

Example

Below is an example of a prescription for two medications under this modality. One of the medications includes an extended treatment for 2 additional months, while the other is prescribed for a treatment duration of 14 days.

{
  "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"
}

Processing of the Simplified Treatment Prescription Request

The request outlined earlier performs the following tasks:

1. Doctor Verification

   • Ensures the doctor is registered and the registration belongs to the entity associated with the provided access token.

2. Patient Validation

   • Validates the patient information and determines if the patient already exists in the doctor’s repository or is a new patient. Each doctor has their own private patient repository that is not visible to other accounts.

3. Diagnostic Validation

   • If diagnoses are provided in the payload, the service ensures the required information is present and corresponds to Osigu's diagnostics catalog.

4. Treatment Validation

   • For each treatment in the request, the following checks are performed:
     1. Verifies that the product ID corresponds to an item in Osigu's catalog.
     2. In Spain, the medication composition is checked:
        • If the medication is a psychotropic or narcotic, treatment duration must not exceed three months.
        • For other medications, treatment duration must not exceed twelve months.

5. Electronic Prescription Creation

   • The prescription is created and sent to Osigu's dispensing system.

6. Patient Information Sheet (HIP) (Spain-specific)

   • A Patient Information Sheet (HIP) is generated alongside each prescription, complete with a Datamatrix code.

7. Prescription Email Delivery

   • If the patient's email address is provided, the system automatically emails the prescription to the patient.

Response Confirmation

The service response will include detailed information about:

• Doctor: Confirmed registration details.
• Patient: Validated or newly registered details.
• Prescription: Prescription details along with unique identifiers for each element.

The prescription identifier can be used to retrieve the PDF of the prescription using the services described later in this guide.

{
  "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"
}

List of Prescriptions and PDF Download

We provide the following additional endpoints for prescription management:

1. Service to List Prescriptions

This service retrieves prescriptions associated with a doctor. It allows filtering by country and medical license through query parameters. Additionally, you can search for prescriptions using the patient’s name or identification.

Pagination Features:

• Results are returned in a paginated format.
• Query parameters allow you to specify the number of items per page and the desired page number.
• The response includes:
  • Total items
  • Total pages
  • Current page number
  • Number of items in the current page

2. Service to Retrieve Prescription Details (JSON or PDF)

This service enables you to obtain full details of a specific prescription using its numeric ID, which was generated during the prescription creation process.

Response Formats:

• By setting the Content-Type header appropriately, you can:
  • Retrieve the full prescription information in JSON format.
  • Download the generated PDF, allowing the doctor to access and distribute the document.