openapi: 3.0.1
info:
  title: I_Consent_Decision_Management
  description: |-
    This interface provides access to the service **Consent Decision Management** of the Electronic Health Record system for insurants, representatives and ombuds offices.<br/>
    
    **General conditions**:</br> 
    For all operations if applicable:
    - a section _Client_ in operation descriptions covers recommendations (informative) for clients.
    - a section _Provider_ in operation descriptions covers requirements for the server side. 
    - error responses may be extended by helpful information about the error condition in _errorDetail_

    **Prerequisites**:</br>
    The Health Record System shall provide 
    - name
    - role ((profession-)oid)
    - identifier (telematik-id or KVNR)
    - indication of a valid entitlement
    
    of the current user (requestor) for evaluation in operations.

    Operations mandating a valid entitlement implicitly mandate use of a VAU channel
    and a valid ID-Token. If one of these conditions is not met, the response
    of the (aborted) operation shall always be '403': 'notEntitled'. 

    **Retry interval**:</br>
    The following retry intervals are suggested in case of an error response:<br>
    - '409' Conflict.
      - approx. 24 hours
    - '500' Internal Error
      - approx. 10 minutes

    **User Agent**:</br>
    The user agent information (x-useragent) is part of any request, even if 
    not essentially required for the operation (e.g. raw-data collection), and
    may be considered for provider internal use. 

    **Request ID**:</br>QQ
    Clients may provide a unique request identifier (X-Request-ID) with each request. 
    Given such a request identifier, providers must 
    - echo the exact same X-Request-ID value in the response header.
    - log the X-Request-ID in all operational logs related to that request.

    **Log-Entries**
    Whenever a _Postcondition_ mandates a log-entry, this entry shall contain
    data as defined in A_24055*.
    Log entry storage requires an entitled user for the related operation to 
    ensure access to secure data storage. Therefore, log entry creation shall 
    always be skipped and no log entry shall be stored if this precondition is 
    not met.

  version: 1.7.1

  # version history:
  # ----------------
  # version 1.7.1
  #   - renamed all occurrences of state MAINTENANCE to INACCESSIBLE
  # version 1.7.0
  #   - added status- and error code for state MAINTENANCE
  # version 1.6.1
  #   - clarification about condition for 404 noHealthRecord and 409 statusMismatch
  # version 1.6.0
  #   - optional X-Request-ID in all requests and responses
  #   - editorial correction: removed oid_diga from allowed userrgroups for udpMedication assignments 
  # version 1.5.3
  #   - additional error condition for missing device registration 
  #   - clarification on scope of an UdpMedication assignment (fhir medication + category emp)
  # version 1.5.1
  #   - clarification regarding required entitlement for logging
  #   - added error condition for not authenticated user sessions
  # version 1.5.0
  #   - rename ResearchUsagePurposes... to DataUsagePurposes 
  #   - fix: purpose examples
  #   - editorial improvements
  #   - changed status code from 404 to 409 in updateDataUsagePurposes and getDataUsagePurposes
  #   - introduce user specific policy medication service UdpMedication
  # version 1.4.0 (renamed: released for review as version 1.3.0 !)
  #   - new ressource researchDataPurpose for detailed consent of research data submission
  # version 1.3.0
  #   - changed array to object with array for consent lists
  # version 1.2.0
  #   - bugfix UserAgentType
  #   - return all changed consent decisions in response of updateConsentDecision  
  # version 1.1.1
  #   - reworked the correction of depending consent decision change 'medication' and 'erp-submission' 
  # version 1.1.0
  #   - correction in effect of consent decision 'medication' for oid_versicherter
  #   - correction of depending consent decision change 'medication' and 'erp-submission'
  #   - bugfixes
  # version 1.0.0
  #   - first release version
  # version 0.0.1
  #   - initial version for review

  contact:
    name: gematik GmbH
    url: 'http://www.gematik.de'
  license:
    name: Apache 2.0
    url: "https://www.apache.org/licenses/LICENSE-2.0"

servers:
  - url: https://epa-hst1.prod.epa4all.de

tags:
  - name: ConsentDecisions
    description: |
     Consent decision management operations allow to view current decisions made and to change those 
     decisions regarding consent related functions of the health record.
  - name: DataUsagePurposes
    description: |
     Consent decision management provides operations to manage the insurant's consent decisions regarding the 
     detailed purposes of use of transmitted health record data in the research data center (FDZ).    
  - name: UdpMedication
    description: |
      UdpMedication allows configuration of the user-specific deny policy for medication service only. 
      The UdpMedication is managed the insurant or entitled representatives for a health record by setting 
      or deleting assignments.</br>
      An assignment addresses a single user identified by a telematik-id. Any user covered by 
      an assignment is excluded from access to the medication service, even if a valid entitlement for this user applies.
      Vice versa access for a specific user is restored as soon as the assignment in UdpMedication is deleted.
        - an assignment for user X prevents access to: 
          - xds data category "emp"; folder.Codelist: code = "emp"; codeSystem = "urn:oid:1.2.276.0.76.5.512"
          - fhir data service "medication"
        - deletion of an assignment for user X allows access to (see Remark): 
          - xds data category "emp"; folder.Codelist: code = "emp"; codeSystem = "urn:oid:1.2.276.0.76.5.512"
          - fhir data service "medication"
      
      Remark: access to medication related data still requires a valid entitlement for the user and also a permitted general
      consent for _medication_ (see ConsentDecisions)

      **Allowed usergroups for UdpMedication assigments:**:</br> 
      TheUdpMedication shall have entries for users of the following roles (professionOid) only.</br>
      The following list of oids is for information only and may be incomplete, the normative requirement is defined in A_26406-*
      - oid_praxis_arzt
      - oid_krankenhaus
      - oid_institution-vorsorge-reha
      - oid_zahnarztpraxis
      - oid_öffentliche_apotheke
      - oid_praxis_psychotherapeut
      - oid_institution-pflege
      - oid_institution-geburtshilfe
      - oid_praxis-physiotherapeut
      - oid_institution-oegd
      - oid_institution-arbeitsmedizin
      - oid_praxis-ergotherapeut
      - oid_praxis-logopaede
      - oid_praxis-podologe
      - oid_praxis-ernaehrungstherapeut

paths:
  /epa/basic/api/v1/consents/{functionid}:
    parameters:
      - $ref: '#/components/parameters/insurantid'
      - $ref: "#/components/parameters/functionid"
      - $ref: '#/components/parameters/useragent'
      - $ref: '#/components/parameters/requestid'
    put:
      tags:
        - ConsentDecisions
      operationId: updateConsentDecision
      summary: (updateConsentDecision) Update one consent decisions
      description: |
        Update the user decision regarding a particular consent related function of a 
        personal health record.</br>
        This operation is limited to entitled users of role oid_versicherter and oid_ombudsstelle.

        **Client**:</br>
        no recommendations.

        **Provider**:</br>
        A changed consent decision shall be persisted securely in SecureDataStorage and become 
        immediately valid.

        Changed consents of class "healthCareProcess" shall also be made available for the Information Service.

        _functionid_ == _medication_:</br> 
        The change of this decision alters the medication process participation and shall cause special impact 
        for the XDS document service and the Fhir data service. If set to _deny_, no client (any oid) - except 
        the ePrescription backend, the insurant and representatives (oid_erp-vau, oid_versicherter) - shall be 
        able to read or write medication related data (locked). 
        Vice versa these clients are unlocked for intented use if decision is set to _permit_. </br>        
          - (a) lock the following data categories if _functionid_ = _medication_ is 
            set to _deny_: 
            - xds data category "emp"; folder.Codelist: code = "emp"; codeSystem = "urn:oid:1.2.276.0.76.5.512"
            - fhir data service "medication"
          - (b) unlock the following data categories if _functionid_ = _medication_ is 
            set to _permit_: 
            - xds data category "emp"; folder.Codelist: code = "emp"; codeSystem = "urn:oid:1.2.276.0.76.5.512"
            - fhir data service "medication"
          - (h) set the decision for _erp-submission_ to _permit_ if _functionid_ = _medication_ is 
            set to _permit_.

        _functionid_ == _erp-submission_:</br> 
        The change of this decision shall cause special impact for the XDS document service and the Fhir data service
        and disable the data collection related to the medication process if set to _deny_. 
        A decision change also sets the corresponding decision for _medication_ implicitly.</br> 
          - (c) remove all data from following data category (folder/service) if _functionid_ = _erp-submission_ is 
            set to _deny_:
            - xds data category "emp"; folder.Codelist: code = "emp"; codeSystem = "urn:oid:1.2.276.0.76.5.512"
            - fhir data service "medication"
          - (d) lock all operations for the ePrescription backend (oid_erp-vau) if _functionid_ = _erp-submission_ is 
            set to _deny_.
          - (e) unlock all operations for the ePrescription backend (oid_erp-vau) if _functionid_ = _erp-submission_ is 
            set to _permit_.
          - (f) set the decision for _medication_ to _deny_ (including the consequences for clients) if _functionid_ = _erp-submission_ is 
            set to _deny_.

        _functionid_ == _data-submission_:</br> 
          The change of this decision prevents submission of pseudonymized medical data to the research data center (FDZ) if set to _deny_. 
          The _deny_-decision information shall be sent to the FDZ instead of any further data for secondary usage.
          If set to _permit_ new medical data will be pseudonymized and send to the FDZ, including the consent decisions 
          of data usage purpose of the insurant.</br> 
        
        If decision provided equals decision stored (i.e. no change), this shall not cause an error response.

        An unknown parameter _functionid_ shall lead to rejection of the request. This operation operates on existings
        resources only and does not create new ones.

        An email shall be sent to the insurant using the registered mail address after a successful change of 
        a decision for notification. The mail shall contain understandable information about the changed consent
        decision(s) and timestamp of change (according to A_24844*)."

        The response of a successful operation shall contain all changed consent decisions. 

        | Conditions | Status code | Error code | Remarks |
        |------------|-------------|------------|---------|
        | Successful operation | 200 |||
        | Request does not match schema | 400 | malformedRequest ||
        | Requestor not authorized | 403 | invalAuth | no user session with valid ID-Token available |
        | Device registration does not exist | 403 | unregisteredDevice | if requestor role is oid_versicherter only |
        | Requestor has no valid entitlement | 403 | notEntitled ||
        | Requestor role is not _oid_versicherter_ or _oid_ombudsstelle_| 403 | invalidOid ||
        | Health record does not exist (UNKNOWN) or is in state INITIALIZED | 404 | noHealthRecord | |
        | Resource for _functionid_ does not exist | 404 | noResource ||
        | Health record is in state SUSPENDED or INACCESSIBLE | 409 | statusMismatch | (see 'Retry interval') |
        | Any other error | 500 | internalError | (see 'Retry interval') |

         </br>
        | Postconditions                        | Remarks |
        |---------------------------------------|---------|
        | The updated consent decision is stored in SecureDataStorage |in case of (f), (g), (h): both decisions |
        | Associated data categories are read and write protected for clients | conditional, see (a), (f) |
        | Associated data categories are read and write enabled for clients | conditional, see (b) |
        | Associated data categories are empty (all content deleted) | conditional, see (c) |
        | Operations for ePrescription backend (oid_erp-vau) are locked | conditional, see (d) |
        | Operations for ePrescription backend (oid_erp-vau) are unlocked | conditional, see (e), (h) |
        | Decision for _medication_ is set to _deny_| conditional, see (f) |
        | Decision for _medication_ is set to _permit_| conditional, see (g) |
        | Decision for _erp-submission_ is set to _permit_| conditional, see (h) |
        | The Information Service has updated consent decisions | conditional, if functions of class "healthCareProcess" are changed |
        | An email is sent to the insurant | success case with change of consent only |
        | A log-entry for the operation exists | all operation results |

      requestBody:
        required: true
        content:
          application/json:
            examples:
              Permit:
                summary: Permit request (e.g functionid == medication)
                value:
                 decision: "permit"
              Deny:
                summary: Deny request (e.g functionid == erp-submission)
                value:
                 decision: "deny"
            schema:
              $ref: "#/components/schemas/ConsentDecisionType"
      responses:
        "200":
          description: OK. Consent decision successfully updated
          headers:
            X-Request-ID:
              $ref: '#/components/headers/requestid'
          content:
            application/json:
              examples:
                Permit_Medication:
                  summary: Permit functionid == medication (permits erp-submission internally) response
                  value:
                    data:
                      - functionId: "medication"
                        decision: "permit"
                      - functionId: "erp-submission"
                        decision: "permit"
                Deny_erp-submission:
                  summary: Deny functionid == erp-submission (denies medication internally) response
                  value:
                    data:
                      - functionId: "medication"
                        decision: "deny"
                      - functionId: "erp-submission"
                        decision: "deny"
                Deny_erp-submission2:
                  summary: Deny functionid == erp-submission (medication already denied) response
                  value:
                    data:
                      - functionId: "erp-submission"
                        decision: "deny"
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ConsentDecisionsResponseType"
        '400':
          $ref: "#/components/responses/Error400BadRequest"
        '403':
          $ref: "#/components/responses/Error403Forbidden"
        '404':
          $ref: "#/components/responses/Error404NotFound"
        '409':
          $ref: "#/components/responses/Error409Conflict"
        '500':
          $ref: "#/components/responses/Error500InternalError"

    get:
      tags:
        - ConsentDecisions
      operationId: getConsentDecision
      summary: (getConsentDecision) Read one current consent decisions
      description: |
        Get current decision for a particular consent related functions of the health record.<br/>
        This operation is limited to entitled users of role oid_versicherter and oid_ombudsstelle.

        **Client**:</br>
        no recommendations.

        **Provider**:
        | Conditions | Status code | Error code | Remarks |
        |------------|-------------|------------|---------|
        | Successful operation | 200 |||
        | Request does not match schema | 400 | malformedRequest ||
        | Requestor not authorized | 403 | invalAuth | no user session with valid ID-Token available |
        | Device registration does not exist | 403 | unregisteredDevice | if requestor role is oid_versicherter only |
        | Requestor has no valid entitlement | 403 | notEntitled ||
        | Requestor role is not _oid_versicherter_ or _oid_ombudsstelle_| 403 | invalidOid ||
        | Health record does not exist (UNKNOWN) or is in state INITIALIZED | 404 | noHealthRecord | |
        | Resource for _functionid_ does not exist | 404 | noResource ||
        | Health record is in state SUSPENDED or INACCESSIBLE | 409 | statusMismatch | (see 'Retry interval') |
        | Any other error | 500 | internalError | (see 'Retry interval') |

         </br>
        | Postconditions                        | Remarks |
        |---------------------------------------|---------|
        | none ||

      responses:
        '200':
          description: Ok.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/requestid'
          content:
            application/json:
              example:
                functionId: "medication"
                decision: "deny"
              schema:
                $ref: "#/components/schemas/ConsentDecisionsResponseType"
        '400':
          $ref: "#/components/responses/Error400BadRequest"
        '403':
          $ref: "#/components/responses/Error403Forbidden"
        '404':
          $ref: "#/components/responses/Error404NotFound"
        '409':
          $ref: "#/components/responses/Error409Conflict"
        '500':
          $ref: "#/components/responses/Error500InternalError"

  /epa/basic/api/v1/consents:
    parameters:
      - $ref: '#/components/parameters/insurantid'
      - $ref: '#/components/parameters/useragent'
      - $ref: '#/components/parameters/requestid'
    get:
      tags:
        - ConsentDecisions
      operationId: getConsentDecisions
      summary: (getConsentDecisions) Read all current consent decisions
      description: |
        Get current decisions for all consent related functions of the health record.<br/>
        This operation is limited to entitled users of role oid_versicherter and oid_ombudsstelle.

        **Client**:</br>
        no recommendations.

        **Provider**
        | Conditions | Status code | Error code | Remarks |
        |------------|-------------|------------|---------|
        | Successful operation | 200 |||
        | Request does not match schema | 400 | malformedRequest ||
        | Requestor not authorized | 403 | invalAuth | no user session with valid ID-Token available |
        | Device registration does not exist | 403 | unregisteredDevice | if requestor role is oid_versicherter only |
        | Requestor has no valid entitlement | 403 | notEntitled ||
        | Requestor role is not _oid_versicherter_ or _oid_ombudsstelle_| 403 | invalidOid ||
        | Health record does not exist (UNKNOWN) or is in state INITIALIZED | 404 | noHealthRecord | |
        | Health record is in state SUSPENDED or INACCESSIBLE | 409 | statusMismatch | (see 'Retry interval') |
        | Any other error | 500 | internalError | (see 'Retry interval') |

         </br>
        | Postconditions                        | Remarks |
        |---------------------------------------|---------|
        | none ||

      responses:
        '200':
          description: Ok.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/requestid'
          content:
            application/json:
              example:
                data:
                  - functionId: "medication"
                    decision: "deny"
                  - functionId: "erp-submission"
                    decision: "permit"
                  - functionId: "data-submission"
                    decision: "permit"                    
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ConsentDecisionsResponseType"
        '400':
          $ref: "#/components/responses/Error400BadRequest"
        '403':
          $ref: "#/components/responses/Error403Forbidden"
        '404':
          $ref: "#/components/responses/Error404NotFound"
        '409':
          $ref: "#/components/responses/Error409Conflict"
        '500':
          $ref: "#/components/responses/Error500InternalError"

  /epa/basic/api/v1/DataUsagePurposes:
    parameters:
      - $ref: '#/components/parameters/insurantid'
      - $ref: '#/components/parameters/useragent'
      - $ref: '#/components/parameters/requestid'
    put:
      tags:
        - DataUsagePurposes
      operationId: updateDataUsagePurposes
      summary: (updateDataUsagePurposes) Update the consent list regarding purposes for usage of research data
      description: |
        Update the insurant's decision regarding the permissible use of data for research purposes.</br>
        This operation is limited to entitled users of role oid_versicherter and oid_ombudsstelle.

        **Client**:</br>
        no recommendations.

        **Provider**:</br>
        A changed list of _DataUsagePurposes_ shall be persisted securely in SecureDataStorage. The changed list
        shall be provided to the Data Submission Service in association to the insurantid for delivery to 
        the research data center.</br>
        The operation shall only succeed in case of general consent for data submission:</br> 
        _functionid_ == _data-submission_ == _permit_</br> 

        An email shall be sent to the insurant using the registered mail address after a successful change of 
        a decision for notification. The mail shall contain understandable information about the changed consent
        decision reagrding data submission and timestamp of change (according to A_24844*)."

        The operation shall succeed in case of no reulting change of consents (i.e. 'old' and 'new' consent settings
        are equal).

        | Conditions | Status code | Error code | Remarks |
        |------------|-------------|------------|---------|
        | Successful operation | 200 |||
        | Request does not match schema | 400 | malformedRequest ||
        | Requestor not authorized | 403 | invalAuth | no user session with valid ID-Token available |
        | Device registration does not exist | 403 | unregisteredDevice | if requestor role is oid_versicherter only |
        | Requestor has no valid entitlement | 403 | notEntitled ||
        | Requestor role is not _oid_versicherter_ or _oid_ombudsstelle_| 403 | invalidOid ||
        | Health record does not exist (UNKNOWN) or is in state INITIALIZED | 404 | noHealthRecord | |
        | No permission (consent) for data submission | 409 | noConsent ||
        | Health record is in state SUSPENDED or INACCESSIBLE | 409 | statusMismatch | (see 'Retry interval') |
        | Any other error | 500 | internalError | (see 'Retry interval') |

         </br>
        | Postconditions                        | Remarks |
        |---------------------------------------|---------|
        | The updated list of DataUsagePurposes is persisted securely in SecureDataStorage | |
        | Updated list of DataUsagePurposes is provided to the Data Submission Service | |
        | An email is sent to the insurant | success case with changed of consent(s) only |
        | A log-entry for the operation exists | all operation results |

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DataUsagePurposesType"
            examples:
              Permit_Pupose1_only:
                $ref: "#/components/examples/Permit_Pupose1_only"
      responses:
        "200":
          description: OK. DataUsagePurposes successfully updated
          headers:
            X-Request-ID:
              $ref: '#/components/headers/requestid'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataUsagePurposesType"
              examples:
                Permit_Pupose1_only:
                  $ref: "#/components/examples/Permit_Pupose1_only"
        '400':
          $ref: "#/components/responses/Error400BadRequest"
        '403':
          $ref: "#/components/responses/Error403Forbidden"
        '404':
          $ref: "#/components/responses/Error404NotFound"
        '409':
          $ref: "#/components/responses/Error409Conflict"
        '500':
          $ref: "#/components/responses/Error500InternalError"
    get:
      tags:
        - DataUsagePurposes
      operationId: getDataUsagePurposes
      summary: (getDataUsagePurposes) Read the consent list regarding the data usage purposes
      description: |
        Get the current user decision regarding the permissible uses of data in the Research Data Center.</br>
        This operation is limited to entitled users of role oid_versicherter and oid_ombudsstelle.

        **Client**:</br>
        no recommendations.

        **Provider**:</br>
        The operation shall only succeed in case of general consent for data submission:</br> 
        _functionid_ == _data-submission_ == _permit_:</br>

        | Conditions | Status code | Error code | Remarks |
        |------------|-------------|------------|---------|
        | Successful operation | 200 |||
        | Request does not match schema | 400 | malformedRequest ||
        | Requestor not authorized | 403 | invalAuth | no user session with valid ID-Token available |
        | Device registration does not exist | 403 | unregisteredDevice | if requestor role is oid_versicherter only |
        | Requestor has no valid entitlement | 403 | notEntitled ||
        | Requestor role is not _oid_versicherter_ or _oid_ombudsstelle_| 403 | invalidOid ||
        | Health record does not exist (UNKNOWN) or is in state INITIALIZED | 404 | noHealthRecord | |
        | No permission (consent) for data submission | 409 | noConsent ||
        | Health record is in state SUSPENDED or INACCESSIBLE | 409 | statusMismatch | (see 'Retry interval') |
        | Any other error | 500 | internalError | (see 'Retry interval') |

         </br>
        | Postconditions                        | Remarks |
        |---------------------------------------|---------|
        | none ||

      responses:
        '200':
          description: Ok.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/requestid'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataUsagePurposesType"
              examples:
                Permit_Pupose1_only:
                  $ref: "#/components/examples/Permit_Pupose1_only"
        '400':
          $ref: "#/components/responses/Error400BadRequest"
        '403':
          $ref: "#/components/responses/Error403Forbidden"
        '404':
          $ref: "#/components/responses/Error404NotFound"
        '409':
          $ref: "#/components/responses/Error409Conflict"
        '500':
          $ref: "#/components/responses/Error500InternalError"

  /epa/basic/api/v1/userspecific/medication:
    parameters:
      - $ref: '#/components/parameters/insurantid'
      - $ref: '#/components/parameters/useragent'
      - $ref: '#/components/parameters/requestid'
    get:
      tags:
        - UdpMedication
      operationId: getUserSpecificMedicationDenyList
      summary: (getUserSpecificMedicationDenyList) get a list of assignments of UdpMedication
      description: |
        Get a list of actual set assignments of the user specific deny policy for medication service.</br>
        This operation is limited to entitled users of role oid_versicherter.

        **Provider**:</br>
        The returned list shall contain only all assignments of user specific deny policy for medication service.</br>
        
        | Conditions | Status code | Error code | Remarks |
        |------------|-------------|------------|---------|
        | Successful operation | 200 |||
        | Request does not match schema | 400 | malformedRequest ||
        | Requestor not authorized | 403 | invalAuth | no user session with valid ID-Token available |
        | Device registration does not exist | 403 | unregisteredDevice | if requestor role is oid_versicherter only |
        | Requestor has no valid entitlement | 403 | notEntitled ||
        | Requestor role is not oid_versicherter_ | 403 | invalidOid ||
        | Health record does not exist (UNKNOWN) or is in state INITIALIZED | 404 | noHealthRecord | |
        | Health record is in state SUSPENDED or INACCESSIBLE | 409 | statusMismatch | (see 'Retry interval') |
        | Any other error | 500 | internalError | (see 'Retry interval') |

         </br>
        | Postconditions                        | Remarks |
        |---------------------------------------|---------|
        | none ||

      responses:
        '200':
          description: Ok. Returns a list of policy assignments
          headers:
            X-Request-ID:
              $ref: '#/components/headers/requestid'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/UdpMedicationResponseType'
              examples:
                getAll:
                  $ref: '#/components/examples/Get_AllUdpMedication'
        '400':
          $ref: '#/components/responses/Error400BadRequest'
        '403':
          $ref: '#/components/responses/Error403Forbidden'
        '404':
          $ref: '#/components/responses/Error404NotFound'
        '409':
          $ref: '#/components/responses/Error409Conflict'
        '500':
          $ref: '#/components/responses/Error500InternalError'

    post:
      tags:
        - UdpMedication
      operationId: setUserSpecificMedicationDeny
      summary: (setUserSpecificMedicationDeny) add a user to the UdpMedication
      description: |
        Set a new assignment for the user specific deny policy for medication.</br>
        The user addressed by the UdpMedication is excluded from access to the medication service.</br>
        This operation is limited to entitled users of role oid_versicherter.

        **Client**:</br>
        A client shall set assignments for users of the allowed roles for 
        UdpMedication only.</br>

        **Provider**:</br>
        A valid new assignment shall be added to the UdpMedication.

        Each new valid assigment shall be extended by a timestamp (_at_ = current date and time)
        by the server.

        An email shall be sent to the insurant using the registered mail address after successful 
        operation for notification. The mail shall contain understandable information about the changed 
        assignment and the timestamp."        

        | Conditions | Status code | Error code | Remarks |
        |------------|-------------|------------|---------|
        | Successful operation | 201 |||
        | Request does not match schema | 400 | malformedRequest ||
        | Requestor not authorized | 403 | invalAuth | no user session with valid ID-Token available |
        | Device registration does not exist | 403 | unregisteredDevice | if requestor role is oid_versicherter only |
        | Requestor has no valid entitlement | 403 | notEntitled ||
        | Requestor role is not _oid_versicherter_ | 403 | invalidOid ||
        | Health record does not exist (UNKNOWN) or is in state INITIALIZED | 404 | noHealthRecord | |
        | Health record is in state SUSPENDED or INACCESSIBLE | 409 | statusMismatch | (see 'Retry interval') |
        | The assignment parameter _oid_ is not in the list of allowd oids | 409 | requestMismatch ||
        | The assignment does yet exist (same _actorId_) | 409 | requestMismatch | avoid duplicates |
        | Any other error | 500 | internalError | (see 'Retry interval') |

         </br>
        | Postconditions                        | Remarks |
        |---------------------------------------|---------|
        | The UdpMedication assignment is extended with the timestamp and stored in SecureDataStorage ||
        | An eMail shall be sent to the insurant, including information about the UdpMedication change| if eMail address is available |
        | A log-entry for the operation exists | all operation results |

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UdPMedicationAssignmentType'
            examples:
              onePolicy:
                $ref: '#/components/examples/Set_SingleUdpAssignment'
      responses:
        '201':
          description: Created
          headers:
            X-Request-ID:
              $ref: '#/components/headers/requestid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UdpMedicationResponseType'
              examples:
                onePolicy:
                  $ref: '#/components/examples/Get_SingleUdpAssignment'

        '400':
          $ref: '#/components/responses/Error400BadRequest'
        '403':
          $ref: '#/components/responses/Error403Forbidden'
        '404':
          $ref: '#/components/responses/Error404NotFound'
        '409':
          $ref: '#/components/responses/Error409Conflict'
        '500':
          $ref: '#/components/responses/Error500InternalError'
  
  /epa/basic/api/v1/userspecific/medication/{telematikid}:
    parameters:
      - $ref: '#/components/parameters/insurantid'
      - $ref: '#/components/parameters/telematikid'
      - $ref: '#/components/parameters/useragent'
      - $ref: '#/components/parameters/requestid'
    get:
      tags:
        - UdpMedication
      operationId: getUserSpecificMedicationDeny
      summary: (getUserSpecificMedicationDeny) get a particular user of UdpMedication
      description: |
        Get one particular assignment of the user specific deny policy for medication service.</br>
        This operation is limited to entitled users of role oid_versicherter.

        **Client**:</br>
        no recommendations.

        **Provider**:</br>
        The addressed assigment shall be returned.
        
        | Conditions | Status code | Error code | Remarks |
        |------------|-------------|------------|---------|
        | Successful operation | 200 |||
        | Request does not match schema | 400 | malformedRequest ||
        | Requestor not authorized | 403 | invalAuth | no user session with valid ID-Token available |
        | Device registration does not exist | 403 | unregisteredDevice | if requestor role is oid_versicherter only |
        | Requestor has no valid entitlement | 403 | notEntitled ||
        | Requestor role is not oid_versicherter_ | 403 | invalidOid ||
        | Health record does not exist (UNKNOWN) or is in state INITIALIZED | 404 | noHealthRecord | |
        | Resource for _telematikid_ does not exist | 404 | noResource ||
        | Health record is in state SUSPENDED or INACCESSIBLE | 409 | statusMismatch | (see 'Retry interval') |
        | Any other error | 500 | internalError | (see 'Retry interval') |

         </br>
        | Postconditions                        | Remarks |
        |---------------------------------------|---------|
        | none ||
      responses:
        '200':
          description: Ok.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/requestid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UdpMedicationResponseType'
              examples:
                onePolicy:
                  $ref: '#/components/examples/Get_SingleUdpAssignment'
        '400':
          $ref: '#/components/responses/Error400BadRequest'
        '403':
          $ref: '#/components/responses/Error403Forbidden'
        '404':
          $ref: '#/components/responses/Error404NotFound'
        '409':
          $ref: '#/components/responses/Error409Conflict'
        '500':
          $ref: '#/components/responses/Error500InternalError'

    delete:
      tags:
        - UdpMedication
      operationId: deleteUserSpecificMedicationDeny
      summary: (deleteUserSpecificMedicationDeny) remove a user UdpMedication
      description: |
        Delete one existing assignment of the user specific deny policy for medication service.</br>
        This operation is limited to entitled users of role oid_versicherter.

        **Client**:</br>
        no recommendations.

        **Provider**:</br>
        The addressed assigment shall be removed from the UdpMedication.
        
        An email shall be sent to the insurant using the registered mail address after successful 
        operation for notification. The mail shall contain understandable information about the deleted 
        assignment."        

        | Conditions | Status code | Error code | Remarks |
        |------------|-------------|------------|---------|
        | Successful operation | 204 |||
        | Request does not match schema | 400 | malformedRequest ||
        | Requestor not authorized | 403 | invalAuth | no user session with valid ID-Token available |
        | Device registration does not exist | 403 | unregisteredDevice | if requestor role is oid_versicherter only |
        | Requestor has no valid entitlement | 403 | notEntitled ||
        | Requestor role is not _oid_versicherter_| 403 | invalidOid ||
        | Health record does not exist (UNKNOWN) or is in state INITIALIZED | 404 | noHealthRecord | |
        | Assignment (_telematikid_) does not exist | 404 | noResource ||
        | Health record is in state SUSPENDED or INACCESSIBLE | 409 | statusMismatch | (see 'Retry interval') |
        | Any other error | 500 | internalError | (see 'Retry interval') |

         </br>
        | Postconditions                        | Remarks |
        |---------------------------------------|---------|
        | The addressed assignment is removed from the UdpMedication ||
        | An eMail is sent to the insurant, including information about the UdpMedication change| if eMail address is available |
        | A log-entry for the operation exists | all operation results |

      responses:
        '204':
          description: OK. Assignment deleted
          headers:
            X-Request-ID:
              $ref: '#/components/headers/requestid'
        '400':
          $ref: '#/components/responses/Error400BadRequest'
        '403':
          $ref: '#/components/responses/Error403Forbidden'
        '404':
          $ref: '#/components/responses/Error404NotFound'
        '409':
          $ref: '#/components/responses/Error409Conflict'
        '500':
          $ref: '#/components/responses/Error500InternalError'

components:

  headers:
    requestid:
      description: Request identifier as provided by the client.
      schema:
       $ref: '#/components/schemas/RequestIdType'

  parameters:
    insurantid:
      name: x-insurantid
      in: header
      description: Health Record Identifier.
      required: true
      schema:
        $ref: '#/components/schemas/InsurantIdType'
    useragent:
      name: x-useragent
      in: header
      description: user agent information
      required: true
      schema:
        $ref: '#/components/schemas/UserAgentType'
    requestid:
      name: X-Request-ID
      in: header
      description: request identifier
      schema:
        $ref: '#/components/schemas/RequestIdType'
    functionid:
      name: functionid
      in: path
      description: id of the consent related function
      required: true
      schema:
        $ref: '#/components/schemas/FunctionIdType'
    telematikid:
      name: telematikid
      in: path
      description: TelematikID
      required: true
      schema:
        $ref: '#/components/schemas/TelematikIdType'

  responses:
    Error400BadRequest:
      description: Bad Request.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/requestid'
      content:
        application/json:
          example:
            errorCode: malformedRequest
          schema:
            $ref: '#/components/schemas/ErrorType'
    Error403Forbidden:
      description: Forbidden.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/requestid'
      content:
        application/json:
          example:
            errorCode: notEntitled
          schema:
            $ref: '#/components/schemas/ErrorType'
    Error404NotFound:
      description: Not found.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/requestid'
      content:
        application/json:
          example:
            errorCode: noResource
          schema:
            $ref: '#/components/schemas/ErrorType'
    Error409Conflict:
      description: Conflict.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/requestid'
      content:
        application/json:
          examples:
            statusMismatch:
              value:
                errorCode: statusMismatch
          schema:
            $ref: '#/components/schemas/ErrorType'
    Error500InternalError:
      description: Internal Server Error
      headers:
        X-Request-ID:
          $ref: '#/components/headers/requestid'
      content:
        application/json:
          example:
            errorCode: internalError
          schema:
            $ref: '#/components/schemas/ErrorType'

  schemas:
    ConsentDecisionType:
      description: "Consent Decision"
      type: object
      properties:
        decision:
          type: string
          enum: ["permit", "deny"]
          description: "Decision"
      required:
        - decision
      example:
        decision: "deny"
    ConsentDecisionsResponseType:
      description: "Consent Decisions Response"
      type: object
      properties:
        functionId:
          $ref: '#/components/schemas/FunctionIdType'
        decision:
          type: string
          enum: ["permit", "deny"]
          description: "Decision"
      required:
        - functionId
        - decision
      example:
          functionId: "medication"
          decision: "deny"

    DataUsagePurposesType:
      description: "List of Data Usage Purposes"
      type: object
      properties:
        purpose1:
          $ref: '#/components/schemas/Purpose1Type'
        purpose2:
          $ref: '#/components/schemas/Purpose2Type'
        purpose3:
          $ref: '#/components/schemas/Purpose3Type'
        purpose4:
          $ref: '#/components/schemas/Purpose4Type'
        purpose5:
          $ref: '#/components/schemas/Purpose5Type'
        purpose6:
          $ref: '#/components/schemas/Purpose6Type'
        purpose7:
          $ref: '#/components/schemas/Purpose7Type'
        purpose8:
          $ref: '#/components/schemas/Purpose8Type'
        purpose9:
          $ref: '#/components/schemas/Purpose9Type'
        purpose10:
          $ref: '#/components/schemas/Purpose10Type'
      required:
        - purpose1
        - purpose2
        - purpose3
        - purpose4
        - purpose5
        - purpose6
        - purpose7
        - purpose8
        - purpose9
        - purpose10
    UserAgentType:
      description: "Information about client software with: ClientId(20 characters) + / + VersionNumber (1 to 15 characters)."
      type: string
      pattern: '^[a-zA-Z0-9\-]{1,20}\/[a-zA-Z0-9\-\.]{1,15}$'
      example: CLIENTID1234567890AB/2.1.12-45
    FunctionIdType:
      type: string
      description: function id of consent related functions of a health record.
    InsurantIdType:
      type: string
      description: |-
        The health record identifier. 
        For today the record identifier equals the insurant id (kvnr).
      pattern: '^[A-Z]{1}\d{9}$'
      example: Z123456789
    RequestIdType:
      type: string
      format: uuid
      description: "Unique identifier of the request"
      example: "f4411e89-2eca-405c-88a1-7ee20b9b6e3c"
    Purpose1Type:
      description: "State of consent for purpose referring §303e SGB V clause 2 number 1: Wahrnehmung von Steuerungsaufgaben durch die Kollektivvertragspartner"
      type: object
      properties:
        decision:
          type: string
          enum: ["permit", "deny"]
    Purpose2Type:
      description: "State of consent for purpose referring §303e SGB V clause 2 number 2: Verbesserung der Qualität der Versorgung sowie Verbesserung der Sicherheitsstandards der Prävention, Versorgung und Pflege"
      type: object
      properties:
        decision:
          type: string
          enum: ["permit", "deny"]
    Purpose3Type:
      description: "State of consent for purpose referring §303e SGB V clause 2 number 3: Planung von Leistungsressourcen, zum Beispiel Krankenhausplanung oder Pflegestrukturplanungsempfehlungen nach § 8a Absatz 4 des Elften Buches"
      type: object
      properties:
        decision:
          type: string
          enum: ["permit", "deny"]
    Purpose4Type:
      description: "State of consent for purpose referring §303e SGB V clause 2 number 4: wissenschaftliche Forschung zu Fragestellungen aus den Bereichen Gesundheit und Pflege, Analysen des Versorgungsgeschehens, sowie Grundlagenforschung im Bereich der Lebenswissenschaften"
      type: object
      properties:
        decision:
          type: string
          enum: ["permit", "deny"]
    Purpose5Type:
      description: "State of consent for purpose referring §303e SGB V clause 2 number 5: Unterstützung politischer Entscheidungsprozesse zur Weiterentwicklung der gesetzlichen Kranken- und Pflegeversicherung"
      type: object
      properties:
        decision:
          type: string
          enum: ["permit", "deny"]
    Purpose6Type:
      description: "State of consent for purpose referring §303e SGB V clause 2 number 6: Analysen zur Wirksamkeit sektorenübergreifender Versorgungsformen sowie zur Wirksamkeit von Einzelverträgen der Kranken- und Pflegekassen"
      type: object
      properties:
        decision:
          type: string
          enum: ["permit", "deny"]
    Purpose7Type:
      description: "State of consent for purpose referring §303e SGB V clause 2 number 7: Wahrnehmung von Aufgaben der Gesundheitsberichterstattung, anderer Berichtspflichten des Bundes nach diesem oder dem Elften Buch und der amtlichen Statistik sowie Berichtspflichten der Länder"
      type: object
      properties:
        decision:
          type: string
          enum: ["permit", "deny"]
    Purpose8Type:
      description: "State of consent for purpose referring §303e SGB V clause 2 number 8: Wahrnehmung gesetzlicher Aufgaben in den Bereichen öffentliche Gesundheit und Epidemiologie"
      type: object
      properties:
        decision:
          type: string
          enum: ["permit", "deny"]
    Purpose9Type:
      description: "State of consent for purpose referring §303e SGB V clause 2 number 9: Entwicklung, Weiterentwicklung und Überwachung der Sicherheit von Arzneimitteln, Medizinprodukten, Untersuchungs- und Behandlungsmethoden, Hilfs- und Heilmitteln, digitalen Gesundheits- und Pflegeanwendungen sowie Systemen der Künstlichen Intelligenz im Gesundheitswesen einschließlich des Trainings, der Validierung und des Testens dieser Systeme der Künstlichen Intelligenz"
      type: object
      properties:
        decision:
          type: string
          enum: ["permit", "deny"]
    Purpose10Type:
      description: "State of consent for purpose referring §303e SGB V clause 2 number 10: Nutzenbewertung von Arzneimitteln, Medizinprodukten, Untersuchungs- und Behandlungsmethoden, Hilfs- und Heilmitteln sowie digitalen Gesundheits- und Pflegeanwendungen, Verhandlung von Vergütungsbeträgen oder Festlegung von Höchstbeträgen und Schwellenwerten nach § 134 sowie Vereinbarung oder Festsetzung von Erstattungsbeträgen von Arzneimitteln nach § 130b"
      type: object
      properties:
        decision:
          type: string
          enum: ["permit", "deny"]
    UdpMedicationResponseType:
      allOf:
        - $ref: '#/components/schemas/UdPMedicationAssignmentType'
        - type: object
          required:
            - at
          properties:
            at:
              description: Creation timestamp
              type: string
              format: date-time
              example: 2025-01-01T18:00:00Z
    UdPMedicationAssignmentType:
      description: Properties of one specific user
      type: object
      required:
        - actorId
        - oid
        - displayName
      properties:
        actorId:
          $ref: '#/components/schemas/TelematikIdType'
        oid:
          $ref: '#/components/schemas/OidType'
        displayName:
          $ref: '#/components/schemas/DisplayNameType'
    TelematikIdType:
      type: string
      pattern: '^[1-9][0-9]?-[\x21-\x7E]+$'
      maxLength: 128
      example: 2-883110000118994
    OidType:
      description: A professionOID
      type: string
      pattern: '([0-2])((\.0)|(\.[1-9][0-9]*))*$'
      example: '1.2.276.0.76.4.50'
    DisplayNameType:
      description: A readable name
      type: string
      example: 'Praxis Dr. Annamaria Heckhausén'

    ErrorType:
      description: "Error object with additional information about the occurred error"
      type: object
      properties:
        errorCode:
          description: "Error condition specifier"
          type: string
        errorDetail:
          description: "Additional details regarding the error condition"
          type: string
      required:
        - errorCode

  examples:
    Permit_Pupose1_only:
      summary: Permit purpose 1 only (purpose according §303e SGB V clause 2 number 1)
      value:
          purpose1:
            decision: permit
          purpose2:
            decision: deny
          purpose3:
            decision: deny
          purpose4:
            decision: deny
          purpose5:
            decision: deny
          purpose6:
            decision: deny
          purpose7:
            decision: deny
          purpose8:
            decision: deny
          purpose9:
            decision: deny
          purpose10:
            decision: deny
   
    Get_AllUdpMedication:
      summary: Get all assignments of the user specific policy for the medication service.
      value:
        data:
          - actorId: 2-883110000092414
            oid: 1.2.276.0.76.4.51
            displayName: 'Zahnarztpraxis Norbert Freiherr Schomaker'
            at: 2025-07-01T12:00:00Z
          - actorId: 1-883110000092404
            oid: 1.2.276.0.76.4.50
            displayName: 'Praxis Dr. Annamaria Heckhausén'
            at: 2025-07-02T12:00:00Z
          - actorId: 2-883110000092427
            oid: 1.2.276.0.76.4.51
            displayName: 'Zahnarztpraxis Dr. Alfons Adamiç'
            at: 2025-07-03T12:00:00Z
          - actorId: 3-883110000092469
            oid: 1.2.276.0.76.4.54
            displayName: 'Süd Apotheke'
            at: 2025-07-04T12:00:00Z
    Set_SingleUdpAssignment:
      summary: Set User for 2-883110000092427 to UdpMedication.
      value:
        actorId: 2-883110000092427
        oid: 1.2.276.0.76.4.51
        displayName: 'Zahnarztpraxis Dr. Alfons Adamiç'
    Get_SingleUdpAssignment:
      summary: Get UdpMedication Assignment Details for 2-883110000092427.
      value:
        actorId: 2-883110000092427
        oid: 1.2.276.0.76.4.51
        displayName: 'Zahnarztpraxis Dr. Alfons Adamiç'
        at: 2025-07-03T12:00:00Z