Introduzione e Informazioni Generali
Questo documento fornisce una guida tecnica completa per le funzioni API DICOMweb con metodi di esempio utilizzati tramite un'applicazione C# d'esempio. Include spiegazioni dettagliate di tutte le funzioni disponibili, coprendo sia i servizi standard DICOMweb (come QIDO-RS, WADO-RS e STOW-RS) sia gli endpoint API DICOMweb personalizzati sviluppati da PostDICOM. Queste funzioni sono progettate per essere utilizzate in chiamate lato server.
Per utilizzare i servizi DICOMweb di PostDICOM, Lei deve prima aver abilitato questa funzione per il Suo account e possedere credenziali utente valide. Se l'accesso DICOMweb non è ancora stato attivato per il Suo account e desidera integrare la Sua applicazione con PostDICOM, La invitiamo a contattarci per richiederne l'attivazione.
Nome Utente: Questa è la Sua credenziale di accesso principale, di solito il Suo indirizzo email. È univoca per il Suo account e viene utilizzata come nome utente nell'Autenticazione di Base (Basic Authentication).
Password: Questa è la password associata al Suo account PostDICOM. Viene utilizzata insieme al Suo nome utente durante l'Autenticazione di Base. Per una sicurezza ottimale, Le consigliamo vivamente di scegliere una password forte. La preghiamo di predisporre i necessari meccanismi di sicurezza nella Sua chiamata lato server affinché questo nome utente e questa password siano da Lei protetti adeguatamente.
Può gestire la Sua password e le impostazioni di sicurezza tramite la pagina del profilo del Suo account dopo aver effettuato l'accesso al Suo account PostDICOM
Archiviazione di Istanze DICOM (STOW-RS)
Questa funzione coordina il caricamento di tutti i file .dcm da una cartella locale specificata al server DICOMweb. Innanzitutto identifica tutti i file pertinenti, quindi utilizza metodi ausiliari per costruire e inviare una richiesta POST multipart/related autenticata per ciascun file, nel rispetto dello standard STOW-RS.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| DirectoryPath | string | Il percorso completo della directory locale contenente i file DICOM (.dcm) da caricare. |
Ricerca di Oggetti DICOM (QIDO-RS)
Questa funzione esegue una ricerca di oggetti DICOM utilizzando lo standard QIDO-RS, consentendo ricerche a livello di Studio, Serie o Istanza. In base al parametro di ricerca fornito (come ID Paziente, UID Istanza Studio o UID Istanza Serie), costruisce l'URL appropriato ed esegue una richiesta autenticata per recuperare i risultati corrispondenti dal server.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| PatientID | string | Opzionale. Utilizzato per identificare il paziente e cercare gli studi correlati. |
| StudyInstanceUID | string | Opzionale. Utilizzato per cercare uno studio specifico o tutte le serie all'interno di quello studio. |
| SeriesInstanceUID | string | Opzionale. Utilizzato per cercare tutte le istanze di immagine all'interno di una serie specifica. |
Recupero di Istanze DICOM (WADO-RS)
Questa funzione fornisce un menu interattivo per recuperare oggetti DICOM utilizzando lo standard WADO-RS. L'utente seleziona un livello di recupero (Studio, Serie o Istanza) e fornisce l'UID corrispondente. La funzione effettua quindi una richiesta autenticata ed elabora la risposta multipart/related, salvando ogni parte DICOM come file .dcm separato in una directory locale appena creata.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| StudyInstanceUID | string | Opzionale. Un identificatore univoco a livello globale per uno studio DICOM. Utilizzato per recuperare tutte le serie e le istanze associate a quello studio. |
| SeriesInstanceUID | string | Opzionale. Un identificatore univoco a livello globale per una serie all'interno di uno studio DICOM. Utilizzato per recuperare tutte le immagini in quella serie. |
| SOPInstanceUID | string | Opzionale. Un identificatore univoco per una singola istanza di immagine DICOM. Utilizzato per recuperare un'immagine specifica tramite WADO-RS. |
Crea Link di Condivisione
Questa funzione genera un link web sicuro per condividere uno o più ordini paziente con utenti esterni. Il link può essere protetto da password e facoltativamente consentire i download.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password per l'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| PatientOrderInfoList | List |
Elenco di stringhe JSON, ciascuna contenente una chiave "PatientOrderUuid", che identifica gli ordini paziente da condividere. |
| ExpireDate | string (YYYY-MM-DD) | Data di scadenza per il link di condivisione. Dopo questa data, il link verrà disabilitato. |
| SharePassword | string | Opzionale. Password richiesta per accedere al link di condivisione. Lasciare vuoto per l'accesso pubblico. |
| Downloadable | bool | Opzionale. Determina se gli studi DICOM sono scaricabili dal destinatario. |
Condivisione Ordine Paziente tramite URL
Questa funzione genera un URL condivisibile per gli ordini paziente selezionati, con opzioni aggiuntive di controllo degli accessi come i permessi di download e la protezione tramite password.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (email) dell'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password per l'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| OrderUuidList | List |
Elenco di UUID che identificano gli ordini paziente da condividere. |
| ExpireDate | string (YYYY-MM-DD) | Data dopo la quale il link di condivisione diventa inattivo. |
| SharePassword | string | Opzionale. Password richiesta per accedere al link condiviso. |
| UserCanDownloadStudies | bool | Opzionale. Se impostato su true, il destinatario può scaricare gli studi. |
Crea Cartella
Questa funzione viene utilizzata per creare una nuova cartella (un contenitore virtuale) all'interno dell'account PostDICOM per aiutare a organizzare gli ordini paziente.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| FolderName | string | Obbligatorio. Il nome visibile per la nuova cartella. |
| FolderDescription | string | Opzionale. Una descrizione testuale per la cartella. |
| ParentFolderUuid | string | Opzionale. L'UUID di una cartella esistente per creare la nuova cartella al suo interno. |
Cerca Cartella
Questa funzione trova le cartelle esistenti in base ai criteri di ricerca. Può includere facoltativamente l'elenco degli ordini paziente all'interno di ciascuna cartella trovata.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| ParentFolderUuid | string | Opzionale. L'UUID di una cartella per limitare la ricerca ai suoi elementi figlio. |
| FolderName | string | Opzionale. Un nome completo o parziale da cercare. |
| GetOrdersInFolder | bool | Opzionale. Se `true`, la risposta includerà un elenco di ordini paziente per ogni cartella trovata. |
Condivisione Cartella tramite URL
Questa funzione genera un URL sicuro e condivisibile per un'intera cartella e i suoi contenuti. Consente un controllo completo degli accessi impostando un titolo personalizzato, una descrizione, una password, una data di scadenza e specificando se i contenuti possono essere scaricati dal destinatario.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| FolderUuid | string | Obbligatorio. L'identificatore univoco (UUID) della cartella da condividere. |
| SharePassword | string | Opzionale. Una password per proteggere il link condiviso. Se lasciato vuoto, il link sarà accessibile al pubblico. |
| ShareTitle | string | Opzionale. Un titolo personalizzato per la pagina della cartella condivisa, visibile al destinatario. |
| ShareDescription | string | Opzionale. Una descrizione visualizzata nella pagina della cartella condivisa. |
| ExpireDate | string (YYYY-MM-DD) | Opzionale. La data in cui il link di condivisione diventerà automaticamente inattivo. |
| UserCanDownloadStudies | bool | Opzionale. Se `true`, i destinatari possono scaricare gli ordini paziente contenuti all'interno della cartella. |
Aggiungi Ordine alla Cartella
Questa funzione crea un'associazione tra un ordine paziente esistente e una cartella esistente. Si tratta di uno strumento organizzativo; non sposta né copia dati.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| PatientOrderUuid | string | Obbligatorio. L'UUID dell'ordine paziente da inserire in una cartella. |
| FolderUuidList | List |
Obbligatorio. Un elenco contenente l'UUID della cartella di destinazione. |
Assegna Ordine all'Utente
Questa funzione è uno strumento essenziale per il flusso di lavoro. Assegna un ordine paziente a un singolo utente, indicando che tale utente è ora responsabile di un'attività relativa a quell'ordine (es. refertazione).
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| PatientOrderUuid | string | Obbligatorio. L'UUID dell'ordine paziente che richiede un'azione. |
| AssignedUserUuid | string | Obbligatorio. L'UUID dell'utente specifico al quale verrà assegnata la responsabilità. |
Assegna Ordine al Gruppo di Utenti
In modo simile all'assegnazione a un singolo utente, questa funzione assegna un ordine paziente a un intero gruppo, abilitando flussi di lavoro basati sul team in cui qualsiasi membro del gruppo può gestire l'attività.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| PatientOrderUuid | string | Obbligatorio. L'UUID dell'ordine paziente da assegnare al gruppo. |
| AssignedUserGroupUuid | string | Obbligatorio. L'UUID del gruppo di utenti al quale verrà assegnato l'ordine. |
Crea Ordine Paziente
Questa funzione crea un nuovo ordine paziente per programmare e gestire gli studi di imaging all'interno del sistema. I parametri obbligatori devono essere forniti per una creazione corretta.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| InstitutionUuid | string | Obbligatorio. UUID dell'istituto in cui viene creato l'ordine paziente. |
| PatientName | string | Obbligatorio. Nome completo del paziente. |
| PatientId | string | Obbligatorio. Identificatore univoco del paziente come documento d'identità nazionale o MRN (Medical Record Number). |
| PatientBirthdate | string (YYYY-MM-DD) | Obbligatorio. Data di nascita del paziente in formato ISO. |
| Modality | string | Obbligatorio. Tipo di modalità come TC, RM, US, ecc. |
| OtherPatientId | string | Opzionale. Un identificatore aggiuntivo per il paziente, se applicabile. |
| PatientSex | string | Opzionale. Sesso del paziente (es. M, F, O). |
| StudyDescription | string | Opzionale. Descrizione dello studio di imaging richiesto. |
| AccessionNumber | string | Opzionale. Accession Number (Numero di Accesso) univoco per l'ordine, se applicabile. |
| PatientComplaints | string | Opzionale. Testo che descrive i disturbi o sintomi del paziente. |
| OrderScheduledDatetime | string (YYYY-MM-DD HH:MM) | Opzionale. La data e l'ora di inizio programmate per la procedura. |
| RequestedProcedureId | string | Opzionale. Identificatore per la procedura richiesta. |
| RequestedProcedureDescription | string | Opzionale. Descrizione della procedura richiesta. |
| RequestingPhysician | string | Opzionale. Nome del medico richiedente lo studio. |
| ReferringPhysiciansName | string | Opzionale. Nome del medico inviante, se diverso da quello richiedente. |
| ScheduledEquipmentUuid | string | Opzionale. UUID dell'apparecchiatura di imaging da utilizzare per la procedura programmata. |
Ottieni Proprietà dell'Ordine Paziente
Questa funzione recupera l'insieme completo delle proprietà di un singolo e specifico ordine paziente.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| PatientOrderInstitutionUuid | string | Obbligatorio. L'UUID dell'istituto a cui appartiene l'ordine. |
| PatientOrderUuid | string | Obbligatorio. L'UUID dello specifico ordine paziente da recuperare. |
Ricerca di Ordini Paziente
Questa funzione recupera un elenco di ordini paziente in base a una combinazione di filtri di ricerca, come il nome del paziente, l'ID, la modalità e le date di studio o di nascita. Consente funzionalità di ricerca avanzate per gli istituti che gestiscono ordini multipli.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| InstitutionUuidList | List |
Elenco di UUID che identificano gli istituti in cui cercare gli ordini paziente. |
| PatientName | string | Opzionale. Filtra in base al nome completo del paziente. |
| PatientId | string | Opzionale. Filtra in base all'identificatore univoco del paziente. |
| OtherPatientId | string | Opzionale. Identificatore secondario per il paziente, se disponibile. |
| AccessionNumber | string | Opzionale. Filtra in base al numero di accesso assegnato allo studio. |
| ModalityList | List |
Elenco di modalità (es. TC, RM, US) per filtrare i risultati della ricerca. |
| StudyDateFrom | string (YYYY-MM-DD) | Opzionale. Data di inizio dell'intervallo di date dello studio per filtrare i risultati. |
| StudyDateTo | string (YYYY-MM-DD) | Opzionale. Data di fine dell'intervallo di date dello studio per filtrare i risultati. |
| PatientBirthdateFrom | string (YYYY-MM-DD) | Opzionale. Data di inizio dell'intervallo di date di nascita del paziente per filtrare in base all'età. |
| PatientBirthdateTo | string (YYYY-MM-DD) | Opzionale. Data di fine dell'intervallo di date di nascita del paziente per filtrare in base all'età. |
Elimina Ordine Paziente
Questa funzione elimina in modo permanente un ordine paziente dal sistema. Richiede sia l'UUID dell'istituto che l'UUID dello specifico ordine paziente per garantire precisione e impedire eliminazioni accidentali.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| PatientOrderInstitutionUuid | string | Obbligatorio. UUID dell'istituto a cui appartiene l'ordine paziente. Garantisce l'utilizzo del contesto corretto per l'eliminazione. |
| PatientOrderUuid | string | Obbligatorio. UUID dello specifico ordine paziente da eliminare. Questo identifica in modo univoco l'ordine nel sistema. |
Ottieni Contenuto Tag DICOMOttieni Contenuto Tag DICOM
Questa funzione recupera i valori di specifici tag DICOM dalle immagini associate a un ordine paziente.
| Parametri Obbligatori | Tipo di Dato | Descrizione |
| UserName | string | Il nome utente (indirizzo email) per l'account PostDICOM. (dall'inizializzazione) |
| Password | string | La password associata all'account PostDICOM. (dall'inizializzazione) |
| WebAddress | string | L'URL di base dell'API. (dall'inizializzazione) |
| PatientOrderInstitutionUuid | string | Obbligatorio. L'UUID dell'istituto in cui risiede l'ordine. |
| PatientOrderUuid | string | Obbligatorio. L'UUID dell'ordine contenente le immagini. |
| PatientSeriesUuid | string | Opzionale. Se fornito, i tag verranno letti solo da questa serie specifica. |
| DicomTagIdList | List |
Opzionale. Un elenco di ID di Tag DICOM da recuperare. |