> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TEFCA/QHIN Connectivity — Integration

> Feature ID: CL-16-EN-01 Status: \U0001F4DD Planned -tefca-qhin-connectivity.md Last Updated: 2026-04-09

**Feature ID:** CL-16-EN-01\
**Status:** 📝 Planned\
**Spec:** [CL-16-EN-01-tefca-qhin-connectivity.md](../../../specs/cl/specs/CL-16-EN-01-tefca-qhin-connectivity.md)\
**Last Updated:** 2026-04-09

***

## Overview

CL-16-EN-01 extends CL-16 interoperability with TEFCA/QHIN-specific transport, patient matching, and consent-governed exchange controls. It does not replace CL-16 ownership of the base FHIR/C-CDA framework.

***

## Integration Points

| Dependency | Pattern        | Purpose                                                         |
| ---------- | -------------- | --------------------------------------------------------------- |
| CL-16      | API / Data     | Base FHIR/C-CDA mapping and exchange infrastructure             |
| CL-11      | API / Policy   | Consent and Part 2 redisclosure gating before outbound exchange |
| CL-12      | Data / API     | Care-transition consumers use TEFCA-sourced exchange artifacts  |
| PM-10      | API Contract   | Prior-auth adjacent interoperability alignment                  |
| PF-04      | Event / Audit  | Compliance and operational audit traceability                   |
| PF-11      | Platform Layer | Referenced document storage artifacts for exchanged payloads    |

***

## API Contracts (Planned)

Canonical API stubs live in [API\_CONTRACTS.md#cl-16-en-01-tefca-qhin-api](./API_CONTRACTS.md#cl-16-en-01-tefca-qhin-api). Use those entries as the source of truth for ownership, correlation behavior, and placeholder schema/version TODOs.

* `POST /tefca/qhin/query`
  * Purpose: submit patient record query to connected QHIN.
  * Required fields: `organization_id`, patient match inputs, `purpose_of_use`.
  * Response: normalized match candidates + `correlation_id`.
  * Canonical contract anchor: [POST /tefca/qhin/query](./API_CONTRACTS.md#cl-16-en-01-api-post-tefca-qhin-query) (owner: CL-16-EN-01; TODO schema/versioning retained).

* `POST /tefca/qhin/exchange`
  * Purpose: outbound disclosure operation through QHIN.
  * Required controls: CL-11 consent check, Part 2 redisclosure handling.
  * Response: accepted/blocked/failed status with `correlation_id`.
  * Canonical contract anchor: [POST /tefca/qhin/exchange](./API_CONTRACTS.md#cl-16-en-01-api-post-tefca-qhin-exchange) (owner: CL-16-EN-01; TODO schema/versioning retained).

* `GET /tefca/qhin/exchanges`
  * Purpose: org-scoped exchange monitoring and compliance audit retrieval.
  * Supports filters: status, direction, qhin identifier, date range.
  * Canonical contract anchor: [GET /tefca/qhin/exchanges](./API_CONTRACTS.md#cl-16-en-01-api-get-tefca-qhin-exchanges) (owner: CL-16-EN-01; TODO schema/versioning retained).

***

## Event Contracts (Planned)

Canonical event stubs live in [EVENT\_CONTRACTS.md#cl-16-en-01-tefca-qhin-events](./EVENT_CONTRACTS.md#cl-16-en-01-tefca-qhin-events). Use those entries as the source of truth for publisher/consumer ownership and payload/version placeholders.

| Event Name                    | Publisher   | Consumers                   | Purpose                                               |
| ----------------------------- | ----------- | --------------------------- | ----------------------------------------------------- |
| `cl_tefca_query_submitted`    | CL-16-EN-01 | PF-04, operations analytics | Track query submission volume and provenance          |
| `cl_tefca_exchange_completed` | CL-16-EN-01 | PF-04, CL-12 consumers      | Track successful exchange and downstream availability |
| `cl_tefca_exchange_blocked`   | CL-16-EN-01 | PF-04, compliance workflows | Trace consent/policy blocked exchanges                |

**Payload constraints:** Include IDs and metadata only (`organization_id`, `patient_id`, `correlation_id`, status); no PHI payload bodies in event data.
**Canonical event anchors:** [cl\_tefca\_query\_submitted](./EVENT_CONTRACTS.md#cl-tefca-query-submitted), [cl\_tefca\_exchange\_completed](./EVENT_CONTRACTS.md#cl-tefca-exchange-completed), [cl\_tefca\_exchange\_blocked](./EVENT_CONTRACTS.md#cl-tefca-exchange-blocked).

***

## Security and Compliance

* All operations must enforce tenant scoping (`organization_id`) and RLS on persisted data.
* CL-11 consent checks are mandatory for outbound disclosures.
* Credentials and certificates must be sourced from environment/secrets, never persisted in plain text.
* Logs and events must avoid PHI content and use identifiers/correlation IDs.

***

## Open Items

* Final QHIN vendor endpoint and onboarding playbook selection.
* Operational retry policy for transient failures (manual vs automatic replay).
* Multi-QHIN failover strategy (deferred enhancement).