REST API method / Метод REST API (настанова) (remove the link block before publishing the document)

Properties of a REST API method document

Document type	Метод REST API
Document title	[Document status] REST API [Назва методу] [ID методу]
Guideline ID	GUI-0011
Author	@
Document version	1
Document status	DRAFT
Date of creation	ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
Date of update	ХХ.ХХ.ХХХХ (дата зміни версії)
Method API ID	API-001-001-001-0001
Microservices (namespace)	MPI
Component	Auth
Component ID	COM-001-001
Link на API-специфікацію	https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/manage-client-configuration/get-client-details
Resource	{{host}}//api.ehealth.gov.ua/api/patients/id/encounter_package
Scope
Protocol type
Request type
Sync/Async
Public/Private

Purpose

This method allows to get the details of the Composition and detailed information about the related composition.

Used in processes:

1. Пошук та отримання МВ (загальний процес)

Logic

Sequence

MIS/Medical employee->Compositions: Create Composition POST/patients/composition
Compositions->Compositions: Check user scopes authorization composition:create
Compositions-->MIS/Medical employee: In case of error HTTP/401
Compositions->Compositions: Async job planning
Compositions->MIS/Medical employee: Async job details
Compositions<->eHealth:data clarification and verification about author, custodsan, diagnosis etc
Compositions->Compositions:Create and save Composition according to the XML template
Compositions->Compositions:Async job Completed
MIS/Medical employee->Compositions: GET/patients/composition/job/{asyncJobId}
Compositions->MIS/Medical employee:Async job completed (conclusionAsyncJobListItem.href)
MIS/Medical employee->Compositions:GET/patients/{patientId}/composition/{compositionId}/episode/{episodeId}/encounter/{encounterId}
Compositions->MIS/Medical employee: Composition in PRELIMINARY status
MIS/Medical employee->MIS/Medical employee:Signs document and gives to patient
MIS/Medical employee->Compositions:Sign Composition PATCH /patients/composition/{compositionId}/sign
Compositions->Compositions:Check user scopes authorization composition:sign
Compositions-->MIS/Medical employee: In case of error HTTP/401
Compositions->MIS/Medical employee: HTTP/200 Async job Created
Compositions<->eHealth:Signature and author validation
Compositions->Compositions:Save object on SWIFT/S3
Compositions->Compositions:Schedule of trigger interactions (DIIA,MJU_DRACZ,ERLN,MPI,Closure)
MIS/Medical employee->Compositions:GET /patients/composition/job/{asyncJobId}
Compositions->MIS/Medical employee:Async job completed (conclusionAsyncJobListItem.href)
MIS/Medical employee->Compositions:GET/patients/{patientId}/composition/{compositionId}/episode/{episodeId}/encounter/{encounterId}
Compositions->MIS/Medical employee:Composition in FINAL status

Configuration parameter

Description of the configuration parameters that are used when processing a request in the system

Dictionaries

Provides a list of links to dictionaries that are available in Confluence

Input parameters

Description of input parameters

	Input parameter	Type	Description	Example
1	compositionId	String ($uuid) (path)	Composition object ID	8c696fa4-6607-4aef-bab7-33cabc2dda2c
2	patientId	String ($uuid) (path)	Patient object ID	6a524088-c3f6-44ef-bcea-12a8e2900431
3	episodeId	String ($uuid) (path)	Episode of care object ID	e4f8c204-4879-4a90-a89f-707ffd7f02c4
4	encounterId	String ($uuid) (path)	Encounter object ID	d44ac2e9-9c83-4f5a-9ce1-0b764f260fff

Request structure

See on SwaggerHub

GET

request GET 'https://{environment}/api/patients/6a524088-c3f6-44ef-bcea-12a8e2900431/composition/8c696fa4-6607-4aef-bab7-33cabc2dda2c/episode/e4f8c204-4879-4a90-a89f-707ffd7f02c4/encounter/d44ac2e9-9c83-4f5a-9ce1-0b764f260fff' \

Headers

	Key	Value	Description	Example
1	Content-Type	application/json	Тип контенту	Content-Type:application/json
2	Authorization	Bearer {token}	Перевірка користувача	Authorization: Bearer {token}
3	api-key	{secret}	Секретний ключ	api-key: {secret}

Request data validation

Authorize

Check user scopes in order to perform this action (scope = 'composition:read')

return 401 (Unauthorized) in case of invalid scope(s)

Composition is not directly involved in the processing of the access authorization module (in the ABAC rules and in the creation of approvals). However, the getComposition request contains encounter's and episod's IDs. That's mean approve for obtain a composition is inherited from these objects and determined by the approvals on them.

In the case of access denied to view the Composition according to the rules of ABAC - return 403 "Access denied"

Excample for access denied

{
"error": {
"type": "forbidden",
"message": "Access denied"
},
"meta": {
"type": "object",
"code": 403,
"request_id": "1b49cfc5-da89-4e72-a1b9-4448a4f23f0b#3245097",
"url": "http://{environment}/api/patients/eb26f1e9-5bf0-435a-ad99-8364db773cd2/composition/b3e1e5e0-ce30-40df-9ffe-6296024dafae/episode/a2876da5-bc86-430b-932b-166603d9d97b/encounter/64afc7f1-6c4c-4dc2-8c44-5d5e1c56a4f6"
}
}

In case of wrong request data - return 404 “Not Found“ - “no Route matched with those values”

Processing

A list of processes related to receiving, changing or transmitting data according to the logic defined in the REST API

Response structure examples

See on SwaggerHub

Example

{
  "author": {
    "type": {
      "coding": [
        {
          "code": "employee",
          "system": "eHealth/resources"
        }
      ],
      "text": "string"
    },
    "value": "43cc2161-1c2b-481b-a618-77e35817f850"
  },
  "category": {
    "coding": [
      {
        "code": "SICKNESS",
        "system": "COMPOSITION_CATEGORIES"
      }
    ]
  },
  "custodian": {
    "type": {
      "coding": [
        {
          "code": "legal_entity",
          "system": "eHealth/resources"
        }
      ]
    },
    "value": "0dccb76f-3ed0-40f4-8f73-e95e2f91ea29"
  },
  "date": "2022-10-24T12:34:49.956Z",
  "encounter": {
    "type": {
      "coding": [
        {
          "code": "encounter",
          "system": "eHealth/resources"
        }
      ],
      "text": "string"
    },
    "value": "e39ee5ae-2644-4f04-8e64-bb359866e907"
  },
  "event": [
    {
      "code": {
        "coding": [
          {
            "code": "COMPOSITION_VALIDITY_PERIOD",
            "system": "COMPOSITION_EVENTS"
          }
        ]
      },
      "period": {
        "end": "2022-10-28T10:45:16Z",
        "start": "2022-10-24T10:45:16Z"
      }
    }
  ],
  "extension": [
    {
      "valueCode": "AUTHORIZE_WITH",
      "valueUuid": "e7ff2eef-712f-4676-960d-6aa16dce2103"
    },
    {
      "valueBoolean": true,
      "valueCode": "IS_FORCE_RENEW"
    },
    {
      "valueBoolean": true,
      "valueCode": "IS_ACCIDENT"
    },
    {
      "valueCode": "TREATMENT_VIOLATION",
      "valueString": "reject_recommendation"
    },
    {
      "valueCode": "TREATMENT_VIOLATION_DATE",
      "valueDate": "2022-10-24"
    },
    {
      "valueBoolean": true,
      "valueCode": "IS_FOREIGN_TREATMENT"
    },
    {
      "valueBoolean": true,
      "valueCode": "IS_INTOXICATED"
    }
  ],
  "identifier": {
    "type": {
      "coding": [
        {
          "code": "composition",
          "system": "eHealth/resources"
        }
      ]
    },
    "value": "2e629d9d-7d19-4bc4-937d-9000b567fd2a"
  },
  "relatesTo": [],
  "section": {
    "focus": {
      "type": {
        "coding": [
          {
            "code": "person",
            "system": "eHealth/resources"
          }
        ],
        "text": "string"
      },
      "value": "52b504c7-0177-4078-834b-52d89154081c"
    },
    "text": {
      "div": "",
      "status": "empty"
    }
  },
  "status": "PRELIMINARY",
  "subject": {
    "type": {
      "coding": [
        {
          "code": "person",
          "system": "eHealth/resources"
        }
      ],
      "text": "string"
    },
    "value": "52b504c7-0177-4078-834b-52d89154081c"
  },
  "title": "K5HP-HX65-4C8X-E85B",
  "type": {
    "coding": [
      {
        "code": "TEMP_DISABILITY",
        "system": "COMPOSITION_TYPES"
      }
    ]
  }
}

HTTP status codes

	Response code	HTTP Status code	Message	Description
1	Базові
2		200	If the object exists and access is authorized
3		401	(Unauthorized) in case of invalid scope(s)
4		403	Access denied	In the case of access denied to view the Composition according to the rules of ABAK
5		404	In case the Composition does not exist	The Composition wasn’t found
6	Специфічні
7

Post-processing processes

Description of actions performed on data after processing

Technical modules where the method is used

List of pages describing technical modules where the method is used

getComposition [API-006-001-001-0214]