Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# FHIR R4 per `$operations` HealthLake
Le operazioni FHIR \$1 (chiamate anche «operazioni in dollari») sono funzioni speciali lato server che vanno oltre le operazioni CRUD standard (`Create`,, `Read``Update`,`Delete`) previste dalle specifiche FHIR. Queste operazioni sono identificate dal prefisso «\$1» e consentono l'elaborazione complessa, la trasformazione dei dati e operazioni di massa che sarebbero difficili o inefficienti da eseguire utilizzando chiamate API REST standard. \$1 Le operazioni possono essere richiamate a livello di sistema, a livello di tipo di risorsa o su istanze di risorse specifiche, fornendo modi flessibili per interagire con i dati FHIR. AWS HealthLake supporta più FHIR. `$operations` Si prega di fare riferimento a ogni singola pagina di seguito per ulteriori dettagli.
**Topics**
+ [Funzionamento FHIR R4 `$attribution-status` per HealthLake](reference-fhir-operations-attribution-status.md)
+ [Eliminazione dei tipi di risorse con `$bulk-delete`](reference-fhir-operations-bulk-delete.md)
+ [`$bulk-member-match`operazione per HealthLake](reference-fhir-operations-bulk-member-match.md)
+ [Funzionamento FHIR R4 `$confirm-attribution-list` per HealthLake](reference-fhir-operations-confirm-attribution-list.md)
+ [Funzionamento FHIR R4 `$davinci-data-export` per HealthLake](reference-fhir-operations-davinci-data-export.md)
+ [Generazione di documenti clinici con `$document`](reference-fhir-operations-document.md)
+ [Rimozione permanente di risorse con `$erase`](reference-fhir-operations-erase.md)
+ [Acquisizione dei dati dei pazienti con `Patient/$everything`](reference-fhir-operations-everything.md)
+ [Recupero dei codici con ValueSet `$expand`](reference-fhir-operations-expand.md)
+ [Esportazione di HealthLake dati con FHIR `$export`](reference-fhir-operations-export.md)
+ [`$inquire`Operazione FHIR per HealthLake](reference-fhir-operations-inquire.md)
+ [Recupero dei dettagli concettuali con `$lookup`](reference-fhir-operations-lookup.md)
+ [`$member-add`operazione per HealthLake](reference-fhir-operations-member-add.md)
+ [`$member-match`operazione per HealthLake](reference-fhir-operations-member-match.md)
+ [`$member-remove`operazione per HealthLake](reference-fhir-operations-member-remove.md)
+ [Eliminazione delle risorse del comparto paziente con `$purge`](reference-fhir-operations-purge.md)
+ [`$questionnaire-package`Operazione FHIR per HealthLake](reference-fhir-operations-questionnaire-package.md)
+ [`$submit`Operazione FHIR per HealthLake](reference-fhir-operations-submit.md)
+ [Convalida delle risorse FHIR con `$validate`](reference-fhir-operations-validate.md)
# Funzionamento FHIR R4 `$attribution-status` per HealthLake
Recupera lo stato di attribuzione di un membro specifico, restituendo un pacchetto contenente tutte le risorse di attribuzione relative al paziente. Questa operazione fa parte dell'implementazione [FHIR Member Attribution (ATR](https://build.fhir.org/ig/HL7/davinci-atr/spec.html)) List IG 2.1.0.
## Endpoint
```
POST [base]/Group/[id]/$attribution-status
```
## Parametri della richiesta
L'operazione accetta i seguenti parametri opzionali:
| Parametro | Tipo | Description |
| --- | --- | --- |
| memberId | Identificatore | Il MemberId membro per il quale è richiesto lo stato di attribuzione |
| Riferimento per il paziente | Documentazione di riferimento | Riferimento alla risorsa per i pazienti nel sistema del produttore |
**Nota**
`memberId`O `patientReference` può essere fornito, o entrambi a scopo di convalida.
## Richiesta di esempio
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "memberId",
"valueIdentifier": {
"system": "http://example.org",
"value": "MBR123456789"
}
},
{
"name": "patientReference",
"valueReference": {
"reference": "Patient/patient-123",
"display": "John Doe"
}
}
]
}
```
## Risposta
Restituisce un pacchetto contenente risorse di attribuzione relative al paziente:
| Risorsa | Cardinalità | Location (Ubicazione) |
| --- | --- | --- |
| Paziente | 1..1 | Group.Member.Entity |
| Copertura | 0.1.. | group.member.extension: CoverageReference |
| Organization/Practitioner/PractitionerRole | 0.1.. | group.member.extension: AttributedProvider |
| Qualsiasi risorsa | 0.1.. | group.member.extension: dati associati |
### Risposta di esempio
```
{
"resourceType": "Bundle",
"id": "bundle-response",
"meta": {
"lastUpdated": "2014-08-18T01:43:33Z"
},
"type": "collection",
"entry": [
{
"fullUrl": "http://example.org/fhir/Patient/12423",
"resource": {
"resourceType": "Patient",
"id": "12423",
"meta": {
"versionId": "1",
"lastUpdated": "2014-08-18T01:43:31Z"
},
"active": true,
"name": [
{
"use": "official",
"family": "Chalmers",
"given": ["Peter", "James"]
}
],
"gender": "male",
"birthDate": "1974-12-25"
}
},
{
"fullUrl": "http://example.org/fhir/Coverage/123456",
"resource": {
"resourceType": "Coverage",
"id": "1"
// ... additional Coverage resource details
}
},
{
"fullUrl": "http://example.org/fhir/Organization/666666",
"resource": {
"resourceType": "Organization",
"id": "2"
// ... additional Organization resource details
}
}
]
}
```
## Gestione errori
L'operazione gestisce le seguenti condizioni di errore:
| Errore | Stato HTTP | Description |
| --- | --- | --- |
| Richiesta di operazione non valida | 400 | Parametri o struttura della richiesta non conformi |
| Risorsa di gruppo non trovata | 404 | L'ID di gruppo specificato non esiste |
| Risorsa per il paziente non trovata | 404 | Il riferimento del paziente specificato non esiste |
## Autorizzazione e sicurezza
Requisiti di SMART
I clienti devono disporre dei privilegi appropriati per leggere le risorse del Gruppo e le relative risorse di attribuzione
I meccanismi di autorizzazione FHIR standard si applicano a tutte le operazioni
# Eliminazione dei tipi di risorse con `$bulk-delete`
AWS HealthLake supporta l'`$bulk-delete`operazione, abilitando l'eliminazione di tutte le risorse di un tipo specifico all'interno di un datastore. Questa operazione è particolarmente utile quando è necessario:
+ Effettuare verifiche e pulizie stagionali
+ Gestisci il ciclo di vita dei dati su larga scala
+ Rimuovi tipi di risorse specifici
+ Rispetta le politiche di conservazione dei dati
## Utilizzo
L'`$bulk-delete`operazione può essere richiamata utilizzando i metodi POST:
```
POST [base]/[ResourceType]/$bulk-delete?isHardDelete=false&deleteAuditEvent=true
```
## Parameters
| Parametro | Tipo | Obbligatorio | Predefinita | Description |
| --- | --- | --- | --- | --- |
| isHardDelete | booleano | No | false | Se impostato su true, rimuove definitivamente le risorse dallo storage |
| deleteAuditEvent | booleano | No | true | Se impostato su true, elimina gli eventi di controllo associati |
| \$1since | stringa | No | Ora di creazione del datastore | Una volta inserito, seleziona l'orario limite iniziale per trovare le risorse in base all'ora dell'ultima modifica. Non può essere utilizzato con start o end |
| start | stringa | No | Ora di creazione del datastore | Una volta inserito, seleziona l'orario limite per la ricerca delle risorse in base all'ora dell'ultima modifica. Può essere usato con fine |
| end | stringa | No | Ora di invio del lavoro | Una volta inserito, seleziona l'orario limite finale per trovare le risorse in base all'ora dell'ultima modifica |
## Esempi
**Richiesta di esempio**
```
POST [base]/Observation/$bulk-delete?isHardDelete=false
```
**Risposta di esempio**
```
{
"jobId": "jobId",
"jobStatus": "SUBMITTED"
}
```
## Stato di un processo
Per verificare lo stato di un processo di eliminazione in blocco:
```
GET [base]/$bulk-delete/[jobId]
```
L'operazione restituisce informazioni sullo stato del lavoro:
```
{
"datastoreId": "datastoreId",
"jobId": "jobId",
"status": "COMPLETED",
"submittedTime": "2025-10-09T15:09:51.336Z"
}
```
## Comportamento
L'`$bulk-delete`operazione:
1. Processi in modo asincrono per gestire grandi volumi di risorse
1. Mantiene le transazioni ACID per l'integrità dei dati
1. Fornisce il monitoraggio dello stato del lavoro con il conteggio delle eliminazioni delle risorse
1. Supporta sia la modalità di cancellazione temporanea che quella definitiva
1. Include una registrazione di controllo completa delle attività di eliminazione
1. Consente l'eliminazione selettiva delle versioni storiche e degli eventi di controllo
## Registrazione di audit
Le `$bulk-delete` operazioni vengono registrate come Start FHIRBulk DeleteJob e Descrivi FHIRBulk DeleteJob con informazioni dettagliate sull'operazione.
## Limitazioni
+ Se `isHardDelete` è impostata su true, le risorse eliminate definitivamente non verranno visualizzate nei risultati di ricerca o nelle query. `_history`
+ Le risorse eliminate tramite questa operazione potrebbero essere temporaneamente inaccessibili durante l'elaborazione
+ La misurazione dello storage viene regolata solo in base alle versioni storiche: deleteVersionHistory =false non aggiusterà lo storage del datastore
# `$bulk-member-match`operazione per HealthLake
AWS HealthLake supporta l'`$bulk-member-match`operazione per l'elaborazione asincrona delle richieste di abbinamento di più membri. Questa operazione consente alle organizzazioni sanitarie di abbinare in modo efficiente gli identificatori univoci di centinaia di membri di diversi sistemi sanitari utilizzando informazioni demografiche e di copertura in un'unica richiesta di massa. [Questa funzionalità è essenziale per lo scambio di payer-to-payer dati su larga scala, le transizioni tra i membri e i requisiti di conformità CMS e segue le specifiche FHIR.](https://build.fhir.org/ig/HL7/davinci-epdx/OperationDefinition-BulkMemberMatch.html)
**Nota**
L'`$bulk-member-match`operazione si basa su una specifica FHIR sottostante che è attualmente sperimentale e soggetta a modifiche. Man mano che le specifiche si evolvono, il comportamento e l'interfaccia di questa API verranno aggiornati di conseguenza. Si consiglia agli sviluppatori di monitorare le note di HealthLake rilascio di AWS e gli aggiornamenti delle specifiche FHIR pertinenti per rimanere informati su eventuali modifiche che potrebbero influire sulle loro integrazioni.
Questa operazione è particolarmente utile quando è necessario:
+ Elaborare l'abbinamento dei membri su larga scala durante i periodi di iscrizione aperti
+ Facilita le transizioni di massa dei membri tra i paganti
+ Supporta i requisiti di scambio di dati di conformità CMS su larga scala
+ Abbina in modo efficiente le coorti di membri attraverso le reti sanitarie
+ Riduci al minimo le chiamate API e migliora l'efficienza operativa per scenari di abbinamento ad alto volume
## Utilizzo
L'`$bulk-member-match`operazione è un'operazione asincrona richiamata sulle risorse del gruppo utilizzando il metodo POST:
```
POST [base]/Group/$bulk-member-match
```
Dopo aver inviato una richiesta di corrispondenza in blocco, puoi verificare lo stato del lavoro utilizzando:
```
GET [base]/$bulk-member-match-status/{jobId}
```
## Parametri supportati
HealthLake supporta i seguenti parametri FHIR: `$bulk-member-match`
| Parametro | Tipo | Campo obbligatorio | Description |
| --- | --- | --- | --- |
| `MemberPatient` | Paziente | Sì | Risorsa per il paziente contenente informazioni demografiche relative al membro da abbinare. |
| `CoverageToMatch` | Copertura | Sì | Risorsa di copertura che verrà utilizzata per il confronto con i record esistenti. |
| `CoverageToLink` | Copertura | No | Risorsa di copertura da collegare durante il processo di abbinamento. |
| `Consent` | Consenso | Sì | Viene inoltre memorizzata la risorsa di consenso a fini di autorizzazione. Questa operazione è diversa dalla singola `$member-match` operazione in cui *non* è richiesto il consenso. |
## Richiesta POST per inviare in blocco un'offerta di lavoro abbinata a un membro
L'esempio seguente mostra una richiesta POST per inviare un lavoro collettivo riservato ai membri. Ogni membro è racchiuso in un `MemberBundle` parametro contenente le risorse obbligatorie e `Consent` le risorse `MemberPatient``CoverageToMatch`, oltre a un parametro opzionale. `CoverageToLink`
```
POST [base]/Group/$bulk-member-match
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "MemberBundle",
"part": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"identifier": [
{
"system": "http://example.org/patient-id",
"value": "patient-0"
}
],
"name": [
{
"family": "Smith",
"given": ["James"]
}
],
"gender": "male",
"birthDate": "1950-01-01"
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"status": "active",
"identifier": [
{
"system": "http://example.org/coverage-id",
"value": "cov-0"
}
],
"subscriberId": "sub-0",
"beneficiary": {
"reference": "Patient/patient123"
},
"relationship": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code": "self"
}
]
},
"payor": [
{
"reference": "Organization/org123"
}
]
}
},
{
"name": "Consent",
"resource": {
"resourceType": "Consent",
"status": "active",
"scope": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentscope",
"code": "patient-privacy"
}
]
},
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "IDSCL"
}
]
}
],
"patient": {
"reference": "Patient/patient123"
},
"performer": [
{
"reference": "Patient/patient123"
}
],
"sourceReference": {
"reference": "http://example.org/DocumentReference/consent-source"
},
"policy": [
{
"uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#regular"
}
],
"provision": {
"type": "permit",
"period": {
"start": "2024-01-01",
"end": "2025-12-31"
},
"actor": [
{
"role": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
"code": "performer"
}
]
},
"reference": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "9876543210"
},
"display": "Old Health Plan"
}
},
{
"role": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "IRCP"
}
]
},
"reference": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "0123456789"
},
"display": "New Health Plan"
}
}
],
"action": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentaction",
"code": "disclose"
}
]
}
]
}
}
},
{
"name": "CoverageToLink",
"resource": {
"resourceType": "Coverage",
"status": "active",
"identifier": [
{
"system": "http://example.org/coverage-link-id",
"value": "cov-link-0"
}
],
"subscriberId": "new-sub-0",
"beneficiary": {
"reference": "Patient/patient123"
},
"relationship": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code": "self"
}
]
},
"payor": [
{
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "0123456789"
},
"display": "New Health Plan"
}
]
}
}
]
}
]
}
```
## Risposta al lavoro completata con output
Una volta completato il lavoro, la risposta include i metadati del lavoro e una risorsa FHIR Parameters contenente tre risorse di gruppo che classificano i risultati delle partite.
```
{
"datastoreId": "datastoreId",
"jobId": "jobId",
"status": "COMPLETED",
"submittedTime": "2026-03-20T18:45:26.321Z",
"numberOfMembers": 3,
"numberOfMembersProcessedSuccessfully": 3,
"numberOfMembersWithCustomerError": 0,
"numberOfMembersWithServerError": 0,
"output": {
"resourceType": "Parameters",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/pdex-parameters-multi-member-match-bundle-out"
]
},
"parameter": [
{
"name": "MatchedMembers",
"resource": {
"resourceType": "Group",
"id": "group1",
"text": {
"status": "generated",
"div": "Matched members group
"
},
"contained": [
{
"resourceType": "Patient",
"id": "1",
"identifier": [
{
"system": "http://example.org/patient-id",
"value": "patient-0"
}
],
"name": [
{
"family": "Smith",
"given": ["James"]
}
],
"gender": "male",
"birthDate": "1950-01-01"
}
],
"type": "person",
"actual": true,
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS",
"code": "match",
"display": "Matched"
}
]
},
"quantity": 1,
"member": [
{
"entity": {
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters",
"valueReference": {
"reference": "#1"
}
}
],
"reference": "Patient/patient123"
}
}
]
}
},
{
"name": "NonMatchedMembers",
"resource": {
"resourceType": "Group",
"id": "Group2",
"text": {
"status": "generated",
"div": "Non-matched members group
"
},
"contained": [
{
"resourceType": "Patient",
"id": "1",
"identifier": [
{
"system": "http://example.org/patient-id",
"value": "patient-501"
}
],
"name": [
{
"family": "Carter",
"given": ["Emily"]
}
],
"gender": "female",
"birthDate": "1985-06-15"
}
],
"type": "person",
"actual": true,
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS",
"code": "nomatch",
"display": "Not Matched"
}
]
},
"quantity": 1,
"member": [
{
"entity": {
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters",
"valueReference": {
"reference": "#1"
}
}
],
"reference": "Patient/patient123"
}
}
]
}
},
{
"name": "ConsentConstrainedMembers",
"resource": {
"resourceType": "Group",
"id": "group3",
"text": {
"status": "generated",
"div": "Consent constrained members group
"
},
"contained": [
{
"resourceType": "Patient",
"id": "1",
"identifier": [
{
"system": "http://example.org/patient-id",
"value": "patient-502"
}
],
"name": [
{
"family": "Nguyen",
"given": ["David"]
}
],
"gender": "male",
"birthDate": "1972-11-22"
}
],
"type": "person",
"actual": true,
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS",
"code": "consentconstraint",
"display": "Consent Constraint"
}
]
},
"quantity": 1,
"member": [
{
"entity": {
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters",
"valueReference": {
"reference": "#1"
}
}
],
"reference": "Patient/123"
}
}
]
}
}
]
}
}
```
## Risorse di Output Group
Il lavoro completato restituisce una risorsa Parameters contenente tre risorse di gruppo:
**MatchedMembers Group** (Gruppo)
Contiene i riferimenti dei pazienti per tutti i membri abbinati correttamente e non è classificato come vincolo di consenso.
Il `Group.quantity` campo contiene il numero totale di membri in ciascuno dei rispettivi gruppi.
**NonMatchedMembers Group** (Gruppo)
Contiene riferimenti ai membri per i quali non è stata trovata alcuna corrispondenza o sono state identificate più corrispondenze.
**ConsentConstrainedMembers Group** (Gruppo)
Contiene i riferimenti dei pazienti per tutti i membri abbinati correttamente, laddove i vincoli di consenso impediscano la condivisione dei dati. Una risorsa di consenso è considerata limitata quando sono presenti entrambe le seguenti condizioni:
+ **L'URI della policy termina con `#sensitive`**: questo è il segnale più chiaro e diretto. Il pagante richiedente dice esplicitamente: «I dati di questo utente sono sensibili, trattali con cura».
```
"policy": [{ "uri": "...hrex-consent.html#sensitive" }]
```
+ **Il tipo di fornitura di primo livello è `deny`**: il membro ha ampiamente rifiutato la condivisione dei dati.
```
"provision": { "type": "deny" }
```
## Integrazione con \$1 davinci-data-export
La risorsa di MatchedMembers gruppo restituita da `$bulk-member-match` può essere utilizzata direttamente con l'`$davinci-data-export`operazione per recuperare i dati di massa dei membri:
```
POST [base]/Group/{matched-group-id}/$davinci-data-export
GET [base]/Group/{matched-group-id}
```
Questa integrazione consente flussi di lavoro efficienti in cui si identificano innanzitutto i membri corrispondenti in blocco, quindi si esportano le relative cartelle cliniche complete utilizzando la risorsa di Gruppo risultante.
## Caratteristiche prestazionali
L'`$bulk-member-match`operazione è progettata per l'elaborazione di grandi volumi e viene eseguita in modo asincrono:
+ **Concorrenza**: massimo 5 operazioni simultanee per archivio dati.
+ **Scalabilità**: gestisce fino a 500 membri per richiesta (limite di payload di 5 MB).
+ **Operazioni parallele**: compatibile con operazioni simultanee di importazione, esportazione o eliminazione in blocco.
## Autorizzazione
L'API utilizza il protocollo di autorizzazione SMART on FHIR con i seguenti ambiti richiesti:
+ `system/Patient.read`— Necessario per cercare e abbinare le risorse dei pazienti.
+ `system/Coverage.read`— Necessario per convalidare le informazioni sulla copertura.
+ `system/Group.write`— Necessario per creare risorse del Gruppo di risultati.
+ `system/Organization.read`— Condizionale, obbligatorio se la copertura si riferisce alle organizzazioni.
+ `system/Practitioner.read`— Condizionale, obbligatorio se la copertura si riferisce ai professionisti.
+ `system/PractitionerRole.read`— Condizionale, obbligatorio se la copertura si riferisce ai ruoli dei professionisti.
+ `system/Consent.write`— Condizionale, obbligatorio se vengono fornite risorse per il consenso.
L'operazione supporta anche l'autorizzazione AWS IAM Signature Version 4 (SigV4) per l'accesso programmatico.
## Gestione degli errori
L'operazione gestisce le seguenti condizioni di errore:
+ **400 Richiesta errata**: formato di richiesta non valido, parametri obbligatori mancanti o il payload supera i limiti di dimensione (500 membri o 5 MB).
+ **422 Entità non processabile**: errori di elaborazione durante l'esecuzione del lavoro.
+ **Errori individuali dei membri**: quando un membro specifico non viene elaborato, l'operazione continua con i membri rimanenti e include i dettagli dell'errore nel NonMatchedMembers Gruppo con i codici motivo appropriati. Ad esempio, se `MemberBundle` a un paziente manca il `birthDate` parametro, verrà restituito il seguente errore:
```
"errors": [
{
"memberIndex": 1,
"jsonBlob": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "invalid",
"diagnostics": "MemberPatient.birthDate is required"
}
],
"statusCode": 400
}
}
]
```
I dettagli sull'errore sono disponibili tramite l'endpoint di polling dello stato e includono:
+ `numberOfMembersWithCustomerError`: Numero di membri con errori di convalida o di input.
+ `numberOfMembersWithServerError`: Numero di membri con errori di elaborazione sul lato server.
## Operazioni correlate
+ [`$member-match`operazione per HealthLake](reference-fhir-operations-member-match.md)— Operazione di abbinamento dei singoli membri.
+ [Funzionamento FHIR R4 `$davinci-data-export` per HealthLake](reference-fhir-operations-davinci-data-export.md)— Esportazione di dati in blocco utilizzando le risorse del Gruppo.
+ [FHIR R4 per `$operations` HealthLake](reference-fhir-operations.md)— Elenco completo delle operazioni supportate.
# Funzionamento FHIR R4 `$confirm-attribution-list` per HealthLake
Indica a un produttore che il consumatore non ha più modifiche da apportare all'elenco di attribuzione. Questa operazione finalizza l'elenco di attribuzione rimuovendo i membri inattivi dall'elenco, modificando lo stato in «finale» e confermando l'operazione. Questa operazione fa parte dell'implementazione [FHIR Member Attribution (](https://build.fhir.org/ig/HL7/davinci-atr/spec.html)ATR) List IG 2.1.0.
## Endpoint
```
POST [base]/Group/[id]/$confirm-attribution-list
```
## Richiesta
Nessun parametro richiesto.
```
POST [base]/Group/[id]/$confirm-attribution-list
```
## Risposta
Restituisce HTTP 201 con un messaggio di conferma.
### Risposta di esempio
```
HTTP Status Code: 201
{
"resourceType": "Parameters",
"parameter": [
{
"name": "message",
"valueString": "Accepted."
}
]
}
```
## Stato del gruppo dopo la conferma
Dopo la conferma avvenuta con successo, lo stato della lista di attribuzione della risorsa del Gruppo sarà impostato su «finale»:
```
{
"resourceType": "Group",
"id": "fullexample",
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-atr/StructureDefinition/ext-attributionListStatus",
"valueCode": "final"
}
]
// ... other Group properties
}
```
## Gestione errori
L'operazione gestisce le seguenti condizioni di errore:
| Errore | Stato HTTP | Description |
| --- | --- | --- |
| Richiesta di operazione non valida | 400 | Parametri o struttura della richiesta non conformi |
| Risorsa di gruppo non trovata | 404 | L'ID di gruppo specificato non esiste |
## Autorizzazione e sicurezza
Requisiti di SMART
I clienti devono disporre dei privilegi appropriati per leggere le risorse del Gruppo e le relative risorse di attribuzione
Infatti`$confirm-attribution-list`, i client devono disporre anche dei privilegi di scrittura per modificare le risorse del Gruppo
I meccanismi di autorizzazione FHIR standard si applicano a tutte le operazioni
# Funzionamento FHIR R4 `$davinci-data-export` per HealthLake
L'`$davinci-data-export`operazione è un'operazione FHIR asincrona da cui è possibile esportare dati sanitari. AWS HealthLake Questa operazione supporta diversi tipi di esportazione, tra cui Member Attribution (ATR), PDex Provider Access e Member Access. Payer-to-Payer APIs È una versione specializzata del `$export` funzionamento standard FHIR, progettata per soddisfare i requisiti delle guide all'implementazione. DaVinci
## Caratteristiche chiave
+ *Elaborazione asincrona*: segue lo schema di richiesta asincrona FHIR standard
+ Esportazione a *livello di gruppo: esporta* i dati per i membri all'interno di una specifica risorsa del gruppo
+ *Diversi tipi di esportazione*: supporta ATR (Member Attribution), PDex Provider Access e Member Access Payer-to-Payer APIs
+ *Profile Support completo*: include US Core, CARIN Blue Button e PDex profili
+ *Filtraggio flessibile*: supporta il filtraggio per pazienti, tipi di risorse e intervalli di tempo
+ *Output NDJSON*: fornisce dati in formato JSON delimitato da nuove righe
## Operazione Endpoint
```
GET [base]/Group/[id]/$davinci-data-export
POST [base]/Group/[id]/$davinci-data-export
```
## Parametri della richiesta
| Parametro | Cardinalità | Description |
| --- | --- | --- |
| patient | 0.. \$1 | Membri specifici di cui esportare i dati. Se omesso, tutti i membri del Gruppo vengono esportati. |
| \$1type | 0.1. | Elenco delimitato da virgole di tipi di risorse FHIR da esportare. |
| \$1since | 0.1.. | Includi solo le risorse aggiornate dopo questa data e ora. |
| \$1until | 0.1.. | Includi solo le risorse aggiornate prima di questa data e ora. |
| exportType | 0.1.. | Tipo di esportazione da eseguire. Valori validi: hl7.fhir.us.davinci-atr, hl7.fhir.us.davinci-pdex, hl7.fhir.us.davinci-pdex.p2p, hl7.fhir.us.davinci-pdex.member. Default: hl7.fhir.us.davinci-atr. |
| \$1includeEOB2xWoFinancial | 0.1. | Specifica se includere le ExplanationOfBenefit risorse CARIN BB 2.x con i dati finanziari rimossi. Default: false. |
### Tipi di risorsa supportati
I tipi di risorse supportati dipendono dal tipo di esportazione specificato. Per le esportazioni ATR, sono supportati i seguenti tipi di risorse:
+ `Group`
+ `Patient`
+ `Coverage`
+ `RelatedPerson`
+ `Practitioner`
+ `PractitionerRole`
+ `Organization`
+ `Location`
Per PDex le esportazioni (Provider Access e Member Access), oltre ai tipi precedenti, sono supportati tutti i tipi di risorse cliniche e relative ai reclami. Payer-to-Payer Per un elenco completo dei tipi di risorse supportati, consulta la [US Core Implementation Guide (STU 6.1)](https://hl7.org/fhir/us/core/STU6.1/), la [CARIN Blue Button Implementation Guide](https://hl7.org/fhir/us/carin-bb/) e la [Da Vinci Prior Authorization Support](https://hl7.org/fhir/us/davinci-pas/) Implementation Guide.
## Tipi di esportazione
L'`$davinci-data-export`operazione supporta i seguenti tipi di esportazione. È possibile specificare il tipo di esportazione utilizzando il `exportType` parametro.
| Tipo di esportazione | Scopo | Ambito dei dati | Limite temporale |
| --- | --- | --- | --- |
| hl7.fhir.us.davinci-atr | Elenco di attribuzione dei membri | Risorse relative all'attribuzione | Nessuno |
| hl7.fhir.us.davinci-pdex | API Provider Access | Dati clinici e relativi ai reclami relativi ai pazienti attribuiti | 5 anni |
| hl7.fhir.us.davinci-pdex.p2p | Payer-to-Payer Scambio | Dati storici dei membri per le transizioni assicurative | 5 anni |
| hl7.fhir.us.davinci-pdex.member | API di accesso ai membri | Dati sanitari propri del socio | 5 anni |
**Nota**
Per PDex le esportazioni, il limite temporale di 5 anni non si applica ai tipi di risorse ATR (`Group`,,`Patient`,`Coverage`,`RelatedPerson`, `Practitioner``PractitionerRole`,`Organization`). `Location` Queste risorse sono sempre incluse indipendentemente dall'età.
### ATR (hl7.fhir.us.davinci-atr)
Con il tipo di esportazione ATR, puoi esportare i dati della Member Attribution List. Utilizzate questo tipo di esportazione per recuperare risorse relative all'attribuzione per i membri di un gruppo. Per ulteriori informazioni, consulta l'operazione di esportazione ATR [Da Vinci](https://build.fhir.org/ig/HL7/davinci-atr/OperationDefinition-davinci-data-export.html).
Tipi di risorsa supportati
`Group`, `Patient`, `Coverage`, `RelatedPerson`, `Practitioner`, `PractitionerRole`, `Organization`, `Location`
Filtraggio temporale
Non viene applicato alcun filtro temporale. Tutte le risorse corrispondenti vengono esportate indipendentemente dalla data.
### PDex Tipi di esportazione
Tutti i tipi di PDex esportazione condividono gli stessi profili e la stessa logica di filtraggio supportati. Per ulteriori informazioni, consulta l'API [Da Vinci PDex Provider Access](https://build.fhir.org/ig/HL7/davinci-epdx/provider-access-api.html). Sono supportati i seguenti profili:
+ US Core 3.1.1, 6.1.0 e 7.0.0
+ PDex Autorizzazione preventiva (non supportata per l'accesso ai membri)
+ CARIN BB 2.x Profili di base: ospedaliero istituzionale, ambulatoriale istituzionale, professionale NonClinician, orale, farmaceutico
Accesso al fornitore () `hl7.fhir.us.davinci-pdex`
Consente ai provider in rete di recuperare i dati dei pazienti per i pazienti attribuiti.
Payer-to-Payer (`hl7.fhir.us.davinci-pdex.p2p`)
Consente lo scambio di dati tra i pagatori quando un paziente cambia assicurazione.
Accesso per i membri () `hl7.fhir.us.davinci-pdex.member`
Consente ai membri di accedere ai propri dati sanitari. Questo tipo di esportazione può includere dati finanziari nelle risorse relative ai reclami.
## Logica di supporto e inclusione del profilo
Per PDex le esportazioni, l'`$davinci-data-export`operazione utilizza le dichiarazioni di profilo nell'`meta.profile`elemento per determinare quali risorse includere nell'esportazione.
### ExplanationOfBenefit Gestione delle risorse
`ExplanationOfBenefit`Le risorse (EOB) sono incluse o escluse dalle PDex esportazioni in base alle loro `meta.profile` dichiarazioni:
+ ExplanationOfBenefit le risorse con un profilo CARIN BB 1.x sono escluse dall'esportazione.
+ ExplanationOfBenefit le risorse senza `meta.profile` set sono escluse dall'esportazione.
+ ExplanationOfBenefit le risorse con un profilo CARIN BB 2.x Basis sono sempre incluse.
+ ExplanationOfBenefit le risorse con un profilo CARIN BB 2.x che contiene dati finanziari sono escluse per impostazione predefinita. Quando `_includeEOB2xWoFinancial=true` è impostato, vengono incluse con i dati finanziari rimossi e la risorsa viene trasformata nel profilo Basis corrispondente.
+ ExplanationOfBenefit le risorse con un profilo di autorizzazione PDex preventiva sono sempre incluse.
### Trasformazione dei dati finanziari
Una volta impostata`_includeEOB2xWoFinancial=true`, l'operazione trasforma le ExplanationOfBenefit risorse [CARIN BB 2.x](https://hl7.org/fhir/us/carin-bb/) nei profili Basis corrispondenti rimuovendo i dati finanziari. Ad esempio, una `C4BB ExplanationOfBenefit Oral` risorsa viene trasformata in`C4BB ExplanationOfBenefit Oral Basis`, il che rimuove i dati finanziari dal record in base alla specifica FHIR.
I seguenti elementi di dati finanziari vengono rimossi durante la trasformazione:
+ Tutte le suddivisioni sugli elementi `total`
+ Tutti gli `adjudication` elementi con slice `amounttype`
+ Tutti gli `item.adjudication` elementi con informazioni sulla quantità
L'operazione aggiorna anche i metadati del profilo durante la trasformazione:
+ `meta.profile`viene aggiornato all'URL canonico del profilo Basis
+ La versione è aggiornata alla versione CARIN BB 2.x Basis
+ Le risorse esistenti nell'archivio dati non vengono modificate
+ Le risorse esportate non vengono salvate in modo persistente nell'archivio dati
### Regole di rilevamento del profilo
L'operazione utilizza le seguenti regole per rilevare e convalidare i profili:
+ Il rilevamento della versione si basa sul codice canonico `meta.profile` URLs
+ Una risorsa viene inclusa se UNO QUALSIASI dei suoi profili dichiarati soddisfa i criteri di esportazione
+ La convalida del profilo avviene durante l'elaborazione dell'esportazione
## Filtraggio temporale quinquennale per le esportazioni PDex
Per tutti i tipi di PDex esportazione, HealthLake applica un filtro temporale di 5 anni basato sull'ultimo aggiornamento della risorsa. Il filtro temporale si applica a tutte le risorse ad eccezione dei seguenti tipi di risorse di attribuzione principali, che vengono sempre esportati indipendentemente dall'età:
+ `Patient`
+ `Coverage`
+ `Organization`
+ `Practitioner`
+ `PractitionerRole`
+ `RelatedPerson`
+ `Location`
+ `Group`
Queste risorse amministrative e demografiche sono esenti perché forniscono un contesto essenziale per i dati esportati. Le esportazioni ATR non sono soggette ad alcun filtro temporale.
## Richieste di esempio
Gli esempi seguenti mostrano come avviare processi di esportazione per diversi tipi di esportazione.
*Esportazione ATR*
```
GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Group,Patient,Coverage,Practitioner,Organization&exportType=hl7.fhir.us.davinci-atr
POST https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Group,Patient,Coverage,Practitioner,Organization&exportType=hl7.fhir.us.davinci-atr
Content-Type: application/json
{
"DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role",
"JobName": "attribution-export-job",
"OutputDataConfig": {
"S3Configuration": {
"S3Uri": "s3://your-export-bucket/EXPORT-JOB",
"KmsKeyId": "arn:aws:kms:region:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
}
```
*Esportazione di Provider Access con ExplanationOfBenefit rimozione dei dati finanziari*
```
GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Patient,Observation,Condition,MedicationRequest,ExplanationOfBenefit&exportType=hl7.fhir.us.davinci-pdex&_includeEOB2xWoFinancial=true
```
*Payer-to-Payer esportazione*
```
GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Patient,Coverage,ExplanationOfBenefit,Condition,Procedure&exportType=hl7.fhir.us.davinci-pdex.p2p&_includeEOB2xWoFinancial=true
```
*Esportazione di Member Access per un paziente specifico*
```
GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Patient,Observation,Condition,ExplanationOfBenefit,MedicationRequest&exportType=hl7.fhir.us.davinci-pdex.member&patient=Patient/example-patient-id
```
## Risposta di esempio
```
{
"datastoreId": "eaee622d8406b41eb86c0f4741201ff9",
"jobStatus": "SUBMITTED",
"jobId": "48d7b91dae4a64d00d54b70862f33f61"
}
```
## Relazioni con le risorse
L'operazione esporta le risorse in base alle loro relazioni all'interno dell'Elenco di attribuzione dei membri:
```
Group (Attribution List)
├── Patient (Members)
├── Coverage → RelatedPerson (Subscribers)
├── Practitioner (Attributed Providers)
├── PractitionerRole → Location
└── Organization (Attributed Providers)
```
### Fonti di risorse
| Risorsa | Ubicazione della fonte | Description |
| --- | --- | --- |
| Patient | Group.member.entity | I pazienti che sono membri della lista di attribuzione |
| Coverage | Group.member.extension:coverageReference | Copertura che ha portato all'iscrizione dei pazienti |
| Organization | Group.member.extension:attributedProvider | Organizzazioni a cui vengono attribuiti i pazienti |
| Practitioner | Group.member.extension:attributedProvider | Professionisti individuali a cui vengono attribuiti i pazienti |
| PractitionerRole | Group.member.extension:attributedProvider | Ruoli professionali a cui vengono attribuiti i pazienti |
| RelatedPerson | Coverage.subscriber | Abbonati alla copertura |
| Location | PractitionerRole.location | Sedi associate ai ruoli professionali |
| Group | Endpoint di input | La lista di attribuzione stessa |
## Gestione del Job
Verifica lo stato del lavoro
`GET [base]/export/[job-id]`
Annullamento di un processo
`DELETE [base]/export/[job-id]`
### Ciclo di vita del processo
+ `SUBMITTED`- Il lavoro è stato ricevuto e messo in coda
+ `IN_PROGRESS`- Job è in fase di elaborazione attiva
+ `COMPLETED`- Job terminato con successo, file disponibili per il download
+ `FAILED`- Job ha riscontrato un errore
## Formato di output
+ *Formato di file*: NDJSON (Newline Delimited JSON)
+ *Organizzazione dei file*: file separati per ogni tipo di risorsa
+ *Estensione del file*: .ndjson
+ *Posizione: bucket* e percorso S3 specificati
## Gestione errori
L'operazione restituisce HTTP 400 Bad Request con un OperationOutcome per le seguenti condizioni:
Errori di autorizzazione
Il ruolo IAM specificato in `DataAccessRoleArn` non dispone di autorizzazioni sufficienti per eseguire l'operazione di esportazione. Per l'elenco completo delle autorizzazioni S3 e KMS richieste, consulta [Configurazione](getting-started-setting-up.md#setting-up-export-permissions) delle autorizzazioni per i lavori di esportazione.
Errori di convalida dei parametri
+ Il `patient` parametro non è formattato come `Patient/id,Patient/id,...`
+ Uno o più riferimenti ai pazienti non sono validi o non appartengono al gruppo specificato
+ Il valore del `exportType` parametro non è un tipo di esportazione supportato
+ Il `_type` parametro contiene tipi di risorse che non sono supportati per il tipo di esportazione specificato
+ Nel `_type` parametro mancano i tipi di risorse richiesti (`Group`,`Patient`,`Coverage`) per il tipo di `hl7.fhir.us.davinci-atr` esportazione
+ Il valore del `_includeEOB2xWoFinancial` parametro non è un valore booleano valido
Errori di convalida delle risorse
+ La risorsa di gruppo specificata non esiste nell'archivio dati
+ La risorsa di gruppo specificata non ha membri
+ Uno o più membri del gruppo fanno riferimento a risorse per i pazienti che non esistono nell'archivio dati
## Sicurezza e autorizzazione
+ Si applicano i meccanismi di autorizzazione FHIR standard
+ Il ruolo di accesso ai dati deve disporre delle autorizzazioni IAM richieste per le operazioni S3 e KMS. Per l'elenco completo delle autorizzazioni richieste, consulta [Configurazione](getting-started-setting-up.md#setting-up-export-permissions) delle autorizzazioni per i lavori di esportazione.
## Best practice
+ *Selezione del tipo di risorsa*: richiedete solo i tipi di risorse necessari per ridurre al minimo le dimensioni di esportazione e i tempi di elaborazione
+ *Filtraggio basato sul tempo*: utilizza il `_since` parametro per le esportazioni incrementali
+ *Filtraggio dei pazienti*: utilizza il `patient` parametro quando sono necessari solo i dati per membri specifici
+ *Job Monitoring*: controlla regolarmente lo stato del lavoro per esportazioni di grandi dimensioni
+ *Gestione degli errori*: Implementa una logica di ripetizione corretta per i lavori non riusciti
+ *Consapevolezza del filtro temporale*: per PDex le esportazioni, considera il filtro temporale quinquennale quando selezioni i tipi di risorse
+ *Rimozione dei dati finanziari*: da utilizzare `_includeEOB2xWoFinancial=true` quando sono necessari i dati relativi ai reclami senza informazioni finanziarie
+ *Gestione dei* profili: assicurati che le risorse dispongano di dichiarazioni di profilo appropriate, esegui la convalida rispetto ai profili di destinazione prima dell'ingestione e utilizza il controllo delle versioni dei profili per controllare il comportamento di esportazione
## Limitazioni
+ Nel parametro è possibile specificare un massimo di 500 pazienti `patient`
+ L'esportazione è limitata alle sole operazioni a livello di gruppo
+ Supporta solo il set predefinito di tipi di risorse per ogni tipo di esportazione
+ L'output è sempre in formato NDJSON
+ PDex le esportazioni sono limitate a 5 anni di dati clinici e relativi ai reclami
+ La trasformazione dei dati finanziari si applica solo ai profili CARIN BB 2.x ExplanationOfBenefit
## Risorse aggiuntive
+ [Elenco di attribuzione dei soci Da Vinci IG](https://build.fhir.org/ig/HL7/davinci-atr/)
+ [Da Vinci Payer Data Exchange IG](https://hl7.org/fhir/us/davinci-pdex/)
+ [IG CARIN Consumer Directed Payer Data Exchange](https://build.fhir.org/ig/HL7/carin-bb/)
+ [Guida all'implementazione di base negli Stati Uniti](https://www.hl7.org/fhir/us/core/)
+ [Specifiche FHIR Bulk Data Access](https://hl7.org/fhir/uv/bulkdata/)
# Generazione di documenti clinici con `$document`
AWS HealthLake ora supporta il `$document` funzionamento delle risorse di Composizione, consentendovi di generare un documento clinico completo raggruppando la Composizione con tutte le sue risorse di riferimento in un unico pacchetto coeso. Questa operazione è essenziale per le applicazioni sanitarie che devono:
+ Creare documenti clinici standardizzati
+ Scambia le cartelle cliniche complete dei pazienti
+ Archivia una documentazione clinica completa
+ Genera report che includano tutto il contesto pertinente
## Utilizzo
L'`$document`operazione può essere richiamata sulle risorse di composizione utilizzando i metodi GET e POST:
**Operazioni supportate**
```
GET/POST [base]/Composition/[id]/$document
```
## Parametri supportati
HealthLake supporta il seguente parametro FHIR`$document`:
| Parametro | Tipo | Obbligatorio | Predefinita | Description |
| --- | --- | --- | --- | --- |
| persist | booleano | No | false | Booleano che indica se il server deve archiviare il pacchetto di documenti generato |
## Esempi
**Richiesta GET**
```
GET [base]/Composition/180f219f-97a8-486d-99d9-ed631fe4fc57/$document?persist=true
```
**Richiesta POST con parametri**
```
POST [base]/Composition/180f219f-97a8-486d-99d9-ed631fe4fc57/$document
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "persist",
"valueBoolean": true
}
]
}
```
**Risposta di esempio**
L'operazione restituisce una risorsa Bundle di tipo «documento» contenente la composizione e tutte le risorse di riferimento:
```
{
"resourceType": "Bundle",
"id": "180f219f-97a8-486d-99d9-ed631fe4fc57",
"type": "document",
"identifier": {
"system": "urn:ietf:rfc:3986",
"value": "urn:uuid:0c3151bd-1cbf-4d64-b04d-cd9187a4c6e0"
},
"timestamp": "2024-06-21T15:30:00Z",
"entry": [
{
"fullUrl": "http://example.org/fhir/Composition/180f219f-97a8-486d-99d9-ed631fe4fc57",
"resource": {
"resourceType": "Composition",
"id": "180f219f-97a8-486d-99d9-ed631fe4fc57",
"status": "final",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "34133-9",
"display": "Summary of Episode Note"
}
]
},
"subject": {
"reference": "Patient/example"
},
"section": [
{
"title": "Allergies",
"entry": [
{
"reference": "AllergyIntolerance/123"
}
]
}
]
}
},
{
"fullUrl": "http://example.org/fhir/Patient/example",
"resource": {
"resourceType": "Patient",
"id": "example",
"name": [
{
"family": "Smith",
"given": ["John"]
}
]
}
},
{
"fullUrl": "http://example.org/fhir/AllergyIntolerance/123",
"resource": {
"resourceType": "AllergyIntolerance",
"id": "123",
"patient": {
"reference": "Patient/example"
},
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "418689008",
"display": "Allergy to penicillin"
}
]
}
}
}
]
}
```
## Comportamento
L'`$document`operazione:
1. Prende la risorsa Composition specificata come base per il documento
1. Identifica e recupera tutte le risorse a cui fa riferimento direttamente la composizione
1. Raggruppa la composizione e tutte le risorse referenziate in un pacchetto di tipo «documento»
1. Memorizza il pacchetto di documenti generato nel datastore quando il parametro persist è impostato su true
1. Identifica e recupera le risorse a cui fa riferimento indirettamente la Composizione per una generazione completa di documenti
L'`$document`operazione attualmente supporta il recupero dei riferimenti alle risorse nel seguente formato:
1.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id
```
1. Risorsa/ID
I riferimenti alle risorse non supportati all'interno della risorsa Composition verranno filtrati dal documento generato.
## Gestione errori
L'operazione gestisce le seguenti condizioni di errore:
+ 400 Richiesta non valida: `$document` operazione non valida (richiesta non conforme) o se il documento risultante non supera la convalida FHIR a causa di riferimenti filtrati quando persist è impostato su true
+ 404 Not Found: Risorsa di composizione non trovata
Per ulteriori informazioni sulle specifiche `$document` operative, consultate la documentazione sulla [composizione `$document` FHIR R4](https://www.hl7.org/fhir/R4/composition-operation-document.html).
# Rimozione permanente di risorse con `$erase`
AWS HealthLake supporta l'`$erase`operazione, abilitando l'eliminazione permanente di una risorsa specifica e delle relative versioni storiche. Questa operazione è particolarmente utile quando è necessario:
+ Rimuovere definitivamente le singole risorse
+ Eliminare cronologie di versioni specifiche
+ Gestisci i cicli di vita delle singole risorse
+ Rispetta i requisiti specifici di rimozione dei dati
## Utilizzo
L'`$erase`operazione può essere richiamata a due livelli:
**Livello di istanza di risorsa**
```
POST [base]/[ResourceType]/[ID]/$erase?deleteAuditEvent=true
```
**Livello specifico della versione**
```
POST [base]/[ResourceType]/[ID]/_history/[VersionID]/$erase
```
## Parameters
| Parametro | Tipo | Obbligatorio | Predefinita | Description |
| --- | --- | --- | --- | --- |
| deleteAuditEvent | booleano | No | false | Se impostato su true, elimina gli eventi di controllo associati |
## Esempi
**Richiesta di esempio**
```
POST [base]/Patient/example-patient/$erase
```
**Risposta di esempio**
```
{
"jobId": "5df47e2f51ff3c731847678cb8cad48e",
"jobStatus": "SUBMITTED"
}
```
## Stato di un processo
Per verificare lo stato di un processo di cancellazione:
```
GET [base]/$erase/[jobId]
```
L'operazione restituisce informazioni sullo stato del lavoro:
```
{
"datastoreId": "36622996b1fcecb7e12ee2ee085308d3",
"jobId": "5df47e2f51ff3c731847678cb8cad48e",
"status": "COMPLETED",
"submittedTime": "2025-10-30T16:39:24.160Z"
}
```
## Comportamento
L'`$erase`operazione:
1. Processi in modo asincrono per garantire l'integrità dei dati
1. Mantiene le transazioni ACID
1. Fornisce il monitoraggio dello stato del lavoro
1. Rimuove definitivamente la risorsa specificata e le relative versioni
1. Include una registrazione di controllo completa delle attività di eliminazione
1. Supporta l'eliminazione selettiva degli eventi di controllo
## Registrazione degli audit
L'`$erase`operazione viene registrata in base DeleteResource all'ID utente, al timestamp e ai dettagli delle risorse.
## Limitazioni
+ `$erased`la risorsa non verrà visualizzata nei risultati di ricerca o nelle query. `_history`
+ Le risorse in fase di cancellazione potrebbero essere temporaneamente inaccessibili durante l'elaborazione
+ La misurazione dello storage viene regolata immediatamente man mano che le risorse vengono rimosse definitivamente
# Acquisizione dei dati dei pazienti con `Patient/$everything`
L'`Patient/$everything`operazione viene utilizzata per interrogare una `Patient` risorsa FHIR, insieme a qualsiasi altra risorsa ad essa correlata. `Patient` L'operazione può essere utilizzata per fornire a un paziente l'accesso all'intera cartella clinica o consentire a un fornitore di eseguire un download di massa di dati relativi a un paziente. HealthLakesupporti `Patient/$everything` per un paziente `id` specifico.
`Patient/$everything`è un'operazione API REST FHIR che può essere richiamata come mostrato negli esempi seguenti.
------
#### [ GET request ]
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything
```
------
**Nota**
Le risorse in risposta sono ordinate per tipo di risorsa e risorsa. `id`
La risposta è sempre compilata con. `Bundle.total`
## Parametri di `Patient/$everything`
HealthLake supporta i seguenti parametri di interrogazione
| Parametro | Informazioni |
| --- | --- |
| rapida | Recupera tutti `Patient` i dati dopo una data di inizio specificata. |
| end | Ottieni tutti i `Patient` dati prima di una data di fine specificata. |
| since | Aggiorna tutti `Patient` i dati dopo una data specificata. |
| \$1tipo | Ottieni `Patient` dati per tipi di risorse specifici. |
| \$1conta | Recupera `Patient` dati e specifica la dimensione della pagina. |
**Example - Ottieni tutti i dati del paziente dopo una data di inizio specificata**
`Patient/$everything`può utilizzare il `start` filtro per interrogare solo i dati dopo una data specifica.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?start=2024-03-15T00:00:00.000Z
```
**Example - Ottieni tutti i `Patient` dati prima di una data di fine specificata**
Patient \$1everything può utilizzare il `end` filtro solo per interrogare i dati prima di una data specifica.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?end=2024-03-15T00:00:00.000Z
```
**Example - Aggiorna tutti `Patient` i dati dopo una data specificata**
`Patient/$everything`può utilizzare il `since` filtro per interrogare solo i dati aggiornati dopo una data specifica.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?since=2024-03-15T00:00:00.000Z
```
**Example - Ottieni `Patient` dati per tipi di risorse specifici**
Patient \$1everything può utilizzare il `_type` filtro per specificare tipi di risorse specifici da includere nella risposta. È possibile specificare più tipi di risorse in un elenco separato da virgole.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?_type=Observation,Condition
```
**Example - Ottieni `Patient` dati e specifica la dimensione della pagina**
Patient \$1everything può utilizzare il `_count` per impostare la dimensione della pagina.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?_count=15
```
## `Patient/$everything``start`e attributi `end`
HealthLake supporta i seguenti attributi di risorsa per i parametri `Patient/ $everything` `start` e di `end` interrogazione.
| Risorsa | Elemento risorsa |
| --- | --- |
| Account | Account.ServicePeriod.start |
| AdverseEvent | AdverseEvent.data |
| AllergyIntolerance | AllergyIntolerance.data registrata |
| Appuntamento | Appuntamento. Inizio |
| AppointmentResponse | AppointmentResponse.inizio |
| AuditEvent | AuditEvent.periodo.inizio |
| Di base | Di base. Creato |
| BodyStructure | NESSUNA\$1DATA |
| CarePlan | CarePlan.periodo. inizio |
| CareTeam | CareTeam.periodo.inizio |
| ChargeItem | ChargeItem. occurrenceDateTime, ChargeItem .OccurrencePeriod.START, .OccurrenceTiming.Event ChargeItem |
| Richiedi | claim. billablePeriod.START |
| ClaimResponse | ClaimResponse.creato |
| ClinicalImpression | ClinicalImpression.data |
| Communication | Comunicazione. Inviata |
| CommunicationRequest | CommunicationRequest. occurrenceDateTime, CommunicationRequest .Periodo di occorrenza. Inizio |
| Composizione | Composizione. Data |
| Condizione | Condizione. Data registrata |
| Consenso | Consenso. Data/ora |
| Copertura | Copertura.Period.Inizio |
| CoverageEligibilityRequest | CoverageEligibilityRequest.creato |
| CoverageEligibilityResponse | CoverageEligibilityResponse.creato |
| DetectedIssue | DetectedIssue.identificato |
| DeviceRequest | DeviceRequest. Scritto il |
| DeviceUseStatement | DeviceUseStatement. Registrato su |
| DiagnosticReport | DiagnosticReport.efficace |
| DocumentManifest | DocumentManifest.creato |
| DocumentReference | DocumentReference.contesto.periodo.inizio |
| Incontro | Incontro.period.start |
| EnrollmentRequest | EnrollmentRequest.creato |
| EpisodeOfCare | EpisodeOfCare.periodo.inizio |
| ExplanationOfBenefit | ExplanationOfBenefit. Periodo fatturabile. Inizio |
| FamilyMemberHistory | NESSUNA\$1DATA |
| Flag | flag.period.start |
| Obiettivo | Obiettivo. StatusDate |
| Gruppo | NESSUNA\$1DATA |
| ImagingStudy | ImagingStudy.iniziato |
| Immunizzazione | Immunizzazione. Registrata |
| ImmunizationEvaluation | ImmunizationEvaluation.data |
| ImmunizationRecommendation | ImmunizationRecommendation.data |
| Fattura | Data della fattura |
| List | Elenco. Data |
| MeasureReport | MeasureReport.periodo.inizio |
| Media | Media. Emesso |
| MedicationAdministration | MedicationAdministration.efficace |
| MedicationDispense | MedicationDispense. Quando preparato |
| MedicationRequest | MedicationRequest. Scritto su |
| MedicationStatement | MedicationStatement.Data inserita |
| MolecularSequence | NESSUNA\$1DATA |
| NutritionOrder | NutritionOrder.Data/ora |
| Osservazione | Osservazione. Efficace |
| Paziente | NESSUNA\$1DATA |
| Person | NESSUNA\$1DATA |
| Procedura | Procedura. Eseguita |
| Provenienza | Provenienza. Periodo occorso. Inizio, Provenienza. occurredDateTime |
| QuestionnaireResponse | QuestionnaireResponse.scritto |
| RelatedPerson | NESSUNA\$1DATA |
| RequestGroup | RequestGroup. Scritto il |
| ResearchSubject | ResearchSubject.periodo |
| RiskAssessment | RiskAssessment. occurrenceDateTime, RiskAssessment .Periodo di occorrenza. Inizio |
| Schedule | Schedule.PlanningHorizon |
| ServiceRequest | ServiceRequest. Scritto il |
| Esemplare | Esemplare. Ora di ricezione |
| SupplyDelivery | SupplyDelivery. occurrenceDateTime, SupplyDelivery .OccurrencePeriod.START, .OccurrenceTiming.Event SupplyDelivery |
| SupplyRequest | SupplyRequest. Scritto il |
| VisionPrescription | VisionPrescription.data scritta |
# Recupero dei codici con ValueSet `$expand`
AWS HealthLake ora supporta l'`$expand`operazione relativa ValueSets ai codici acquisiti da te come cliente, consentendoti di recuperare l'elenco completo dei codici contenuti in quelle ValueSet risorse. Questa operazione è particolarmente utile quando è necessario:
+ Recuperare tutti i codici possibili a scopo di convalida
+ Visualizza le opzioni disponibili nelle interfacce utente
+ Esegui ricerche complete di codice all'interno di un contesto terminologico specifico
## Utilizzo
L'`$expand`operazione può essere richiamata sulle ValueSet risorse utilizzando i metodi GET e POST:
**Operazioni supportate**
```
GET/POST [base]/ValueSet/[id]/$expand
GET [base]/ValueSet/$expand?url=http://example.com
POST [base]/ValueSet/$expand
```
## Parametri supportati
HealthLake supporta un sottoinsieme di parametri FHIR R4: `$expand`
| Parametro | Tipo | Campo obbligatorio | Description |
| --- | --- | --- | --- |
| url | uri | No | URL canonico del file da espandere ValueSet |
| id | id | No | ValueSet id della risorsa da espandere (per le operazioni GET o POST) |
| filter | stringa | No | Filtra il risultato dell'espansione del codice |
| count | numero intero | No | Numero di codici da restituire |
| offset | numero intero | No | Numero di codici corrispondenti da saltare prima della restituzione. Si applica dopo il filtraggio e solo ai codici corrispondenti, non al contenuto completo e non filtrato dell'originale ValueSet |
## Esempi
**GET Richiesta per ID**
```
GET [base]/ValueSet/example-valueset/$expand
```
**Richiesta GET per URL con filtro**
```
GET [base]/ValueSet/$expand?url=http://example.com/ValueSet/my-valueset&filter=male&count=5
```
**Richiesta POST con parametri (per ID)**
```
POST [base]/ValueSet/example-valueset/$expand
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "count",
"valueInteger": 10
},
{
"name": "filter",
"valueString": "admin"
}
]
}
```
**Richiesta POST con parametri (tramite URL)**
```
POST [base]/ValueSet/$expand
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "url",
"valueUri": "http://hl7.org/fhir/ValueSet/administrative-gender"
},
{
"name": "count",
"valueInteger": 10
}
]
}
```
**Risposta di esempio**
L'operazione restituisce una ValueSet risorsa con un `expansion` elemento contenente i codici espansi:
```
{
"resourceType": "ValueSet",
"id": "administrative-gender",
"status": "active",
"expansion": {
"identifier": "urn:uuid:12345678-1234-1234-1234-123456789abc",
"timestamp": "2024-01-15T10:30:00Z",
"total": 4,
"parameter": [
{
"name": "count",
"valueInteger": 10
}
],
"contains": [
{
"system": "http://hl7.org/fhir/administrative-gender",
"code": "male",
"display": "Male"
},
{
"system": "http://hl7.org/fhir/administrative-gender",
"code": "female",
"display": "Female"
},
{
"system": "http://hl7.org/fhir/administrative-gender",
"code": "other",
"display": "Other"
},
{
"system": "http://hl7.org/fhir/administrative-gender",
"code": "unknown",
"display": "Unknown"
}
]
}
}
```
La risposta include:
+ expansion.total: numero totale di codici nell'espanso ValueSet
+ expansion.contains: matrice di codici espansi con i relativi valori di sistema, codice e visualizzazione
+ expansion.parameter: parametri utilizzati nella richiesta di espansione
[Per ulteriori informazioni sulle specifiche `$expand` operative, consultate la documentazione FHIR R4. ValueSet `$expand`](https://build.fhir.org/valueset-operation-expand.html)
# Esportazione di HealthLake dati con FHIR `$export`
Puoi esportare i dati in blocco dal tuo archivio HealthLake dati utilizzando l'operazione FHIR \$1export. HealthLake supporta l'utilizzo e le richieste di FHIR`$export`. `POST` `GET` Per effettuare una richiesta di esportazione`POST`, devi disporre di un utente, gruppo o ruolo IAM con le autorizzazioni richieste, specificarlo `$export` come parte della richiesta e includere i parametri desiderati nel corpo della richiesta.
**Nota**
Tutte le richieste di HealthLake esportazione effettuate utilizzando FHIR `$export` vengono restituite in `ndjson` formato ed esportate in un bucket Amazon S3, dove ogni oggetto Amazon S3 contiene un solo tipo di risorsa FHIR.
Puoi mettere in coda le richieste di esportazione in base alle quote di servizio dell'account. AWS Per ulteriori informazioni, consulta [Service Quotas](reference-healthlake-endpoints-quotas.md#reference-healthlake-quotas).
HealthLake supporta i seguenti tre tipi di richieste endpoint di esportazione in blocco.
**HealthLake tipi in blocco `$export`**
| Tipo di esportazione | Description | Sintassi |
| --- | --- | --- |
| Sistema | Esporta tutti i dati dal server HealthLake FHIR. | `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/$export` |
| Tutti i pazienti | Esporta tutti i dati relativi a tutti i pazienti, compresi i tipi di risorse associati al tipo di risorsa Paziente. | `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/$export` `GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/$export` |
| Gruppo di pazienti | Esporta tutti i dati relativi a un gruppo di pazienti specificato con un ID di gruppo. | `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Group/id/$export` `GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Group/id/$export` |
## Prima di iniziare
Soddisfa i seguenti requisiti per effettuare una richiesta di esportazione utilizzando l'API REST FHIR per HealthLake.
+ È necessario aver impostato un utente, un gruppo o un ruolo con le autorizzazioni necessarie per effettuare la richiesta di esportazione. Per ulteriori informazioni, consulta [Autorizzazione di una richiesta `$export`](#export-rest-auth).
+ Devi aver creato un ruolo di servizio che garantisca HealthLake l'accesso al bucket Amazon S3 in cui desideri esportare i tuoi dati. Il ruolo di servizio deve inoltre essere specificato HealthLake come principale del servizio. Per ulteriori informazioni sulla configurazione delle autorizzazioni, vedere[Impostazione delle autorizzazioni per i lavori di esportazione](getting-started-setting-up.md#setting-up-export-permissions).
## Autorizzazione di una richiesta `$export`
Per effettuare correttamente una richiesta di esportazione utilizzando l'API REST FHIR, autorizza il tuo utente, gruppo o ruolo utilizzando IAM o .0. OAuth2 È inoltre necessario avere un ruolo di servizio.
**Autorizzazione di una richiesta tramite IAM**
Quando effettui una `$export` richiesta, l'utente, il gruppo o il ruolo devono includere azioni IAM nella policy. Per ulteriori informazioni, consulta [Impostazione delle autorizzazioni per i lavori di esportazione](getting-started-setting-up.md#setting-up-export-permissions).
**Autorizzazione di una richiesta utilizzando SMART on FHIR (2.0) OAuth**
Quando si effettua una `$export` richiesta su un HealthLake data store compatibile con SMART on FHIR, è necessario assegnare gli ambiti appropriati. Per ulteriori informazioni, consulta [SMART sugli ambiti di risorse FHIR per HealthLake](reference-smart-on-fhir-oauth-scopes.md#smart-on-fhir-scopes-rest).
**Nota**
Le FHIR `$export` con `GET` richieste richiedono lo stesso metodo di autenticazione o lo stesso token portatore (nel caso di SMART su FHIR) per richiedere l'esportazione e il recupero dei file. I file esportati utilizzando FHIR `$export` con `GET` sono disponibili per il download per 48 ore.
## Effettuare una richiesta `$export`
Questa sezione descrive i passaggi necessari da eseguire quando si effettua una richiesta di esportazione utilizzando l'API REST FHIR.
Per evitare addebiti accidentali sul tuo AWS account, ti consigliamo di testare le tue richieste effettuando una `POST` richiesta senza fornire la `$export` sintassi.
Per effettuare la richiesta, devi fare quanto segue:
1. Specificare `$export` nell'URL della `POST` richiesta per un endpoint supportato.
1. Specificate i parametri di intestazione richiesti.
1. Specificate un corpo della richiesta che definisca i parametri richiesti.
### Passo 1: Specificare `$export` nell'URL della `POST` richiesta un [endpoint](reference-healthlake-endpoints-quotas.md#reference-healthlake-endpoints) supportato.
HealthLake supporta tre tipi di richieste endpoint di esportazione in blocco. Per effettuare una richiesta di esportazione in blocco, è necessario effettuare una richiesta `POST` basata su uno dei tre endpoint supportati. Gli esempi seguenti mostrano dove specificare `$export` nell'URL della richiesta.
+ `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/$export`
+ `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/$export`
+ `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Group/id/$export`
È possibile utilizzare i seguenti parametri di ricerca supportati nella stringa di `POST` richiesta.
#### Parametri di ricerca supportati
HealthLake supporta i seguenti modificatori di ricerca nelle richieste di esportazione in blocco.
I seguenti esempi includono caratteri speciali che devono essere codificati prima di inviare la richiesta.
| Name | Obbligatorio? | Description | Esempio |
| --- | --- | --- | --- |
| \$1outputFormat | No | Il formato per i file Bulk Data richiesti da generare. I valori accettati sonoapplication/fhir\$1ndjson,application/ndjson,ndjson. | |
| \$1type | No | Una stringa di tipi di risorse FHIR delimitati da virgole da includere nel processo di esportazione. Ti consigliamo di includerla \$1type perché ciò può avere un impatto sui costi quando tutte le risorse vengono esportate. | &\$1type=MedicationStatement, Observation |
| \$1since | No | Tipi di risorse modificati in o dopo la data e l'ora. Se un tipo di risorsa non ha l'ora dell'ultimo aggiornamento, verranno inclusi nella risposta. | &\$1since=2024-05-09T00%3A00%3A00Z |
| \$1until | No | Tipi di risorse modificati in data e ora o prima. Utilizzato in combinazione con \$1since per definire un intervallo di tempo specifico per l'esportazione. Se un tipo di risorsa non ha un'ora dell'ultimo aggiornamento, verrà escluso dalla risposta. | &\$1until=2024-12-31T23%3A59%3A59Z |
### Passaggio 2: Specificare i parametri di intestazione richiesti
Per effettuare una richiesta di esportazione utilizzando l'API REST FHIR, è necessario specificare i seguenti parametri di intestazione.
+ Tipo di contenuto: `application/fhir+json`
+ Preferisco: `respond-async`
Successivamente, è necessario specificare gli elementi richiesti nel corpo della richiesta.
### Fase 3: Specificare un corpo della richiesta e definire i parametri richiesti.
La richiesta di esportazione richiede anche un corpo in `JSON` formato. Il corpo può includere i seguenti parametri.
| Chiave | Obbligatorio? | Description | Valore |
| --- | --- | --- | --- |
| DataAccessRoleArn | Sì | Un ARN di un ruolo di HealthLake servizio. Il ruolo di servizio utilizzato deve essere specificato HealthLake come principale del servizio. | arn:aws:iam::444455556666:role/your-healthlake-service-role |
| JobName | No | Il nome della richiesta di esportazione. | your-export-job-name |
| S3Uri | Sì | Parte di una OutputDataConfig chiave. L'URI S3 del bucket di destinazione in cui verranno scaricati i dati esportati. | s3://amzn-s3-demo-bucket/EXPORT-JOB/ |
| KmsKeyId | Sì | Parte di una chiave. OutputDataConfig L'ARN della AWS KMS chiave utilizzata per proteggere il bucket Amazon S3. | arn:aws:kms:region-of-bucket:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab |
**Example Corpo di una richiesta di esportazione effettuata utilizzando l'API REST FHIR**
Per effettuare una richiesta di esportazione utilizzando l'API REST FHIR, è necessario specificare un corpo, come illustrato di seguito.
```
{
"DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role",
"JobName": "your-export-job",
"OutputDataConfig": {
"S3Configuration": {
"S3Uri": "s3://amzn-s3-demo-bucket/EXPORT-JOB",
"KmsKeyId": "arn:aws:kms:region-of-bucket:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
}
```
Quando la richiesta avrà esito positivo, riceverai la seguente risposta.
*Intestazione della risposta*
```
content-location: https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/export/your-export-request-job-id
```
*Corpo di risposta*
```
{
"datastoreId": "your-data-store-id",
"jobStatus": "SUBMITTED",
"jobId": "your-export-request-job-id"
}
```
## Gestione della richiesta di esportazione
Dopo aver effettuato una richiesta di esportazione corretta, puoi gestirla descrivendo `$export` lo stato di una richiesta di esportazione corrente e `$export` annullando una richiesta di esportazione corrente.
Quando annulli una richiesta di esportazione utilizzando l'API REST, ti viene fatturata solo la parte dei dati che sono stati esportati fino al momento in cui hai inviato la richiesta di annullamento.
I seguenti argomenti descrivono come visualizzare lo stato o annullare una richiesta di esportazione corrente.
### Annullamento di una richiesta di esportazione
Per annullare una richiesta di esportazione, effettua una `DELETE` richiesta e fornisci l'ID del lavoro nell'URL della richiesta.
```
DELETE https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/export/your-export-request-job-id
```
Quando la richiesta ha esito positivo, riceverai quanto segue.
```
{
"exportJobProperties": {
"jobId": "your-original-export-request-job-id",
"jobStatus": "CANCEL_SUBMITTED",
"datastoreId": "your-data-store-id"
}
}
```
Quando la tua richiesta non va a buon fine, ricevi quanto segue.
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "not-supported",
"diagnostics": "Interaction not supported."
}
]
}
```
### Descrizione di una richiesta di esportazione
Per conoscere lo stato di una richiesta di esportazione, effettua una `GET` richiesta utilizzando `export` and your`export-request-job-id`.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/export/your-export-request-id
```
La risposta JSON conterrà un `ExportJobProperties` oggetto. Può contenere le seguenti coppie chiave:valore.
| Name | Obbligatorio? | Description | Valore |
| --- | --- | --- | --- |
| DataAccessRoleArn | No | Un ARN di un ruolo di HealthLake servizio. Il ruolo di servizio utilizzato deve essere specificato HealthLake come principale del servizio. | arn:aws:iam::444455556666:role/your-healthlake-service-role |
| SubmitTime | No | La data e l'ora in cui è stato inviato un processo di esportazione. | Apr 21, 2023 5:58:02 |
| EndTime | No | L'ora in cui è stato completato un processo di esportazione. | Apr 21, 2023 6:00:08 PM |
| JobName | No | Il nome della richiesta di esportazione. | your-export-job-name |
| JobStatus | No | | I valori validi sono:SUBMITTED | IN_PROGRESS | COMPLETED_WITH_ERRORS | COMPLETED |
FAILED
|
| S3Uri | Sì | Parte di un [OutputDataConfig](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_OutputDataConfig.html)oggetto. L'URI Amazon S3 del bucket di destinazione in cui verranno scaricati i dati esportati. | s3://amzn-s3-demo-bucket/EXPORT-JOB/ |
| KmsKeyId | Sì | Parte di un oggetto. [OutputDataConfig](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_OutputDataConfig.html) L'ARN della AWS KMS chiave utilizzata per proteggere il bucket Amazon S3. | arn:aws:kms:region-of-bucket:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab |
**Example : corpo di una richiesta di descrizione dell'esportazione effettuata utilizzando l'API REST FHIR**
In caso di successo, riceverai la seguente risposta JSON.
```
{
"exportJobProperties": {
"jobId": "your-export-request-id",
"JobName": "your-export-job",
"jobStatus": "SUBMITTED",
"submitTime": "Apr 21, 2023 5:58:02 PM",
"endTime": "Apr 21, 2023 6:00:08 PM",
"datastoreId": "your-data-store-id",
"outputDataConfig": {
"s3Configuration": {
"S3Uri": "s3://amzn-s3-demo-bucket/EXPORT-JOB",
"KmsKeyId": "arn:aws:kms:region-of-bucket:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab""
}
},
"DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role",
}
}
```
# `$inquire`Operazione FHIR per HealthLake
L'`$inquire`operazione consente di verificare lo stato di una richiesta di autorizzazione preventiva inviata in precedenza. Questa operazione implementa la [Guida all'implementazione del Da Vinci Prior Authorization Support (PAS)](https://hl7.org/fhir/us/davinci-pas/), che fornisce un flusso di lavoro standardizzato basato su FHIR per recuperare l'attuale decisione di autorizzazione.
## Come funziona
+ **Invia richiesta**: invii un pacchetto FHIR contenente il reclamo che desideri verificare e le informazioni di supporto
+ **Cerca**: HealthLake cerca il corrispondente ClaimResponse nel tuo archivio dati
+ **Recupera**: viene recuperato lo stato di autorizzazione più recente
+ **Rispondi**: ricevi una risposta immediata con lo stato dell'autorizzazione corrente (in coda, approvata, negata, ecc.)
**Nota**
`$inquire`è un'**operazione di sola lettura** che recupera lo stato di autorizzazione esistente. Non modifica o aggiorna alcuna risorsa nell'archivio dati.
## Endpoint API
```
POST /datastore/{datastoreId}/r4/Claim/$inquire
Content-Type: application/fhir+json
```
## Struttura della richiesta
### Requisiti del pacchetto
La tua richiesta deve essere una risorsa FHIR Bundle con:
+ **Bundle.type: Deve** essere `"collection"`
+ **bundle.entry****: deve contenere esattamente una risorsa Claim con:**
+ `use = "preauthorization"`
+ `status = "active"`
+ **Risorse referenziate**: tutte le risorse a cui fa riferimento il reclamo devono essere incluse nel pacchetto
**Interrogazione per esempio**
Le risorse del tuo pacchetto di input fungono da modello di ricerca. HealthLake utilizza le informazioni fornite per individuare il corrispondente ClaimResponse.
### Risorse obbligatorie
| Risorsa | Cardinalità | Profilo | Description |
| --- | --- | --- | --- |
| Reclamo | 1 | Richiesta di reclamo PAS | L'autorizzazione preventiva su cui stai chiedendo informazioni |
| La paziente | 1 | Paziente beneficiario PAS | Informazioni demografiche sui pazienti |
| Organizzazione (assicuratore) | 1 | Organizzazione assicurativa PAS | Compagnia assicurativa |
| Organizzazione (fornitore) | 1 | Organizzazione richiedente PAS | Operatore sanitario che ha inviato la richiesta |
### Criteri di ricerca importanti
HealthLake ricerche per l' ClaimResponse utilizzo:
+ **Riferimento del paziente** riportato nel reclamo
+ **Riferimento dell'assicuratore** riportato nel reclamo
+ **Riferimento al fornitore** riportato nel reclamo
+ **Data di creazione** del reclamo (come filtro temporale)
**Solo domande specifiche per il paziente**
Tutte le richieste devono essere legate a un paziente specifico. Non sono consentite domande a livello di sistema senza identificazione del paziente.
## Richiesta di esempio
```
POST /datastore/example-datastore/r4/Claim/$inquire
Content-Type: application/fhir+json
Authorization: Bearer
{
"resourceType": "Bundle",
"id": "PASClaimInquiryBundleExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-inquiry-request-bundle"]
},
"identifier": {
"system": "http://example.org/SUBMITTER_TRANSACTION_IDENTIFIER",
"value": "5269368"
},
"type": "collection",
"timestamp": "2005-05-02T14:30:00+05:00",
"entry": [
{
"fullUrl": "http://example.org/fhir/Claim/MedicalServicesAuthorizationExample",
"resource": {
"resourceType": "Claim",
"id": "MedicalServicesAuthorizationExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim-inquiry"]
},
"status": "active",
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "professional"
}]
},
"use": "preauthorization",
"patient": {
"reference": "Patient/SubscriberExample"
},
"created": "2005-05-02T11:01:00+05:00",
"insurer": {
"reference": "Organization/InsurerExample"
},
"provider": {
"reference": "Organization/UMOExample"
}
}
},
{
"fullUrl": "http://example.org/fhir/Patient/SubscriberExample",
"resource": {
"resourceType": "Patient",
"id": "SubscriberExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-beneficiary"]
},
"name": [{
"family": "SMITH",
"given": ["JOE"]
}],
"gender": "male"
}
},
{
"fullUrl": "http://example.org/fhir/Organization/UMOExample",
"resource": {
"resourceType": "Organization",
"id": "UMOExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor"]
},
"name": "Provider Organization"
}
},
{
"fullUrl": "http://example.org/fhir/Organization/InsurerExample",
"resource": {
"resourceType": "Organization",
"id": "InsurerExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer"]
},
"name": "Insurance Company"
}
}
]
}
```
## Formato della risposta
### Risposta riuscita (200 OK)
Riceverai un pacchetto PAS Inquiry Response contenente:
+ **ClaimResponse**con lo stato di autorizzazione corrente; multiplo **ClaimResponse**se corrisponde ai criteri di ricerca
+ Tutte le risorse originali contenute nella tua richiesta (riportate all'indietro)
+ Timestamp di quando è stata assemblata la risposta
**Possibili esiti ClaimResponse**
| Outcome | Description |
| --- | --- |
| queued | La richiesta di autorizzazione è ancora in attesa di revisione |
| complete | La decisione di autorizzazione è stata presa (verifica se disposition approvata/negata) |
| error | Si è verificato un errore durante l'elaborazione |
| partial | Autorizzazione parziale concessa |
```
{
"resourceType": "Bundle",
"identifier": {
"system": "http://example.org/SUBMITTER_TRANSACTION_IDENTIFIER",
"value": "5269367"
},
"type": "collection",
"timestamp": "2005-05-02T14:30:15+05:00",
"entry": [
{
"fullUrl": "http://example.org/fhir/ClaimResponse/InquiryResponseExample",
"resource": {
"resourceType": "ClaimResponse",
"id": "InquiryResponseExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claimresponse-inquiry"]
},
"status": "active",
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "professional"
}]
},
"use": "preauthorization",
"patient": {
"reference": "Patient/SubscriberExample"
},
"created": "2005-05-02T11:05:00+05:00",
"insurer": {
"reference": "Organization/InsurerExample"
},
"request": {
"reference": "Claim/MedicalServicesAuthorizationExample"
},
"outcome": "complete",
"disposition": "Approved",
"preAuthRef": "AUTH12345"
}
},
{
"fullUrl": "http://example.org/fhir/Claim/MedicalServicesAuthorizationExample",
"resource": {
"resourceType": "Claim",
"id": "MedicalServicesAuthorizationExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim-inquiry"]
},
"status": "active",
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "professional"
}]
},
"use": "preauthorization",
"patient": {
"reference": "Patient/SubscriberExample"
},
"created": "2005-05-02T11:01:00+05:00",
"insurer": {
"reference": "Organization/InsurerExample"
},
"provider": {
"reference": "Organization/UMOExample"
}
}
},
{
"fullUrl": "http://example.org/fhir/Patient/SubscriberExample",
"resource": {
"resourceType": "Patient",
"id": "SubscriberExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-beneficiary"]
},
"name": [{
"family": "SMITH",
"given": ["JOE"]
}],
"gender": "male"
}
},
{
"fullUrl": "http://example.org/fhir/Organization/UMOExample",
"resource": {
"resourceType": "Organization",
"id": "UMOExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor"]
},
"name": "Provider Organization"
}
},
{
"fullUrl": "http://example.org/fhir/Organization/InsurerExample",
"resource": {
"resourceType": "Organization",
"id": "InsurerExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer"]
},
"name": "Insurance Company"
}
}
]
}
```
## Risposte agli errori
### 400 Richiesta non valida
Restituito quando il formato della richiesta non è valido o la convalida fallisce.
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "required",
"diagnostics": "Reference 'Patient/SubscriberExample' at path 'patient' for 'CLAIM' resource not found(at Bundle.entry[0].resource)"
}
]
}
```
### 401 - Autorizzazione negata
Restituito quando le credenziali di autenticazione sono mancanti o non valide.
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "forbidden",
"diagnostics": "Invalid authorization header"
}
]
}
```
### 403 Non consentito
Restituito quando l'utente autenticato non è autorizzato ad accedere alla risorsa richiesta.
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "exception",
"diagnostics": "Insufficient SMART scope permissions."
}
]
}
```
### 400 Quando non ne viene trovato nessuno
Restituito quando non ClaimResponse viene trovata alcuna corrispondenza per la richiesta.
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "not-found",
"diagnostics": "Resource not found. No ClaimResponse found from the input Claim that matches the specified Claim properties patient, insurer, provider, and created(at Bundle.entry[0].resource)"
}]
}
```
### 4.1.5 Tipo di supporto non supportato
Restituito quando l'intestazione Content-Type non è application/fhir\$1json.
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "value",
"diagnostics": "Incorrect MIME-type. Update request Content-Type header."
}]
}
```
### 429 Troppe richieste
Restituito quando vengono superati i limiti di velocità.
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "throttled",
"diagnostics": "Rate limit exceeded. Please retry after some time."
}]
}
```
## Regole di convalida
HealthLake esegue una convalida completa della richiesta:
### Convalida del pacchetto
+ Deve essere conforme al profilo PAS Inquiry Request Bundle
+ `Bundle.type`deve essere `"collection"`
+ Deve contenere esattamente una risorsa Claim
+ Tutte le risorse referenziate devono essere incluse nel pacchetto
### Convalida del reclamo
+ Deve essere conforme al profilo PAS Claim Inquiry
+ `Claim.use`deve essere `"preauthorization"`
+ `Claim.status`deve essere `"active"`
+ Campi obbligatori:`patient`,`insurer`,`provider`, `created`
### Convalida delle risorse
+ Tutte le risorse devono essere conformi ai rispettivi profili di richiesta PAS
+ Devono essere presenti le risorse di supporto necessarie (paziente, organizzazione assicurativa, organizzazione fornitrice)
+ I riferimenti incrociati devono essere validi e risolvibili all'interno del pacchetto
## Specifiche prestazionali
| Metrica | Specifiche |
| --- | --- |
| Limite di conteggio delle risorse | 500 risorse per pacchetto |
| Limite di dimensione del pacchetto | Massimo 5 MB |
## Autorizzazioni richieste
Per utilizzare l'`$inquire`operazione, assicurati che il tuo ruolo IAM abbia:
+ `healthlake:InquirePreAuthClaim`- Per richiamare l'operazione
**SMART su FHIR Scopes**
**Ambiti minimi richiesti:**
+ **SMART v1:** `user/ClaimResponse.read`
+ **SMART versione 2:** `user/ClaimResponse.s`
## Note importanti sull'implementazione
### Comportamento di ricerca
Quando invii una richiesta, HealthLake cerca ClaimResponse utilizzando:
+ **Riferimento del paziente** riportato nel reclamo inserito
+ **Riferimento dell'assicuratore riportato** nella Richiesta inserita
+ **Riferimento al fornitore** riportato nel reclamo inserito
+ **Data di creazione** in base alla richiesta di immissione (come filtro temporale)
**Corrispondenze** multiple: se più ClaimResponses corrispondono ai criteri di ricerca, HealthLake restituisce tutti i risultati corrispondenti. È necessario utilizzare il `ClaimResponse.created` timestamp più recente per identificare lo stato più recente.
### Reclami aggiornati
Se hai inviato più aggiornamenti alla stessa autorizzazione preventiva (ad esempio, Claim v1.1, v1.2, v1.3), l'`$inquire`operazione recupererà quelli ClaimResponse associati alla **versione più recente** in base ai criteri di ricerca forniti.
### Operazione di sola lettura
L'`$inquire`operazione:
+ Recupera **lo** stato di autorizzazione esistente
+ **Restituisce** il più recente ClaimResponse
+ **Non** modifica o aggiorna alcuna risorsa
+ **Non** crea nuove risorse
+ **Non** attiva una nuova elaborazione delle autorizzazioni
## Esempio di workflow
**Tipico flusso di lavoro di richiesta di autorizzazione preventiva**
```
1. Provider submits PA request
POST /Claim/$submit
→ Returns ClaimResponse with outcome="queued"
2. Payer reviews request (asynchronous)
→ Updates ClaimResponse status internally
3. Provider checks status
POST /Claim/$inquire
→ Returns ClaimResponse with outcome="queued" (still pending)
4. Provider checks status again later
POST /Claim/$inquire
→ Returns ClaimResponse with outcome="complete", disposition="Approved"
```
## Operazioni correlate
+ `Claim/$submit`- Invia una nuova richiesta di autorizzazione preventiva o aggiornane una esistente
+ `Patient/$everything`- Recupera i dati completi del paziente per il contesto di autorizzazione preventiva
# Recupero dei dettagli concettuali con `$lookup`
AWS HealthLake ora supporta l'`$lookup`operazione per CodeSystem le risorse, consentendoti di recuperare dettagli su un concetto specifico in un sistema di codice fornendo informazioni identificative come il codice. Questa operazione è particolarmente utile quando è necessario:
+ Recuperare informazioni dettagliate su codici medici specifici
+ Convalida i significati e le proprietà dei codici
+ Accedi alle definizioni e alle relazioni dei concetti
+ Supporta il processo decisionale clinico con dati terminologici accurati
## Utilizzo
L'`$lookup`operazione può essere richiamata sulle CodeSystem risorse utilizzando i metodi GET e POST:
**Operazioni supportate**
```
GET [base]/CodeSystem/$lookup?system=http://snomed.info/sct&code=73211009&version=20230901
POST [base]/CodeSystem/$lookup
```
## Parametri supportati
HealthLake supporta un sottoinsieme di parametri FHIR R4: `$lookup`
| Parametro | Tipo | Campo obbligatorio | Description |
| --- | --- | --- | --- |
| code | code | Sì | Il codice concettuale che stai cercando (ad esempio, «71620000" in SNOMED CT) |
| system | uri | Sì | [L'URL canonico del sistema di codici (ad esempio, "http://snomed.info/sct «)](http://snomed.info/sct) |
| version | stringa | No | Versione specifica del sistema di codice |
## Esempi
**Richiesta GET**
```
GET [base]/CodeSystem/$lookup?system=http://snomed.info/sct&code=71620000&version=2023-09
```
**Richiesta POST**
```
POST [base]/CodeSystem/$lookup
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "system",
"valueUri": "http://snomed.info/sct"
},
{
"name": "code",
"valueCode": "71620000"
},
{
"name": "version",
"valueString": "2023-09"
}
]
}
```
**Risposta di esempio**
L'operazione restituisce una risorsa Parameters contenente i dettagli del concetto:
```
{
"resourceType": "Parameters",
"parameter": [{
"name": "name",
"valueString": "SNOMED CT Fractures"
},
{
"name": "version",
"valueString": "2023-09"
},
{
"name": "display",
"valueString": "Fracture of femur"
},
{
"name": "property",
"part": [{
"name": "code",
"valueCode": "child"
},
{
"name": "value",
"valueCode": "263225007"
},
{
"name": "description",
"valueString": "Fracture of neck of femur"
}
]
},
{
"name": "property",
"part": [{
"name": "code",
"valueCode": "child"
},
{
"name": "value",
"valueCode": "263227004"
},
{
"name": "description",
"valueString": "Fracture of shaft of femur"
}
]
}
]
}
```
## Parametri di risposta
La risposta include i seguenti parametri, se disponibili:
| Parametro | Tipo | Description |
| --- | --- | --- |
| name | stringa | Nome del sistema di codici |
| version | stringa | Versione del sistema di codici |
| display | stringa | Visualizza il nome del concetto |
| designation | BackboneElement | Rappresentazioni aggiuntive per questo concetto. |
| property | BackboneElement | Proprietà aggiuntive del concetto (definizione, relazioni, ecc.) |
## Comportamento
L'`$lookup`operazione:
1. Convalida i parametri richiesti (`code`e`system`)
1. Cerca il concetto all'interno del sistema di codice specificato memorizzato nel datastore
1. Restituisce informazioni dettagliate sul concetto, tra cui nome visualizzato, designazioni e proprietà.
1. Supporta ricerche specifiche per versione quando viene fornito il parametro `version`
1. Funziona solo su sistemi di codice archiviati in modo esplicito nel datastore HealthLake
## Gestione errori
L'operazione gestisce le seguenti condizioni di errore:
+ 400 Bad Request: `$lookup` operazione non valida (richiesta non conforme o parametri obbligatori mancanti)
+ 404 Not Found: Sistema di codice non trovato o codice non trovato nel sistema di codice specificato
## Avvertenze
In questa versione, non sono supportati:
+ `$lookup`operazione mediante chiamata a server terminologici esterni
+ `$lookup`operazione su CodeSystems gestita da HealthLake ma non archiviata in modo esplicito nel datastore
Per ulteriori informazioni sulle specifiche `$lookup` operative, consultate la documentazione di [FHIR](https://www.hl7.org/fhir/R4/codesystem-operation-lookup.html) R4. CodeSystem `$lookup`
# `$member-add`operazione per HealthLake
L'`$member-add`operazione FHIR aggiunge un membro (paziente) a una risorsa del Gruppo, in particolare a una lista di attribuzione dei membri. Questa operazione fa parte della DaVinci Member Attribution Implementation Guide e supporta il processo di riconciliazione per la gestione delle attribuzioni dei membri.
## Operazione Endpoint
```
POST [base]/datastore/{datastoreId}/r4/Group/{groupId}/$member-add
Content-Type: application/json
```
## Parameters
L'operazione accetta una risorsa FHIR Parameters con le seguenti combinazioni di parametri:
### Opzioni dei parametri
È possibile utilizzare una delle seguenti combinazioni di parametri:
Opzione 1: Member ID \$1 Provider NPI
`memberId` \$1 `providerNpi`
`memberId` \$1 `providerNpi` \$1 `attributionPeriod`
Opzione 2: riferimento per il paziente e riferimento per il fornitore
`patientReference` \$1 `providerReference`
`patientReference` \$1 `providerReference` \$1 `attributionPeriod`
### Dettagli dei parametri
MemberID (opzionale)
L'identificatore del membro da aggiungere al gruppo.
Tipo: identificatore
Sistema: sistema di identificazione del paziente
```
{
"name": "memberId",
"valueIdentifier": {
"system": "http://example.org/patient-id",
"value": "patient-new"
}
}
```
ProviderNPI (opzionale)
Il National Provider Identifier (NPI) del provider attribuito.
Tipo: identificatore
Sistema: http://terminology.hl7. org/CodeSystem/NPI
```
{
"name": "providerNpi",
"valueIdentifier": {
"system": "http://terminology.hl7.org/CodeSystem/NPI",
"value": "1234567890"
}
}
```
Riferimento per il paziente (opzionale)
Riferimento diretto alla risorsa per il paziente da aggiungere.
Tipo: riferimento
```
{
"name": "patientReference",
"valueReference": {
"reference": "Patient/patient-123"
}
}
```
ProviderReference (opzionale)
Riferimento diretto alla risorsa del provider.
Tipo: riferimento
```
{
"name": "providerReference",
"valueReference": {
"reference": "Practitioner/provider-456"
}
}
```
Periodo di attribuzione (opzionale)
Il periodo di tempo durante il quale il paziente viene attribuito al fornitore.
Tipo: Periodo
```
{
"name": "attributionPeriod",
"valuePeriod": {
"start": "2024-07-15",
"end": "2025-07-14"
}
}
```
## Esempi di richieste
### Utilizzo dell'ID membro e del provider NPI
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "memberId",
"valueIdentifier": {
"system": "http://example.org/patient-id",
"value": "patient-new"
}
},
{
"name": "providerNpi",
"valueIdentifier": {
"system": "http://terminology.hl7.org/CodeSystem/NPI",
"value": "1234567890"
}
},
{
"name": "attributionPeriod",
"valuePeriod": {
"start": "2024-07-15",
"end": "2025-07-14"
}
}
]
}
```
### Utilizzo dei riferimenti di pazienti e fornitori
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "patientReference",
"valueReference": {
"reference": "Patient/patient-123"
}
},
{
"name": "providerReference",
"valueReference": {
"reference": "Practitioner/provider-456"
}
},
{
"name": "attributionPeriod",
"valuePeriod": {
"start": "2024-07-15",
"end": "2025-07-14"
}
}
]
}
```
## Formato della risposta
### Risposta di aggiunta riuscita
```
HTTP Status: 200 OK
Content-Type: application/fhir+json
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "success",
"code": "informational",
"details": {
"text": "Member Patient/patient-new successfully added to the Member Attribution List."
}
}
]
}
```
### Risposte agli errori
Sintassi di richiesta non valida
Stato HTTP: 400 Richiesta errata
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "invalid",
"details": {
"text": "Invalid parameter combination provided"
}
}
]
}
```
Risorsa non trovata
Stato HTTP: 404 non trovato
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "not-found",
"details": {
"text": "Resource not found."
}
}
]
}
```
Conflitto di versione
Stato HTTP: conflitto 409
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "conflict",
"details": {
"text": "Resource version conflict detected"
}
}
]
}
```
Stato di attribuzione non valido
Stato HTTP: 422 Entità non processabile
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "business-rule",
"details": {
"text": "Cannot add member to Attribution List with status 'final'. Status must be 'draft' or 'open'."
}
}
]
}
```
## Regole aziendali
Convalida dello stato di attribuzione
L'operazione può essere eseguita solo quando lo stato di attribuzione del gruppo è:
+ `draft`
+ `open`
Le operazioni non sono consentite quando lo stato è`final`.
Prevenzione della duplicazione dei membri
Il sistema impedisce l'aggiunta di membri duplicati in base alla combinazione unica di:
+ Identificatore del membro
+ Identificativo del pagatore
+ Identificatore di copertura
Convalida del periodo di copertura
Quando ne `attributionPeriod` viene fornita una, questa deve rientrare nei limiti del periodo di copertura del socio. Il sistema consentirà di:
+ Cerca la risorsa Coverage del socio
+ Usa la copertura più recente (VersionID più alto) se ne esistono più
+ Verifica che il periodo di attribuzione non superi il periodo di copertura
Convalida del riferimento
Quando vengono forniti sia l'ID che il riferimento per la stessa risorsa (paziente o fornitore), il sistema verifica che corrispondano alla stessa risorsa.
Quando vengono forniti entrambi i campi ID e reference.identifier per la stessa risorsa (paziente o fornitore), viene generato un errore.
## Autenticazione e autorizzazione
L'operazione richiede l'autorizzazione SMART on FHIR per:
+ Autorizzazioni di lettura: per convalidare le risorse di pazienti, fornitori e gruppi
+ Autorizzazioni di ricerca: per trovare risorse in base all'identificatore
+ Aggiorna le autorizzazioni: per modificare la risorsa del gruppo
## Comportamento operativo
Aggiornamenti delle risorse
+ Aggiorna l'ID della versione della risorsa del gruppo
+ Crea una voce di cronologia con lo stato originale della risorsa prima dell'operazione
+ Aggiunge le informazioni sui membri all'array Group.member con:
+ Riferimento al paziente in entity.reference
+ Periodo di attribuzione in periodo
+ Informazioni sulla copertura e sul fornitore nei campi di estensione
Fasi di convalida
+ Convalida dei parametri: garantisce combinazioni di parametri valide
+ Esistenza di risorse: verifica l'esistenza di risorse per pazienti, fornitori e gruppi
+ Stato di attribuzione: conferma che lo stato del gruppo consente modifiche
+ Duplicate Check: impedisce l'aggiunta di membri esistenti
+ Convalida della copertura: garantisce che il periodo di attribuzione rientri nei limiti di copertura
## Limitazioni
+ Tutte le risorse referenziate devono esistere all'interno dello stesso datastore
+ L'operazione funziona solo con le risorse del Member Attribution List Group
+ I periodi di attribuzione devono rientrare nei limiti di copertura
+ Non è possibile modificare i gruppi con lo stato «finale»
# `$member-match`operazione per HealthLake
AWS HealthLake ora supporta l'`$member-match`operazione Patient Resources, consentendo alle organizzazioni sanitarie di trovare l'identificatore univoco di un membro in diversi sistemi sanitari utilizzando informazioni demografiche e di copertura. Questa operazione è essenziale per raggiungere la conformità CMS e facilitare lo scambio sicuro payer-to-payer dei dati, mantenendo al contempo la privacy dei pazienti.
Questa operazione è particolarmente utile quando è necessario:
+ Consentire lo scambio sicuro di dati sanitari tra le organizzazioni
+ Mantieni la continuità dell'assistenza ai pazienti tra diversi sistemi
+ Supporta i requisiti di conformità CMS
+ Facilita l'identificazione accurata dei membri attraverso le reti sanitarie
## Utilizzo
L'`$member-match`operazione può essere richiamata sulle risorse del paziente utilizzando il metodo POST:
```
POST [base]/Patient/$member-match
```
## Parametri supportati
HealthLake supporta i seguenti parametri FHIR`$member-match`:
| Parametro | Tipo | Obbligatorio | Predefinita | Description |
| --- | --- | --- | --- | --- |
| MemberPatient | Paziente | Sì | — | Risorsa per il paziente contenente informazioni demografiche relative al membro da abbinare |
| CoverageToMatch | Copertura | Sì | — | Risorsa di copertura che verrà utilizzata per il confronto con i record esistenti |
| CoverageToLink | Copertura | No | — | Risorsa di copertura da collegare durante il processo di abbinamento |
| Consenso | Consenso | No | — | Risorsa di consenso a fini di autorizzazione |
## Esempi
### Richiesta POST con parametri
```
POST [base]/Patient/$member-match
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"name": [
{
"family": "Jones",
"given": ["Sarah"]
}
],
"gender": "female",
"birthDate": "1985-05-15"
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"status": "active",
"beneficiary": {
"reference": "Patient/1"
},
"relationship": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code": "self",
"display": "Self"
}
]
},
"payor": [
{
"reference": "Organization/payer456"
}
]
}
},
{
"name": "Consent",
"resource": {
"resourceType": "Consent",
"status": "active",
"scope": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentscope",
"code": "patient-privacy"
}
]
},
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "IDSCL"
}
]
}
],
"patient": {
"reference": "Patient/1"
},
"performer": [
{
"reference": "Patient/patient123"
}
],
"sourceReference": {
"reference": "Document/someconsent"
},
"policy": [
{
"uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#regular"
}
]
}
}
]
}
```
### Risposta di esempio
L'operazione restituisce una risorsa Parameters contenente i risultati corrispondenti:
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "MemberIdentifier",
"valueIdentifier": {
"system": "http://hospital.org/medical-record-number",
"value": "MRN-123456"
}
},
{
"name": "MemberId",
"valueReference": {
"reference": "Patient/patient123"
}
},
{
"name": "matchAlgorithm",
"valueString": "DEMOGRAPHIC_MATCH"
},
{
"name": "matchDetails",
"valueString": "Demographic match: DOB + Name"
},
{
"name": "matchedFields",
"valueString": "given,birthdate,gender,family"
}
]
}
```
## Parametri di risposta
La risposta include i seguenti parametri quando viene trovata una corrispondenza:
| Parametro | Tipo | Description |
| --- | --- | --- |
| MemberIdentifier | Identificatore | L'identificatore univoco per il membro corrispondente |
| MemberId | Documentazione di riferimento | Riferimento alla risorsa Patient |
| Match Algoritm | Stringa | Tipo di algoritmo di corrispondenza utilizzato (EXACT\$1MATCH, STRONG\$1MATCH o DEMOGRAPHIC\$1MATCH) |
| Dettagli della partita | Stringa | Informazioni dettagliate sul processo di abbinamento |
| Campi corrispondenti | Stringa | Elenco di campi specifici che sono stati abbinati correttamente |
## Algoritmi di corrispondenza
L'`$member-match`API utilizza un approccio di abbinamento a più livelli per garantire un'identificazione accurata dei membri:
EXACT\$1MATCH
Utilizza l'identificatore del paziente combinato con la copertura SubscriberId
Fornisce il massimo livello di confidenza per l'abbinamento dei membri
STRONG\$1MATCH
Utilizza Patient Identifier con informazioni minime sulla copertura
Offre un'elevata affidabilità quando non vengono soddisfatti i criteri di corrispondenza esatti
ABBINAMENTO DEMOGRAFICO
Si basa su informazioni demografiche di base
Utilizzato quando non è possibile la corrispondenza basata su identificatori
## Comportamento
L'operazione: `$member-match`
+ Accetta come input i dati demografici dei pazienti, i dettagli sulla copertura e le informazioni facoltative sul consenso
+ Restituisce un identificatore di membro univoco che può essere utilizzato per le interazioni successive
+ Implementa la corrispondenza a più livelli (esatta, forte, demografica) per garantire l'identificazione accurata dei membri nei diversi sistemi sanitari
+ Salva tutte le informazioni di consenso fornite per scopi di autorizzazione futuri
+ Supporta lo scambio sicuro di payer-to-payer dati mantenendo al contempo la privacy del paziente
+ Conforme ai requisiti CMS per lo scambio di dati sanitari
## Autorizzazione
L'API utilizza il protocollo di autorizzazione SMART on FHIR con i seguenti ambiti richiesti:
+ `system/Patient.read`
+ `system/Coverage.read`
+ `system/Organization.read`(condizionale)
+ `system/Practitioner.read`(condizionale)
+ `system/PractitionerRole.read`(condizionale)
+ `system/Consent.write`(condizionale)
## Gestione errori
L'operazione gestisce le seguenti condizioni di errore:
+ `400 Bad Request`: `$member-match` operazione non valida (richiesta non conforme o parametri obbligatori mancanti)
+ `422 Unprocessable Entity`: nessuna corrispondenza o più corrispondenze trovate
# `$member-remove`operazione per HealthLake
L'`$member-remove`operazione consente di rimuovere membri da una lista di attribuzione dei membri FHIR (risorsa di gruppo) in. AWS HealthLake Questa operazione fa parte della DaVinci Member Attribution Implementation Guide e supporta il processo di riconciliazione per la gestione delle attribuzioni dei membri.
## Prerequisiti
+ AWS HealthLake Datastore FHIR
+ Autorizzazioni IAM appropriate per le operazioni HealthLake
+ Elenco di attribuzione dei membri (risorsa di gruppo) in bozza o in stato aperto
## Dettagli dell'operazione
Endpoint
`POST /Group/{id}/$member-remove`
Content Type
`application/fhir+json`
## Parameters
L'operazione accetta una risorsa FHIR Parameters con i seguenti parametri opzionali:
| Parametro | Cardinalità | Tipo | Description |
| --- | --- | --- | --- |
| memberId | 0.1.. | Identificatore | Identificativo aziendale del membro da rimuovere |
| ProviderNPI | 0.1.. | Identificatore | NPI del fornitore attribuito |
| Riferimento per il paziente | 0.. 1 | Documentazione di riferimento | Riferimento diretto alla risorsa per i pazienti |
| Riferimento del fornitore | 0.1.. | Documentazione di riferimento | Riferimento diretto alla risorsa del Fornitore (professionista o PractitionerRole organizzazione) |
| Riferimento alla copertura | 0.1.. | Documentazione di riferimento | Riferimento alla risorsa Coverage |
### Combinazioni di parametri supportate
Sono supportate le seguenti combinazioni di parametri:
+ `memberId`solo: rimuove tutte le attribuzioni per il membro specificato
+ `memberId`\$1 `providerNpi` - Rimuove le attribuzioni per la specifica combinazione membro-provider
+ `patientReference`solo: rimuove tutte le attribuzioni per il paziente specificato
+ `patientReference`\$1 `providerReference` - Rimuove le attribuzioni per la combinazione specifica paziente-operatore
+ `patientReference``providerReference`\$1 `coverageReference` - Rimuove l'attribuzione specifica in base al paziente, al fornitore e alla copertura
## Esempio di richiesta
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "patientReference",
"valueReference": {
"reference": "Patient/12345"
}
},
{
"name": "providerReference",
"valueReference": {
"reference": "Practitioner/67890"
}
}
]
}
```
## Risposta
### Risposta riuscita
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "result",
"valueBoolean": true
},
{
"name": "effectiveDate",
"valueDate": "2024-06-30"
},
{
"name": "status",
"valueCode": "inactive"
},
{
"name": "message",
"valueString": "Member successfully removed from attribution list"
}
]
}
```
## Comportamento
Requisiti di status
L'operazione funziona solo su elenchi di attribuzione con stato o `draft` `open`
Gli elenchi con `final` stato rifiuteranno l'operazione con un errore 422
Procedura di rimozione dei membri
*Bozze di elenchi di status*: i membri sono contrassegnati come inattivi (`inactive: true`) e la loro `changeType` estensione è aggiornata a `changed`
*Liste di stato aperte*: comportamento simile alla bozza di stato
*Elenchi di stato finali*: l'operazione è rifiutata
Convalida
I riferimenti vengono convalidati per garantire che esistano nel HealthLake datastore
Se vengono forniti sia l'identificatore che il riferimento per lo stesso tipo di risorsa, devono corrispondere alla stessa risorsa
Le combinazioni di parametri vengono convalidate in base ai modelli supportati
## Gestione errori
### Risposte di errore comuni
Risorsa non trovata (404)
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "not-found",
"details": {
"text": "Patient with identifier 'http://example.org/fhir/identifiers|99999' not found in system"
},
"diagnostics": "Cannot remove member from attribution list. Verify patient identifier and try again.",
"expression": ["memberId"]
}
]
}
```
Stato finale dell'elenco di attribuzione (422)
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "business-rule",
"details": {
"coding": [
{
"system": "http://hl7.org/fhir/us/davinci-atr/CodeSystem/atr-error-codes",
"code": "list-final",
"display": "Attribution list is final and cannot be modified"
}
]
},
"diagnostics": "Cannot modify attribution list with status 'final'. List modifications are not permitted after finalization.",
"expression": ["Group.status"]
}
]
}
```
Operazione non valida (400)
Restituito quando le combinazioni di parametri non sono valide o non sono corrette.
Trovate più corrispondenze (412)
Restituito quando i parametri forniti corrispondono a più membri nell'elenco di attribuzione.
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "Multiple members found matching the criteria"
}
]
}
```
## Best practice
+ *Usa parametri specifici*: quando possibile, utilizza la combinazione di parametri più specifica per evitare rimozioni involontarie
+ Stato della *lista di controllo: verifica lo stato* dell'elenco di attribuzione prima di tentare le rimozioni
+ *Gestisci gli errori con garbo*: implementa una corretta gestione degli errori per tutte le possibili condizioni di errore
+ *Convalida i riferimenti*: assicurati che tutte le risorse referenziate esistano prima di effettuare la richiesta
# Eliminazione delle risorse del comparto paziente con `$purge`
AWS HealthLake supporta l'`$purge`operazione, consentendo l'eliminazione permanente di tutte le risorse all'interno del compartimento del paziente. Questa operazione è particolarmente utile quando è necessario:
+ Rimuovere tutti i dati associati a un paziente
+ Rispetta le richieste di rimozione dei dati dei pazienti
+ Gestisci il ciclo di vita dei dati dei pazienti
+ Esegui una pulizia completa delle cartelle cliniche dei pazienti
## Utilizzo
L'`$purge`operazione può essere richiamata sulle risorse del paziente:
```
POST [base]/Patient/[ID]/$purge?deleteAuditEvent=true
```
## Parameters
| Parametro | Tipo | Obbligatorio | Predefinita | Description |
| --- | --- | --- | --- | --- |
| deleteAuditEvent | booleano | No | false | Se impostato su true, elimina gli eventi di controllo associati |
| \$1since | stringa | No | Ora di creazione del datastore | Una volta inserito, seleziona l'orario limite iniziale per trovare le risorse in base all'ora dell'ultima modifica. Non può essere utilizzato con start o end |
| start | stringa | No | Ora di creazione del datastore | Una volta inserito, seleziona l'orario limite per la ricerca delle risorse in base all'ora dell'ultima modifica. Può essere usato con fine |
| end | stringa | No | Ora di invio del lavoro | Una volta inserito, seleziona l'orario limite finale per trovare le risorse in base all'ora dell'ultima modifica |
## Esempi
**Richiesta di esempio**
```
POST [base]/Patient/example-patient/$purge?deleteAuditEvent=true
```
**Risposta di esempio**
```
{
"resourceType": "OperationOutcome",
"id": "purge-job",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "Purge job started successfully. Job ID: 12345678-1234-1234-1234-123456789012"
}
]
}
```
## Stato di un processo
Per verificare lo stato di un processo di eliminazione:
```
GET [base]/$purge/[jobId]
```
L'operazione restituisce informazioni sullo stato del lavoro:
```
{
"datastoreId": "36622996b1fcecb7e12ee2ee085308d3",
"jobId": "3dd1c7a5b6c0ef8c110f566eb87e2ef9",
"status": "COMPLETED",
"submittedTime": "2025-10-31T18:43:21.822Z"
}
```
## Comportamento
L'`$purge`operazione:
1. Processi in modo asincrono per gestire più risorse
1. Mantiene le transazioni ACID per l'integrità dei dati
1. Fornisce il monitoraggio dello stato del lavoro con il conteggio delle eliminazioni delle risorse
1. Rimuove definitivamente tutte le risorse presenti nel compartimento del paziente
1. Include una registrazione di controllo completa delle attività di eliminazione
1. Supporta l'eliminazione selettiva degli eventi di controllo
## Registrazione degli audit
Le `$purge` operazioni vengono registrate come Start FHIRBulk DeleteJob e Descrivi FHIRBulk DeleteJob con informazioni dettagliate sull'operazione.
## Limitazioni
+ Le risorse eliminate non verranno visualizzate nelle risposte di ricerca
+ Le risorse eliminate potrebbero essere temporaneamente inaccessibili durante l'elaborazione
+ Tutte le risorse presenti nel compartimento del paziente vengono rimosse definitivamente
# `$questionnaire-package`Operazione FHIR per HealthLake
L'`$questionnaire-package`operazione recupera un pacchetto completo contenente un questionario FHIR e tutte le sue dipendenze necessarie per il rendering e l'elaborazione del questionario. Questa operazione implementa la [Da Vinci Documentation Templates and Rules (DTR) Implementation Guide, che consente il rendering dinamico dei moduli per i requisiti di documentazione](https://hl7.org/fhir/us/davinci-dtr/OperationDefinition-questionnaire-package.html) nei flussi di lavoro sanitari.
## Come funziona
+ **Richiesta**: inviate i parametri che identificano il questionario o i questionari necessari, insieme alla copertura e al contesto dell'ordine
+ **Recupera**: HealthLake raccoglie il questionario e tutte le dipendenze (, librerie CQL, ecc.) ValueSets
+ **Package**: Tutte le risorse sono raggruppate in un formato standardizzato
+ **Rispondi**: Riceverai un pacchetto completo pronto per il rendering e la raccolta dei dati
**Casi d'uso**
+ **Documentazione di autorizzazione preventiva**: raccoglie le informazioni cliniche necessarie per le richieste di autorizzazione preventiva
+ **Requisiti di copertura**: raccogliere la documentazione necessaria per soddisfare i requisiti di copertura dei pagatori
+ **Clinical Data Exchange**: struttura dei dati clinici da presentare ai pagatori
+ **Moduli dinamici**: renderizza i questionari con dati precompilati sui pazienti e logica condizionale
## Endpoint API
```
POST /datastore/{datastoreId}/r4/Questionnaire/$questionnaire-package
Content-Type: application/fhir+json
```
## Parametri della richiesta
### Parametri di input
Il corpo della richiesta deve contenere una risorsa FHIR Parameters con i seguenti parametri:
| Parametro | Tipo | Cardinalità | Description |
| --- | --- | --- | --- |
| coverage | Copertura | 1.. \$1 (Obbligatorio) | Risorse/e di copertura per stabilire il membro e copertura della documentazione |
| questionnaire | canonico | 0.. \$1 | URL canonici per uno o più questionari specifici da restituire (la versione può includere) |
| order | Risorsa | 0.. \$1 | Ordina le risorse (DeviceRequest, ServiceRequest, MedicationRequest, Encounter, Appointment) per stabilire il contesto |
| changedSince | dateTime | 0.1. | Se presenti, restituisce solo le risorse modificate dopo questo timestamp |
### Regole di convalida dei parametri
È **necessario fornire almeno UNO dei seguenti elementi** (oltre a quelli obbligatori`coverage`):
+ Uno o più `questionnaire` canonici URLs
+ Una o più risorse `order`
**Combinazioni di richieste valide:**
+ `coverage` \$1 `questionnaire`
+ `coverage` \$1 `order`
+ `coverage` \$1 `questionnaire` \$1 `order`
## Richiesta di esempio
```
POST /datastore/example-datastore/r4/Questionnaire/$questionnaire-package
Content-Type: application/fhir+json
Authorization: Bearer
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coverage",
"resource": {
"resourceType": "Coverage",
"id": "example-coverage",
"status": "active",
"beneficiary": {
"reference": "Patient/example-patient"
},
"payor": [{
"reference": "Organization/example-payer"
}],
"class": [{
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "group"
}]
},
"value": "12345"
}]
}
},
{
"name": "questionnaire",
"valueCanonical": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0"
},
{
"name": "order",
"resource": {
"resourceType": "ServiceRequest",
"id": "example-service-request",
"status": "active",
"intent": "order",
"code": {
"coding": [{
"system": "http://www.ama-assn.org/go/cpt",
"code": "94660",
"display": "Continuous positive airway pressure ventilation (CPAP)"
}]
},
"subject": {
"reference": "Patient/example-patient"
}
}
},
{
"name": "changedSince",
"valueDateTime": "2024-01-01T00:00:00Z"
}
]
}
```
## Formato della risposta
### Risposta riuscita (200 OK)
L'operazione restituisce una risorsa FHIR Parameters contenente uno o più **Package Bundle**. Ogni pacchetto Package include:
| Tipo di ingresso | Cardinalità | Description |
| --- | --- | --- |
| Questionario | 1 | Il questionario da rendere |
| QuestionnaireResponse | 0.1.. | Risposta precompilata o parzialmente completata (se applicabile) |
| Libreria | 0.. \$1 | Librerie CQL contenenti logica condizionale e di precompilazione |
| ValueSet | 0.. \$1 | Espanso ValueSets (per scelte di risposta con <40 espansioni) |
**Example Esempio di risposta**
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "PackageBundle",
"resource": {
"resourceType": "Bundle",
"id": "questionnaire-package-example",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/DTR-QPackageBundle"]
},
"type": "collection",
"timestamp": "2024-03-15T10:30:00Z",
"entry": [
{
"fullUrl": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",
"resource": {
"resourceType": "Questionnaire",
"id": "home-oxygen-therapy",
"url": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",
"version": "2.0",
"status": "active",
"title": "Home Oxygen Therapy Documentation",
"item": [
{
"linkId": "1",
"text": "Patient diagnosis",
"type": "choice",
"answerValueSet": "http://example.org/fhir/ValueSet/oxygen-diagnoses"
}
]
}
},
{
"fullUrl": "http://example.org/fhir/Library/oxygen-prepopulation",
"resource": {
"resourceType": "Library",
"id": "oxygen-prepopulation",
"url": "http://example.org/fhir/Library/oxygen-prepopulation",
"version": "1.0",
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/library-type",
"code": "logic-library"
}]
},
"content": [{
"contentType": "text/cql",
"data": "bGlicmFyeSBPeHlnZW5QcmVwb3B1bGF0aW9u..."
}]
}
},
{
"fullUrl": "http://example.org/fhir/ValueSet/oxygen-diagnoses",
"resource": {
"resourceType": "ValueSet",
"id": "oxygen-diagnoses",
"url": "http://example.org/fhir/ValueSet/oxygen-diagnoses",
"status": "active",
"expansion": {
"timestamp": "2024-03-15T10:30:00Z",
"contains": [
{
"system": "http://hl7.org/fhir/sid/icd-10",
"code": "J44.0",
"display": "COPD with acute lower respiratory infection"
},
{
"system": "http://hl7.org/fhir/sid/icd-10",
"code": "J96.01",
"display": "Acute respiratory failure with hypoxia"
}
]
}
}
},
{
"fullUrl": "http://example.org/fhir/QuestionnaireResponse/example-prepopulated",
"resource": {
"resourceType": "QuestionnaireResponse",
"id": "example-prepopulated",
"questionnaire": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0",
"status": "in-progress",
"subject": {
"reference": "Patient/example-patient"
},
"basedOn": [{
"reference": "ServiceRequest/example-service-request"
}],
"item": [
{
"linkId": "1",
"text": "Patient diagnosis",
"answer": [{
"valueCoding": {
"system": "http://hl7.org/fhir/sid/icd-10",
"code": "J44.0",
"display": "COPD with acute lower respiratory infection"
}
}]
}
]
}
}
]
}
},
{
"name": "Outcome",
"resource": {
"resourceType": "OperationOutcome",
"issue": [{
"severity": "information",
"code": "informational",
"details": {
"text": "Successfully retrieved questionnaire package"
}
}]
}
}
]
}
```
## Flusso di lavoro operativo
**Come HealthLake elabora la tua richiesta**
Quando chiami`$questionnaire-package`, HealthLake effettua le seguenti operazioni:
1. **Identify Patient & Payer**: estrae il paziente e l'organizzazione assicurativa dal parametro. `coverage`
1. **Trova il questionario giusto**:
+ **Con `questionnaire`** **parametro**: utilizza l'URL canonico che hai fornito
+ **Con `order`** **parametro**: corrisponde al codice dell'ordine (CPT/HCPCS/LOINC) e al pagatore per trovare il questionario appropriato
1. **Raccogli le dipendenze**: recupera automaticamente tutto ciò che serve per il rendering del questionario:
+ **Librerie CQL** - Logica per domande condizionali e preliminari
+ **ValueSets**- Scelte di risposta (espanse automaticamente se <40 opzioni)
+ **QuestionnaireResponse**- Eventuali risposte esistenti in corso o completate
1. **Package tutto insieme**:
+ Raggruppa tutte le risorse (ogni risorsa è inclusa una sola volta)
+ Filtra per `changedSince` timestamp, se fornito
+ Aggiunge avvisi in `Outcome` caso di mancanza di risorse
**Risultato**: un pacchetto completo e autonomo pronto per il rendering.
## Risposte agli errori
### 400 Richiesta non valida
Restituito quando la convalida della richiesta fallisce.
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "required",
"details": {
"text": "At least one of 'questionnaire' or 'order' must be provided along with 'coverage'"
}
}]
}
```
### 4.2.4 Dipendenza non riuscita
Restituito quando una risorsa dipendente non può essere recuperata.
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "warning",
"code": "not-found",
"details": {
"text": "Referenced Library 'http://example.org/fhir/Library/missing-library' could not be retrieved"
}
}]
}
```
### 401 - Autorizzazione negata
Restituito quando le credenziali di autenticazione sono mancanti o non valide.
### 403 Non consentito
Restituito quando l'utente autenticato non è autorizzato ad accedere alle risorse richieste.
### 406 Non accettabile
Restituito quando non è possibile fornire il tipo di contenuto richiesto.
### 409 Conflitto
Restituito in caso di conflitto di versione o concorrenza.
### 410 Andato
Restituito quando la risorsa richiesta è stata eliminata definitivamente.
### 429 Troppe richieste
Restituito quando vengono superati i limiti di velocità.
### 500 - Errore interno del server
Restituito quando si verifica un errore imprevisto del server.
### 501 non implementato
Restituito quando l'operazione richiesta non è ancora implementata.
## Regole di convalida
### Convalida dell'input
+ `coverage`il parametro è **obbligatorio** (1.. \$1 cardinalità)
+ Almeno uno `questionnaire` o `order` deve essere fornito
+ Tutte le risorse di copertura devono essere risorse FHIR valide
+ Tutte le risorse dell'Ordine devono essere risorse FHIR valide
+ Canonical URLs deve essere formattato correttamente
+ `changedSince`deve essere un DateTime ISO 8601 valido
### QuestionnaireResponse convalida
+ `status`deve essere appropriato (`in-progress`,`completed`,`amended`)
+ La struttura deve corrispondere al questionario di riferimento
+ `basedOn`deve fare riferimento a risorse Order valide
+ `subject`deve fare riferimento a risorse valide per i pazienti
### Deduplicazione delle risorse
+ Ogni risorsa appare solo una volta nel pacchetto
+ Eccezione: è possibile includere entrambe versioni diverse della stessa risorsa
+ Le risorse sono identificate in base all'URL e alla versione canonici
## Specifiche prestazionali
| Metrica | Specifiche |
| --- | --- |
| Limite di conteggio delle risorse | 500 risorse per pacchetto |
| Limite di dimensione del pacchetto | Massimo 5 MB |
## Autorizzazioni richieste
Per utilizzare l'`$questionnaire-package`operazione, assicurati che il tuo ruolo IAM abbia:
+ `healthlake:QuestionnairePackage`- Per richiamare l'operazione
+ `healthlake:ReadResource`- Per recuperare il questionario e le risorse dipendenti
+ `healthlake:SearchWithPost`- Per cercare risorse correlate QuestionnaireResponse
**SMART su FHIR Scopes**
**Ambiti minimi richiesti:**
+ **SMART v1:** `user/Questionnaire.read user/Library.read user/ValueSet.read user/QuestionnaireResponse.read`
+ **SMART versione 2:** `user/Questionnaire.rs user/Library.rs user/ValueSet.rs user/QuestionnaireResponse.rs`
## Note importanti sull'implementazione
### Strategia di recupero delle risorse
**Priorità di identificazione del questionario:**
+ **URL canonico** (se il `questionnaire` parametro è stato fornito) - Priorità massima
+ **Analisi dell'ordine** (se il `order` parametro è fornito):
+ Abbina i codici degli ordini (CPT, HCPCS, LOINC) alle politiche mediche dei paganti
+ Utilizza Coverage Payor per filtrare i questionari specifici per ciascun pagatore
+ Prendi in considerazione i codici dei motivi per un contesto aggiuntivo
### Risoluzione delle dipendenze
**Librerie CQL:**
+ Recuperato tramite l'`cqf-library`estensione sulle risorse del questionario
+ Recupera ricorsivamente le librerie dipendenti tramite type `Library.relatedArtifact` `depends-on`
+ Tutte le dipendenze della libreria sono incluse nel pacchetto
**ValueSets:**
+ Si espandono automaticamente se contengono meno di 40 concetti
+ ValueSets I più grandi sono inclusi senza espansione
+ ValueSets a cui si fa riferimento sia nel Questionario che nelle risorse della Libreria sono incluse
### QuestionnaireResponse prepopolazione
L'operazione può restituire un file QuestionnaireResponse con dati precompilati quando:
+ Viene trovata una risposta esistente in corso o completata
+ La logica CQL nelle librerie associate può estrarre dati dalle cartelle cliniche dei pazienti
+ La risposta è collegata all'ordine e alla copertura pertinenti
**Criteri di ricerca per QuestionnaireResponse:**
| Parametro di ricerca | Percorso FHIR | Description |
| --- | --- | --- |
| based-on | QuestionnaireResponse.basedOn | Collegamenti a o ServiceRequest CarePlan |
| patient | QuestionnaireResponse.subject | Il paziente che è il soggetto |
| questionnaire | QuestionnaireResponse.questionnaire | Il questionario a cui si sta rispondendo |
### Filtraggio delle risorse modificato
Quando viene fornito il `changedSince` parametro:
+ Sono incluse solo le risorse modificate **dopo** il timestamp specificato
+ Se nessuna risorsa è stata modificata, ritorna `200 OK` con un pacchetto vuoto
+ Utile per aggiornamenti incrementali e strategie di memorizzazione nella cache
+ Il confronto dei timestamp utilizza il campo delle risorse `meta.lastUpdated`
### Pacchetti multipli
L'operazione può restituire **più Package Bundle** quando:
+ Vengono richiesti più questionari tramite canonical URLs
+ Ordini multipli richiedono questionari diversi
+ Sono applicabili versioni diverse dello stesso questionario
Ogni Package Bundle è autonomo con tutte le dipendenze necessarie.
## Casi di utilizzo comune
### Caso d'uso 1: documentazione di autorizzazione preventiva
**Scenario**: un fornitore deve raccogliere la documentazione per un'autorizzazione preventiva di ossigenoterapia domiciliare.
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coverage",
"resource": { /* Patient's insurance coverage */ }
},
{
"name": "order",
"resource": {
"resourceType": "ServiceRequest",
"code": {
"coding": [{
"system": "http://www.ama-assn.org/go/cpt",
"code": "94660"
}]
}
}
}
]
}
```
**Risultato**: restituisce un pacco con il questionario di ossigenoterapia, precompilato con i dati anagrafici dei pazienti e i codici di diagnosi dell'EHR.
### Caso d'uso 2: recupero di una versione specifica del questionario
**Scenario**: un provider necessita di una versione specifica di un questionario per la conformità.
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coverage",
"resource": { /* Coverage resource */ }
},
{
"name": "questionnaire",
"valueCanonical": "http://example.org/fhir/Questionnaire/dme-request|3.1.0"
}
]
}
```
**Risultato**: restituisce esattamente la versione 3.1.0 del questionario di richiesta DME con tutte le dipendenze.
### Caso d'uso 3: verifica la presenza di aggiornamenti
**Scenario**: un provider desidera verificare se alcune risorse del questionario sono state aggiornate dall'ultimo recupero.
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coverage",
"resource": { /* Coverage resource */ }
},
{
"name": "questionnaire",
"valueCanonical": "http://example.org/fhir/Questionnaire/medication-request"
},
{
"name": "changedSince",
"valueDateTime": "2024-03-01T00:00:00Z"
}
]
}
```
**Risultato**: restituisce solo le risorse che sono state modificate dopo il 1° marzo 2024 o un pacchetto vuoto se non è cambiato nulla.
### Caso d'uso 4: ordini multipli
**Scenario**: un provider invia più richieste di assistenza che possono richiedere questionari diversi.
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coverage",
"resource": { /* Coverage resource */ }
},
{
"name": "order",
"resource": { /* ServiceRequest for imaging */ }
},
{
"name": "order",
"resource": { /* ServiceRequest for DME */ }
}
]
}
```
**Risultato**: restituisce più Package Bundle, uno per ogni questionario applicabile.
## Integrazione con Other Da Vinci IGs
### Discovery dei requisiti di copertura (CRD)
**Integrazione del flusso di lavoro:**
+ Il fornitore ordina un servizio nel proprio EHR
+ Il CRD si blocca, verifica dei requisiti di copertura
+ Il pagatore risponde indicando che è necessaria la documentazione
+ Il provider chiama `$questionnaire-package` per recuperare il modulo di documentazione
+ Il provider completa il questionario
+ La documentazione viene inviata tramite PAS o CDex
### Support di autorizzazione preventiva (PAS)
**Integrazione del flusso di lavoro:**
+ Utilizzare `$questionnaire-package` per recuperare i requisiti di documentazione
+ Completare il modulo QuestionnaireResponse con i dati clinici richiesti
+ Inviare l'autorizzazione preventiva utilizzando `Claim/$submit` con il QuestionnaireResponse
+ Controlla lo stato utilizzando `Claim/$inquire`
### Data Exchange clinico (CDex)
**Integrazione del flusso di lavoro:**
+ Il pagante richiede documentazione aggiuntiva per un reclamo
+ Il fornitore utilizza `$questionnaire-package` per recuperare il modulo di raccolta dei dati strutturati
+ Il fornitore completa il QuestionnaireResponse
+ La documentazione viene inviata al pagatore tramite CDex il flusso di lavoro in allegato
## Guida alla risoluzione dei problemi
### Problema: nessun questionario restituito
**Possibili cause:**
+ L'URL canonico non corrisponde a nessun questionario nell'archivio dati
+ Il codice dell'ordine non corrisponde a nessun questionario nella politica medica del pagatore
+ Il beneficiario della copertura non dispone di questionari associati
**Soluzioni:**
+ Verifica che l'URL canonico sia corretto e che il questionario esista
+ Verifica che i codici d'ordine (CPT/HCPCS) siano specificati correttamente
+ Conferma che i questionari siano configurati per il pagatore o l'organizzazione
### Problema: dipendenze mancanti nel pacchetto
**Possibili cause:**
+ Libreria referenziata o ValueSet non esiste nell'archivio dati
+ I riferimenti alla libreria sono interrotti o errati
+ ValueSet espansione non riuscita
**Soluzioni:**
+ Controlla il `Outcome` parametro per gli avvisi relativi alle risorse mancanti
+ Verifica che tutte le risorse di riferimento esistano nel tuo archivio dati
+ Assicurati che ValueSet URLs siano corretti e risolvibili
### Problema: Package vuoto con ChangedSince
**Possibili cause:**
+ Questo è il comportamento previsto: nessuna risorsa è stata modificata dopo il timestamp specificato
**Soluzioni:**
+ Usa la versione cache del pacchetto
+ Rimuovi il `changedSince` parametro per recuperare il pacchetto completo
### Problema: QuestionnaireResponse non precompilato
**Possibili cause:**
+ Nessun elemento esistente QuestionnaireResponse trovato
+ La logica della libreria CQL non è in grado di estrarre i dati richiesti
+ I dati del paziente sono mancanti o incompleti
**Soluzioni:**
+ Questo è prevedibile: non tutti i questionari hanno una logica di prepopolazione
+ Verificate che i dati del paziente esistano nell'archivio dati
+ Rivedi la logica della libreria CQL per i requisiti di estrazione dei dati
## Best practice
### 1. Usa Canonical URLs con le versioni
Specificate sempre i numeri di versione quando richiedete questionari specifici:
```
{
"name": "questionnaire",
"valueCanonical": "http://example.org/fhir/Questionnaire/dme|2.1.0"
}
```
**Perché**: garantisce la coerenza e previene modifiche impreviste quando i questionari vengono aggiornati.
### 2. Sfrutta ChangedSince per le prestazioni
Per i questionari a cui si accede di frequente, utilizza `changedSince` per ridurre al minimo il trasferimento dei dati:
```
{
"name": "changedSince",
"valueDateTime": "2024-03-10T15:30:00Z"
}
```
**Perché**: riduce la latenza e l'utilizzo della larghezza di banda recuperando solo le risorse aggiornate.
### 3. Includi informazioni complete sulla copertura
Fornisci dettagli completi sulla copertura per garantire la corretta selezione del questionario:
```
{
"name": "coverage",
"resource": {
"resourceType": "Coverage",
"beneficiary": { "reference": "Patient/123" },
"payor": [{ "reference": "Organization/payer-abc" }],
"class": [{ /* Group/plan information */ }]
}
}
```
**Perché**: aiuta a HealthLake identificare i questionari e i requisiti specifici del pagatore.
## Operazioni correlate
+ `Claim/$submit`- Invia richieste di autorizzazione preventiva con documentazione completa
+ `Claim/$inquire`- Verifica lo stato delle autorizzazioni precedenti inviate
+ `ValueSet/$expand`- Espandi ValueSets per visualizzare le opzioni di risposta
# `$submit`Operazione FHIR per HealthLake
L'`$submit`operazione consente di inviare elettronicamente richieste di autorizzazione preventiva ai pagatori per l'approvazione. Questa operazione implementa la [Da Vinci Prior Authorization Support (PAS) Implementation Guide](https://hl7.org/fhir/us/davinci-pas/), che fornisce un flusso di lavoro standardizzato basato su FHIR per l'invio di autorizzazioni preventive.
## Come funziona
+ **Invio: si invia** un pacchetto FHIR contenente la richiesta di autorizzazione preventiva e i dati clinici di supporto
+ **Convalida**: HealthLake convalida l'invio rispetto ai requisiti PAS
+ **Persiste**: tutte le risorse sono archiviate nel tuo archivio dati HealthLake
+ **Rispondi**: ricevi una risposta immediata con lo stato «in coda»
+ **Processo**: la decisione di autorizzazione viene elaborata in modo asincrono dal pagatore
## Endpoint API
```
POST /datastore/{datastoreId}/r4/Claim/$submit
Content-Type: application/fhir+json
```
## Struttura della richiesta
### Requisiti del pacchetto
La tua richiesta deve essere una risorsa FHIR Bundle con:
+ **Bundle.type: Deve** essere `"collection"`
+ **bundle.entry****: deve contenere esattamente una risorsa Claim con** `use = "preauthorization"`
+ **Risorse referenziate**: tutte le risorse a cui fa riferimento il reclamo devono essere incluse nel pacchetto
### Risorse obbligatorie
| Risorsa | Cardinalità | Profilo | Description |
| --- | --- | --- | --- |
| Reclamo | 1 | Reclamo PAS | La richiesta di autorizzazione preventiva |
| Paziente | 1 | Paziente PAS | Informazioni demografiche sui pazienti |
| Organizzazione (assicuratore) | 1 | Assicuratore PAS | Compagnia assicurativa |
| Organizzazione (fornitore) | 1 | Richiedente PAS | Fornitore di assistenza sanitaria che invia la richiesta |
| Copertura | 1 o più | Copertura PAS | Dettagli della copertura assicurativa |
### Risorse opzionali
| Risorsa | Cardinalità | Profilo | Description |
| --- | --- | --- | --- |
| Professionista | 0 o più | Professionista PAS | Operatori sanitari |
| PractitionerRole | 0 o più | PAS PractitionerRole | Ruoli del professionista |
| ServiceRequest | 0 o più | PAS ServiceRequest | Servizi medici richiesti |
| DeviceRequest | 0 o più | PAS DeviceRequest | Dispositivi medici richiesti |
| MedicationRequest | 0 o più | PAS MedicationRequest | Farmaci richiesti |
| DocumentReference | 0 o più | PAS DocumentReference | Documentazione clinica di supporto |
## Richiesta di esempio
```
POST /datastore/example-datastore/r4/Claim/$submit
Content-Type: application/fhir+json
Authorization: Bearer
{
"resourceType" : "Bundle",
"id" : "MedicalServicesAuthorizationBundleExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-request-bundle"]
},
"identifier" : {
"system" : "http://example.org/SUBMITTER_TRANSACTION_IDENTIFIER",
"value" : "5269367"
},
"type" : "collection",
"timestamp" : "2005-05-02T11:01:00+05:00",
"entry" : [{
"fullUrl" : "http://example.org/fhir/Claim/MedicalServicesAuthorizationExample",
"resource" : {
"resourceType" : "Claim",
"id" : "MedicalServicesAuthorizationExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim"]
},
"identifier" : [{
"system" : "http://example.org/PATIENT_EVENT_TRACE_NUMBER",
"value" : "111099"
}],
"status" : "active",
"type" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/claim-type",
"code" : "professional"
}]
},
"use" : "preauthorization",
"patient" : {
"reference" : "Patient/SubscriberExample"
},
"created" : "2005-05-02T11:01:00+05:00",
"insurer" : {
"reference" : "Organization/InsurerExample"
},
"provider" : {
"reference" : "Organization/UMOExample"
},
"priority" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/processpriority",
"code" : "normal"
}]
},
"insurance" : [{
"sequence" : 1,
"focal" : true,
"coverage" : {
"reference" : "Coverage/InsuranceExample"
}
}],
"item" : [{
"extension" : [{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-serviceItemRequestType",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1525",
"code" : "IN",
"display" : "Initial Medical Services Reservation"
}]
}
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-certificationType",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1322",
"code" : "I",
"display" : "Initial"
}]
}
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-authorizationNumber",
"valueString" : "1122344"
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-administrationReferenceNumber",
"valueString" : "33441122"
}],
"sequence" : 1,
"category" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1365",
"code" : "1",
"display" : "Medical Care"
}]
},
"productOrService" : {
"coding" : [{
"system" : "http://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets",
"code" : "99212",
"display" : "Established Office Visit"
}]
},
"servicedDate" : "2005-05-10",
"locationCodeableConcept" : {
"coding" : [{
"system" : "https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set",
"code" : "11"
}]
}
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Organization/UMOExample",
"resource" : {
"resourceType" : "Organization",
"id" : "UMOExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor"]
},
"identifier" : [{
"system" : "http://hl7.org/fhir/sid/us-npi",
"value" : "8189991234"
}],
"active" : true,
"type" : [{
"coding" : [{
"system" : "https://codesystem.x12.org/005010/98",
"code" : "X3"
}]
}],
"name" : "DR. JOE SMITH CORPORATION",
"address" : [{
"line" : ["111 1ST STREET"],
"city" : "SAN DIEGO",
"state" : "CA",
"postalCode" : "92101",
"country" : "US"
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Organization/InsurerExample",
"resource" : {
"resourceType" : "Organization",
"id" : "InsurerExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer"]
},
"identifier" : [{
"system" : "http://hl7.org/fhir/sid/us-npi",
"value" : "1234567893"
}],
"active" : true,
"type" : [{
"coding" : [{
"system" : "https://codesystem.x12.org/005010/98",
"code" : "PR"
}]
}],
"name" : "MARYLAND CAPITAL INSURANCE COMPANY"
}
},
{
"fullUrl" : "http://example.org/fhir/Coverage/InsuranceExample",
"resource" : {
"resourceType" : "Coverage",
"id" : "InsuranceExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-coverage"]
},
"status" : "active",
"subscriberId" : "1122334455",
"beneficiary" : {
"reference" : "Patient/SubscriberExample"
},
"relationship" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code" : "self"
},
{
"system" : "https://codesystem.x12.org/005010/1069",
"code" : "18"
}]
},
"payor" : [{
"reference" : "Organization/InsurerExample"
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Patient/SubscriberExample",
"resource" : {
"resourceType" : "Patient",
"id" : "SubscriberExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-subscriber"]
},
"extension" : [{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-militaryStatus",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/584",
"code" : "RU"
}]
}
}],
"identifier" : [{
"type" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "MB"
}]
},
"system" : "http://example.org/MIN",
"value" : "12345678901"
}],
"name" : [{
"family" : "SMITH",
"given" : ["JOE"]
}],
"gender" : "male"
}
}]
}
```
## Formato della risposta
### Risposta di successo (200 OK)
Riceverai un pacchetto di risposta PAS contenente:
+ **ClaimResponse**con e `outcome: "queued"` `status: "active"`
+ Tutte le risorse originali contenute nella tua richiesta
+ Timestamp di conferma della ricezione
```
{
"resourceType" : "Bundle",
"identifier": {
"system": "http://example.org/SUBMITTER_TRANSACTION_IDENTIFIER",
"value": "5269367"
},
"type" : "collection",
"timestamp" : "2005-05-02T11:02:00+05:00",
"entry" : [{
"fullUrl" : "http://example.org/fhir/ClaimResponse/PractitionerRequestorPendingResponseExample",
"resource" : {
"resourceType" : "ClaimResponse",
"id" : "PractitionerRequestorPendingResponseExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claimresponse"]
},
"identifier" : [{
"system" : "http://example.org/PATIENT_EVENT_TRACE_NUMBER",
"value" : "111099"
}],
"status" : "active",
"type" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/claim-type",
"code" : "professional"
}]
},
"use" : "preauthorization",
"patient" : {
"reference" : "Patient/SubscriberExample"
},
"created" : "2005-05-02T11:02:00+05:00",
"insurer" : {
"reference" : "Organization/InsurerExample"
},
"requestor" : {
"reference" : "PractitionerRole/ReferralPractitionerRoleExample"
},
"request" : {
"reference" : "Claim/MedicalServicesAuthorizationExample"
},
"outcome" : "queued"
}
},
{
"fullUrl" : "http://example.org/fhir/Claim/MedicalServicesAuthorizationExample",
"resource" : {
"resourceType" : "Claim",
"id" : "MedicalServicesAuthorizationExample",
"meta" : {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim|2.1.0"
]
},
"identifier" : [{
"system" : "http://example.org/PATIENT_EVENT_TRACE_NUMBER",
"value" : "111099"
}
}],
"status" : "active",
"type" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/claim-type",
"code" : "professional"
}]
},
"use" : "preauthorization",
"patient" : {
"reference" : "Patient/SubscriberExample"
},
"created" : "2005-05-02T11:01:00+05:00",
"insurer" : {
"reference" : "Organization/InsurerExample"
},
"provider" : {
"reference" : "Organization/UMOExample"
},
"priority" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/processpriority",
"code" : "normal"
}]
},
"insurance" : [{
"sequence" : 1,
"focal" : true,
"coverage" : {
"reference" : "Coverage/InsuranceExample"
}
}],
"item" : [{
"extension" : [{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-serviceItemRequestType",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1525",
"code" : "IN",
"display" : "Initial Medical Services Reservation"
}]
}
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-certificationType",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1322",
"code" : "I",
"display" : "Initial"
}]
}
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-authorizationNumber",
"valueString" : "1122344"
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-administrationReferenceNumber",
"valueString" : "33441122"
}],
"sequence" : 1,
"category" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1365",
"code" : "1",
"display" : "Medical Care"
}]
},
"productOrService" : {
"coding" : [{
"system" : "http://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets",
"code" : "99212",
"display" : "Established Office Visit"
}]
},
"servicedDate" : "2005-05-10",
"locationCodeableConcept" : {
"coding" : [{
"system" : "https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set",
"code" : "11"
}]
}
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Organization/UMOExample",
"resource" : {
"resourceType" : "Organization",
"id" : "UMOExample",
"meta" : {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor|2.1.0"
]
},
"identifier" : [{
"system" : "http://hl7.org/fhir/sid/us-npi",
"value" : "8189991234"
}],
"active" : true,
"type" : [{
"coding" : [{
"system" : "https://codesystem.x12.org/005010/98",
"code" : "X3"
}]
}],
"name" : "DR. JOE SMITH CORPORATION",
"address" : [{
"line" : ["111 1ST STREET"],
"city" : "SAN DIEGO",
"state" : "CA",
"postalCode" : "92101",
"country" : "US"
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Organization/InsurerExample",
"resource" : {
"resourceType" : "Organization",
"id" : "InsurerExample",
"meta" : {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer|2.1.0"
]
},
"identifier" : [{
"system" : "http://hl7.org/fhir/sid/us-npi",
"value" : "1234567893"
}],
"active" : true,
"type" : [{
"coding" : [{
"system" : "https://codesystem.x12.org/005010/98",
"code" : "PR"
}]
}],
"name" : "MARYLAND CAPITAL INSURANCE COMPANY"
}
},
{
"fullUrl" : "http://example.org/fhir/Coverage/InsuranceExample",
"resource" : {
"resourceType" : "Coverage",
"id" : "InsuranceExample",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-coverage",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-coverage|2.1.0"
]
},
"status" : "active",
"subscriberId" : "1122334455",
"beneficiary" : {
"reference" : "Patient/SubscriberExample"
},
"relationship" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code" : "self"
},
{
"system" : "https://codesystem.x12.org/005010/1069",
"code" : "18"
}]
},
"payor" : [{
"reference" : "Organization/InsurerExample"
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Patient/SubscriberExample",
"resource" : {
"resourceType" : "Patient",
"id" : "SubscriberExample",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-subscriber",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-beneficiary",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-beneficiary|2.1.0"
]
},
"extension" : [{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-militaryStatus",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/584",
"code" : "RU"
}]
}
}],
"identifier" : [{
"type" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "MB"
}]
},
"system" : "http://example.org/MIN",
"value" : "12345678901"
}],
"name" : [{
"family" : "SMITH",
"given" : ["JOE"]
}],
"gender" : "male"
}
}]
}
```
## Risposte agli errori
### 400 Richiesta non valida
Restituito quando il formato della richiesta non è valido o non è valido.
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "invalid",
"diagnostics": "The provided payload was invalid and could not be parsed correctly."
}]
}
```
### 412 Precondizione non riuscita
Restituito quando è già stata inviata la stessa richiesta di autorizzazione preventiva (è stato rilevato un invio duplicato).
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "processing",
"diagnostics": "PreAuth Claim already exists"
}]
}
```
**Idempotenza**
L'`$submit`operazione è idempotente. L'invio della stessa richiesta più volte non creerà richieste di autorizzazione preventiva duplicate. Riceverai invece un errore 412 che ti chiederà di utilizzare per `$inquire` verificare lo stato dell'invio originale.
### 422 Entità non processabile
Restituito quando la convalida FHIR fallisce.
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "required",
"diagnostics": "Bundle contains more than one preauthorization claim"
}]
}
```
## Regole di convalida
HealthLake esegue una convalida completa dell'invio:
### Convalida del pacchetto
+ Deve essere conforme al profilo PAS Request Bundle
+ `Bundle.type`deve essere `"collection"`
+ Può contenere più risorse per i reclami
+ Tuttavia, deve contenere esattamente una risorsa Claim da utilizzare in preautorizzazione
+ E questa risorsa Claim deve essere la prima voce del pacchetto
+ Tutte le risorse a cui si fa riferimento devono essere incluse nel pacchetto
### Convalida del reclamo
+ Deve essere conforme al profilo PAS Claim
+ `Claim.use`deve essere `"preauthorization"`
+ Campi obbligatori: `patient``insurer`,`provider`,`created`, `priority`
+ Gli identificatori aziendali devono essere presenti e validi
### Convalida delle risorse
+ Tutte le risorse devono essere conformi ai rispettivi profili PAS
+ Devono essere presenti le risorse di supporto necessarie (paziente, copertura, organizzazione)
+ I riferimenti incrociati devono essere validi e risolvibili all'interno del pacchetto
## Specifiche prestazionali
| Metrica | Specifiche |
| --- | --- |
| Limite di dimensione del pacchetto | Massimo 5 MB |
| Limite di numero di risorse | 500 risorse per pacchetto |
## Autorizzazioni richieste
Per utilizzare l'`$submit`operazione, è possibile utilizzare AWS Sigv4 o SMART su FHIR:
+ Assicurati che il tuo ruolo IAM abbia: `healthlake:SubmitPreAuthClaim` - Per chiamare l'operazione
**SMART su FHIR Scopes**
**Ambiti minimi richiesti:**
+ **SMART v1:** `user/Claim.write & .write`
+ **SMART versione 2:** `user/Claim.c & .c or system/*.*`
## Note importanti sull'implementazione
### Persistenza delle risorse
+ Tutte le voci del Bundle vengono memorizzate come risorse FHIR individuali nell'archivio dati
+ I dati forniti dal cliente vengono conservati quando vengono forniti IDs
+ La cronologia delle versioni viene conservata a fini di controllo
+ Il rilevamento dei duplicati previene i conflitti di risorse
### Comportamento di elaborazione
+ Ogni invio valido restituisce esattamente ClaimResponse un `"queued"` risultato
+ Gli invii non validi restituiscono codici di stato 400 o 422 con informazioni dettagliate sull'errore
+ Gli errori di sistema restituiscono i codici di stato 5xx appropriati
+ Tutti gli invii andati a buon fine restituiscono lo stato 200 con un messaggio Risolto ClaimResponse
### Requisiti del pacchetto
+ `Bundle.entry.fullUrl`i valori devono essere REST URLs o format `"urn:uuid:[guid]"`
+ Tutti gli invii GUIDs devono essere unici (ad eccezione delle stesse istanze di risorse)
+ Le risorse referenziate devono esistere all'interno del pacchetto o essere risolvibili
## Operazioni correlate
+ `Claim/$inquire`- Verifica lo stato di una richiesta di autorizzazione preventiva inviata
+ `Patient/$everything`- Recupera i dati completi del paziente per il contesto di autorizzazione preventiva
# Convalida delle risorse FHIR con `$validate`
AWS HealthLake ora supporta il `$validate` funzionamento delle risorse FHIR, consentendoti di convalidare una risorsa rispetto alle specifiche FHIR e di verificarne la conformità a un profilo specifico o a una definizione di risorsa di base senza eseguire alcuna operazione di storage. Questa operazione è particolarmente utile quando è necessario:
+ Convalidare i requisiti di conformità FHIR CMS
+ Testa le risorse prima di utilizzarle in produzione
+ Fornisci feedback di convalida in tempo reale mentre gli utenti modificano i dati clinici
+ Riduci gli invii di dati non validi per crearli e aggiornarli APIs
## Utilizzo
L'`$validate`operazione può essere richiamata sulle risorse FHIR utilizzando i metodi POST:
**Operazioni supportate**
```
POST [base]/[type]/[id]/$validate
POST [base]/[type]/$validate
```
## Payload supportati
**Risorsa di parametri**
HealthLake supporta i seguenti `$validate` parametri FHIR:
| Parametro | Tipo | Campo obbligatorio | Description |
| --- | --- | --- | --- |
| resource | Risorsa | Sì | La risorsa da convalidare |
| profile | canonico | No | URL canonico del profilo con cui eseguire la convalida |
| mode | code | No | Modalità di convalida:, oppure create update |
**Risorsa diretta con parametri di interrogazione**
| Parametro | Tipo | Campo obbligatorio | Description |
| --- | --- | --- | --- |
| profile | canonico | No | URL canonico del profilo con cui eseguire la convalida |
| mode | code | No | Modalità di convalida:, oppure create update |
## Esempi
**Richiesta POST di risorsa con payload ID e parametri**
```
POST [base]/Patient/example-patient/$validate
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "resource",
"resource": {
"resourceType": "Patient",
"id": "example-patient",
"name": [
{
"family": "Smith",
"given": ["John"]
}
],
"gender": "male",
"birthDate": "1990-01-01"
}
},
{
"name": "profile",
"valueCanonical": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
},
{
"name": "mode",
"valueString": "create"
}
]
}
```
**Richiesta POST per il tipo di risorsa e il payload dei parametri**
```
POST [base]/Patient/$validate
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "resource",
"resource": {
"resourceType": "Patient",
"name": [
{
"family": "Doe",
"given": ["Jane"]
}
],
"gender": "female",
"birthDate": "1985-05-15"
}
},
{
"name": "profile",
"valueCanonical": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
},
{
"name": "mode",
"valueString": "update"
}
]
}
```
**Richiesta di risorsa POST con ID e payload diretto della risorsa**
```
POST [base]/Patient/example-patient/$validate?profile=http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient&mode=create
Content-Type: application/fhir+json
{
"resourceType": "Patient",
"id": "example-patient",
"name": [
{
"family": "Smith",
"given": ["John"]
}
],
"gender": "male",
"birthDate": "1990-01-01"
}
```
**Richiesta POST per tipo di risorsa e payload diretto della risorsa**
```
POST [base]/Patient/$validate?profile=http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient&mode=create
Content-Type: application/fhir+json
{
"resourceType": "Patient",
"id": "example-patient",
"name": [
{
"family": "Smith",
"given": ["John"]
}
],
"gender": "male",
"birthDate": "1990-01-01"
}
```
**Risposta di esempio**
L'operazione restituisce una OperationOutcome risorsa con risultati di convalida:
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "Validation successful"
}
]
}
```
**Esempio di risposta con errori di convalida**
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "required",
"details": {
"text": "Missing required element"
},
"diagnostics": "Patient.identifier is required by the US Core Patient profile",
"location": [
"Patient.identifier"
]
},
{
"severity": "warning",
"code": "code-invalid",
"details": {
"text": "Invalid code value"
},
"diagnostics": "The provided gender code is not from the required value set",
"location": [
"Patient.gender"
]
}
]
}
```
## Comportamento
L'`$validate`operazione:
1. Convalida la risorsa rispetto alla specifica FHIR e alla definizione della risorsa di base
1. Verifica la conformità ai profili specificati quando viene fornito il parametro `profile`
1. Esegue la convalida in base alla modalità specificata (o) `create` `update`
1. Restituisce risultati di convalida dettagliati, inclusi errori, avvisi e messaggi informativi
1. Non esegue alcuna operazione di archiviazione, solo convalida
1. Restituisce HTTP 200 OK quando è possibile eseguire la convalida, indipendentemente dal fatto che vengano rilevati problemi di convalida
## Modalità di convalida
+ **create**: convalida la risorsa come se fosse in fase di creazione (nuova risorsa)
+ **update**: convalida la risorsa come se fosse in fase di aggiornamento (risorsa esistente)
## Gestione errori
L'operazione restituisce:
+ 200 OK: la convalida è stata eseguita correttamente (indipendentemente dal risultato della convalida)
+ 400 Bad Request: formato o parametri della richiesta non validi
+ 404 Not Found: Tipo di risorsa o profilo non trovato
Per ulteriori informazioni sulle specifiche `$validate` operative, consulta la documentazione delle [risorse `$validate` FHIR R4](https://www.hl7.org/fhir/R4/operation-resource-validate.html).