Documentazione DICOMweb

PrerequisitiIntroduzione 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


DICOMwebServizi Standard DICOMweb

Archiviazione di Istanze DICOM (STOW-RS)

UploadDicomImagesInAFolder(UserName, Password, WebAddress, FileNamesList)

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)

QidoSearch(UserName, Password, WebAddress, PatientID, StudyInstanceUID, SeriesInstanceUID)

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)

RetrieveImagesUsingWadoRs(UserName, Password, WebAddress, StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID)

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.

CondividiGestione della Condivisione

Crea Link di Condivisione

CreateShareLink(UserName, Password, WebAddress, PatientOrderInfoList, ExpireDate, SharePassword, Downloadable)

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

SharePatientOrderWithUrl(UserName, Password, WebAddress, OrderUuidList, ExpireDate, SharePassword, UserCanDownloadStudies)

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.

CartellaGestione delle Cartelle e degli Ordini

Crea Cartella

CreateFolder(UserName, Password, WebAddress, FolderName, FolderDescription, ParentFolderUuid)

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

SearchFolder(UserName, Password, WebAddress, ParentFolderUuid, FolderName, GetOrdersInFolder)

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

ShareFolderWithUrl(UserName, Password, WebAddress, FolderUuid, SharePassword, ShareTitle, ShareDescription, ExpireDate, UserCanDownloadStudies)

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

AddOrderToFolder(UserName, Password, WebAddress, PatientOrderUuid, FolderUuidList)

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.

Flusso di LavoroFlusso di Lavoro e Assegnazione

Assegna Ordine all'Utente

AssignOrderToUser(UserName, Password, WebAddress, PatientOrderUuid, AssignedUserUuid)

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

AssignOrderToUserGroup(UserName, Password, WebAddress, PatientOrderUuid, AssignedUserGroupUuid)

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.

Ordine PazienteCiclo di Vita dell'Ordine Paziente e Recupero Dati

Crea Ordine Paziente

CreatePatientOrder(UserName, Password, WebAddress, InstitutionUuid, PatientName, PatientId, OtherPatientId, PatientSex, PatientBirthdate, Modality, StudyDescription, AccessionNumber, PatientComplaints, OrderScheduledDatetime, RequestedProcedureId, RequestedProcedureDescription, RequestingPhysician, ReferringPhysiciansName, ScheduledEquipmentUuid)

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

GetPatientOrderProperties(UserName, Password, WebAddress, PatientOrderInstitutionUuid, PatientOrderUuid)

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

GetPatientOrderList(UserName, Password, WebAddress, InstitutionUuidList, PatientName, PatientId, OtherPatientId, AccessionNumber, ModalityList, StudyDateFrom, StudyDateTo, PatientBirthdateFrom, PatientBirthdateTo)

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

DeletePatientOrder(UserName, Password, WebAddress, PatientOrderInstitutionUuid, PatientOrderUuid)

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.

Tag DICOMOttieni Contenuto Tag DICOM

Ottieni Contenuto Tag DICOM

GetDicomTagContent(UserName, Password, WebAddress, PatientOrderInstitutionUuid, PatientOrderUuid, PatientSeriesUuid, DicomTagIdList)

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.