Documentazione Servizio DICOMweb | PostDICOM

Prerequisites Introduzione e Informazioni Generali

Questo documento fornisce una guida tecnica completa per le funzioni dell'API DICOMweb con metodi di esempio utilizzati attraverso un'applicazione di esempio in C#. Include spiegazioni dettagliate di tutte le funzioni disponibili, coprendo sia i servizi standard DICOMweb (come QIDO-RS, WADO-RS e STOW-RS) che gli endpoint API DICOMweb personalizzati sviluppati da PostDICOM. Queste funzioni sono progettate per essere utilizzate nelle chiamate lato server.

Per utilizzare i servizi DICOMweb di PostDICOM, deve prima avere questa funzione abilitata per il Suo account e possedere credenziali utente valide. Se l'accesso DICOMweb non è ancora attivato per il Suo account e desidera integrare la Sua applicazione con PostDICOM, ci contatti per richiedere l'attivazione.

Nome Utente: Questa è la Sua credenziale di accesso principale, solitamente il Suo indirizzo email. È univoca per il Suo account e utilizzata come nome utente nell'Autenticazione Base.

Password: Questa è la password associata al Suo account PostDICOM. Viene utilizzata insieme al Suo nome utente durante l'Autenticazione Base. Per una sicurezza ottimale, consigliamo vivamente di scegliere una password complessa. La preghiamo di disporre dei meccanismi di sicurezza necessari sulla Sua chiamata lato server affinché questo nome utente e questa password siano protetti.

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

Servizi Standard DICOMweb

Archiviazione Istanze DICOM (STOW-RS)

UploadDicomImagesInAFolder(UserName, Password, WebAddress, FileNamesList)

Questa funzione orchestra il caricamento di tutti i file .dcm da una cartella locale specifica al server DICOMweb. Identifica prima tutti i file rilevanti, quindi utilizza metodi ausiliari per costruire e inviare una richiesta POST multipart/related autenticata per ogni file, aderendo allo standard STOW-RS.

Parametri Richiesti	Tipo di Dati	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.

Query per Oggetti DICOM (QIDO-RS)

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

Questa funzione esegue una query per 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 Richiesti	Tipo di Dati	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 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 immagine all'interno di una serie specifica.

Recupero 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 Richiesti	Tipo di Dati	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 globale per uno studio DICOM. Utilizzato per recuperare tutte le serie e le istanze associate a quello studio.
SeriesInstanceUID	string	Opzionale. Un identificatore univoco globale per una serie all'interno di uno studio DICOM. Utilizzato per recuperare tutte le immagini sotto quella serie.
SOPInstanceUID	string	Opzionale. Un identificatore univoco per una singola istanza immagine DICOM. Utilizzato per recuperare un'immagine specifica utilizzando WADO-RS.

Gestione 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 Richiesti	Tipo di Dati	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, ognuna 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 sarà 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.

Condividi Ordine Paziente con URL

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

Questa funzione genera un URL condivisibile per ordini paziente selezionati con opzioni di controllo accessi aggiuntive come permesso di download e protezione password.

Parametri Richiesti	Tipo di Dati	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.

Gestione Cartelle e 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 Richiesti	Tipo di Dati	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 cartelle esistenti in base ai criteri di ricerca. Può facoltativamente includere l'elenco degli ordini paziente all'interno di ogni cartella trovata.

Parametri Richiesti	Tipo di Dati	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. Un UUID cartella per limitare la ricerca ai suoi figli.
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.

Condividi Cartella con URL

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

Questa funzione genera un URL sicuro e condivisibile per un'intera cartella e il suo contenuto. Consente un controllo completo degli accessi impostando un titolo personalizzato, una descrizione, una password, una data di scadenza e specificando se il contenuto può essere scaricato dal destinatario.

Parametri Richiesti	Tipo di Dati	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 lasciata vuota, il link sarà accessibile pubblicamente.
ShareTitle	string	Opzionale. Un titolo personalizzato per la pagina della cartella condivisa, visibile al destinatario.
ShareDescription	string	Opzionale. Una descrizione visualizzata sulla 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 nella 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. Questo è uno strumento organizzativo; non sposta né copia i dati.

Parametri Richiesti	Tipo di Dati	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 Lavoro e Assegnazione

Assegna Ordine all'Utente

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

Questa funzione è uno strumento fondamentale del flusso di lavoro. Assegna un ordine paziente a un singolo utente, indicando che questo utente è ora responsabile di un compito relativo a quell'ordine (es. refertazione).

Parametri Richiesti	Tipo di Dati	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 azione.
AssignedUserUuid	string	Obbligatorio. L'UUID dell'utente specifico a cui verrà assegnata la responsabilità.

Assegna Ordine al Gruppo Utenti

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

Simile all'assegnazione a un singolo utente, questa funzione assegna un ordine paziente a un intero gruppo, consentendo flussi di lavoro di squadra in cui qualsiasi membro del gruppo può gestire il compito.

Parametri Richiesti	Tipo di Dati	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 utenti a cui assegnare l'ordine.

Ciclo 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 pianificare e gestire studi di imaging all'interno del sistema. I parametri obbligatori devono essere forniti per una creazione riuscita.

Parametri Richiesti	Tipo di Dati	Descrizione
InstitutionUuid	string	Obbligatorio. UUID dell'istituzione in cui viene creato l'ordine paziente.
PatientName	string	Obbligatorio. Nome completo del paziente.
PatientId	string	Obbligatorio. Identificatore univoco del paziente come un ID nazionale o MRN.
PatientBirthdate	string (YYYY-MM-DD)	Obbligatorio. Data di nascita del paziente in formato ISO.
Modality	string	Obbligatorio. Tipo di modalità come CT, MR, US, ecc.
OtherPatientId	string	Opzionale. Un identificatore aggiuntivo per il paziente, se applicabile.
PatientSex	string	Opzionale. Genere del paziente (es. M, F, O).
StudyDescription	string	Opzionale. Descrizione dello studio di imaging ordinato.
AccessionNumber	string	Opzionale. Numero di accesso univoco per l'ordine, se applicabile.
PatientComplaints	string	Opzionale. Testo che descrive i disturbi o i sintomi del paziente.
OrderScheduledDatetime	string (YYYY-MM-DD HH:MM)	Opzionale. La data e l'ora di inizio programmate della procedura.
RequestedProcedureId	string	Opzionale. Identificatore per la procedura richiesta.
RequestedProcedureDescription	string	Opzionale. Descrizione della procedura richiesta.
RequestingPhysician	string	Opzionale. Nome del medico che ha richiesto lo studio.
ReferringPhysiciansName	string	Opzionale. Nome del medico referente, se diverso dal richiedente.
ScheduledEquipmentUuid	string	Opzionale. UUID dell'apparecchiatura di imaging da utilizzare per la procedura programmata.

Ottieni Proprietà Ordine Paziente

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

Questa funzione recupera il set completo di proprietà per un singolo ordine paziente specifico.

Parametri Richiesti	Tipo di Dati	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'istituzione a cui appartiene l'ordine.
PatientOrderUuid	string	Obbligatorio. L'UUID dell'ordine paziente specifico da recuperare.

Cerca Ordini Paziente

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

Questa funzione recupera un elenco di ordini paziente basato su una combinazione di filtri di ricerca come nome paziente, ID, modalità e date dello studio o di nascita. Abilita funzionalità di ricerca avanzata per istituzioni che gestiscono più ordini.

Parametri Richiesti	Tipo di Dati	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 le istituzioni per cercare ordini paziente.
PatientName	string	Opzionale. Filtra per nome completo del paziente.
PatientId	string	Opzionale. Filtra per identificatore univoco del paziente.
OtherPatientId	string	Opzionale. Identificatore secondario per il paziente, se disponibile.
AccessionNumber	string	Opzionale. Filtra per numero di accesso assegnato allo studio.
ModalityList	List	Elenco di modalità (es. CT, MR, 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 i pazienti per età.
PatientBirthdateTo	string (YYYY-MM-DD)	Opzionale. Data di fine dell'intervallo di date di nascita del paziente per filtrare i pazienti per età.

Elimina Ordine Paziente

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

Questa funzione elimina definitivamente un ordine paziente dal sistema. Richiede sia l'UUID dell'istituzione che l'UUID specifico dell'ordine paziente per garantire l'accuratezza e prevenire l'eliminazione accidentale.

Parametri Richiesti	Tipo di Dati	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'istituzione che possiede l'ordine paziente. Assicura che venga utilizzato il contesto corretto per l'eliminazione.
PatientOrderUuid	string	Obbligatorio. UUID dell'ordine paziente specifico da eliminare. Questo identifica univocamente l'ordine nel sistema.

Ottieni Contenuto Tag DICOM

Ottieni Contenuto Tag DICOM

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

Questa funzione recupera i valori di tag DICOM specifici dalle immagini associate a un ordine paziente.

Parametri Richiesti	Tipo di Dati	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'istituzione 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 Tag DICOM da recuperare.