Documentação do Serviço DICOMweb | PostDICOM

Pré-requisitos Introdução e Informações Gerais

Este documento fornece um guia técnico abrangente para as funções da API DICOMweb com exemplos de métodos utilizados através de uma aplicação de exemplo em C#. Inclui explicações detalhadas de todas as funções disponíveis, abrangendo tanto os serviços DICOMweb padrão (como QIDO-RS, WADO-RS e STOW-RS) quanto os endpoints personalizados da API DICOMweb desenvolvidos pela PostDICOM. Estas funções foram concebidas para serem utilizadas em chamadas do lado do servidor.

Para utilizar os serviços DICOMweb da PostDICOM, deve primeiro ter esta funcionalidade ativada na sua conta e possuir credenciais de utilizador válidas. Se o acesso DICOMweb ainda não estiver ativado para a sua conta e desejar integrar a sua aplicação com a PostDICOM, por favor contacte-nos para solicitar a ativação.

Nome de Utilizador: Esta é a sua credencial de login principal, geralmente o seu endereço de e-mail. É única para a sua conta e usada como nome de utilizador na Autenticação Básica.

Palavra-passe: Esta é a palavra-passe associada à sua conta PostDICOM. É utilizada em conjunto com o seu nome de utilizador durante a Autenticação Básica. Para uma segurança ideal, recomendamos vivamente que escolha uma palavra-passe forte. Por favor, tenha os mecanismos de segurança necessários na sua chamada do lado do servidor para que este nome de utilizador e palavra-passe sejam protegidos por si.

Pode gerir a sua palavra-passe e definições de segurança através da página de perfil da sua conta após entrar na sua conta PostDICOM.

Serviços Padrão DICOMweb

Armazenar Instâncias DICOM (STOW-RS)

UploadDicomImagesInAFolder(UserName, Password, WebAddress, FileNamesList)

Esta função orquestra o upload de todos os ficheiros .dcm de uma pasta local especificada para o servidor DICOMweb. Primeiro identifica todos os ficheiros relevantes, depois utiliza métodos auxiliares para construir e enviar um pedido POST multipart/related autenticado para cada ficheiro, aderindo ao padrão STOW-RS.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
DirectoryPath	string	O caminho completo para o diretório local que contém os ficheiros DICOM (.dcm) a serem carregados.

Consultar Objetos DICOM (QIDO-RS)

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

Esta função realiza uma consulta de objetos DICOM utilizando o padrão QIDO-RS, permitindo pesquisas ao nível do Estudo, Série ou Instância. Com base no parâmetro de pesquisa fornecido (como ID do Paciente, UID da Instância do Estudo ou UID da Instância da Série), constrói o URL apropriado e executa um pedido autenticado para recuperar resultados correspondentes do servidor.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
PatientID	string	Opcional. Usado para identificar o paciente e pesquisar estudos relacionados.
StudyInstanceUID	string	Opcional. Usado para pesquisar um estudo específico ou todas as séries dentro desse estudo.
SeriesInstanceUID	string	Opcional. Usado para pesquisar todas as instâncias de imagem dentro de uma série específica.

Recuperar Instâncias DICOM (WADO-RS)

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

Esta função fornece um menu interativo para recuperar objetos DICOM utilizando o padrão WADO-RS. O utilizador seleciona um nível de recuperação (Estudo, Série ou Instância) e fornece o UID correspondente. A função faz então um pedido autenticado e processa a resposta multipart/related, guardando cada parte DICOM como um ficheiro .dcm separado num diretório local recém-criado.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
StudyInstanceUID	string	Opcional. Um identificador globalmente único para um estudo DICOM. Usado para recuperar todas as séries e instâncias associadas a esse estudo.
SeriesInstanceUID	string	Opcional. Um identificador globalmente único para uma série dentro de um estudo DICOM. Usado para recuperar todas as imagens sob essa série.
SOPInstanceUID	string	Opcional. Um identificador único para uma instância de imagem DICOM individual. Usado para recuperar uma imagem específica usando WADO-RS.

Gestão de Partilha

Criar Link de Partilha

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

Esta função gera um link web seguro para partilhar um ou mais pedidos de pacientes com utilizadores externos. O link pode ser protegido por palavra-passe e, opcionalmente, permitir downloads.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe para a conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
PatientOrderInfoList	List	Lista de strings JSON, cada uma contendo uma chave "PatientOrderUuid", identificando os pedidos de pacientes a serem partilhados.
ExpireDate	string (AAAA-MM-DD)	Data de expiração para o link de partilha. Após esta data, o link será desativado.
SharePassword	string	Opcional. Palavra-passe necessária para aceder ao link de partilha. Deixe vazio para acesso público.
Downloadable	bool	Opcional. Determina se os estudos DICOM podem ser descarregados pelo destinatário.

Partilhar Pedido do Paciente com URL

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

Esta função gera um URL partilhável para pedidos de pacientes selecionados com opções adicionais de controlo de acesso, como permissão de download e proteção por palavra-passe.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (e-mail) da conta PostDICOM. (da inicialização)
Password	string	A palavra-passe para a conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
OrderUuidList	List	Lista de UUIDs identificando os pedidos de pacientes a serem partilhados.
ExpireDate	string (AAAA-MM-DD)	Data após a qual o link de partilha se torna inativo.
SharePassword	string	Opcional. Palavra-passe necessária para aceder ao link partilhado.
UserCanDownloadStudies	bool	Opcional. Se definido como verdadeiro (true), o destinatário pode descarregar os estudos.

Gestão de Pastas e Pedidos

Criar Pasta

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

Esta função é utilizada para criar uma nova pasta (um contentor virtual) dentro da conta PostDICOM para ajudar a organizar os pedidos dos pacientes.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
FolderName	string	Obrigatório. O nome visível para a nova pasta.
FolderDescription	string	Opcional. Uma descrição de texto para a pasta.
ParentFolderUuid	string	Opcional. O UUID de uma pasta existente para criar a nova pasta dentro dela.

Pesquisar Pasta

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

Esta função encontra pastas existentes com base em critérios de pesquisa. Pode opcionalmente incluir a lista de pedidos de pacientes dentro de cada pasta encontrada.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
ParentFolderUuid	string	Opcional. Um UUID de pasta para restringir a pesquisa aos seus descendentes.
FolderName	string	Opcional. Um nome completo ou parcial para pesquisar.
GetOrdersInFolder	bool	Opcional. Se `true`, a resposta incluirá uma lista de pedidos de pacientes para cada pasta encontrada.

Partilhar Pasta com URL

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

Esta função gera um URL seguro e partilhável para uma pasta inteira e o seu conteúdo. Permite um controlo de acesso abrangente ao definir um título personalizado, descrição, palavra-passe, data de expiração e especificando se o conteúdo pode ser descarregado pelo destinatário.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
FolderUuid	string	Obrigatório. O identificador único (UUID) da pasta a ser partilhada.
SharePassword	string	Opcional. Uma palavra-passe para proteger o link partilhado. Se deixada vazia, o link será acessível publicamente.
ShareTitle	string	Opcional. Um título personalizado para a página da pasta partilhada, visível para o destinatário.
ShareDescription	string	Opcional. Uma descrição exibida na página da pasta partilhada.
ExpireDate	string (AAAA-MM-DD)	Opcional. A data em que o link de partilha se tornará automaticamente inativo.
UserCanDownloadStudies	bool	Opcional. Se `true`, os destinatários podem descarregar os pedidos de pacientes contidos na pasta.

Adicionar Pedido à Pasta

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

Esta função cria uma associação entre um pedido de paciente existente e uma pasta existente. Esta é uma ferramenta organizacional; não move nem copia dados.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
PatientOrderUuid	string	Obrigatório. O UUID do pedido do paciente a ser colocado numa pasta.
FolderUuidList	List	Obrigatório. Uma lista contendo o UUID da pasta de destino.

Fluxo de Trabalho e Atribuição

Atribuir Pedido ao Utilizador

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

Esta função é uma ferramenta central do fluxo de trabalho. Atribui um pedido de paciente a um utilizador individual, significando que este utilizador é agora responsável por uma tarefa relacionada com esse pedido (por exemplo, relatórios).

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
PatientOrderUuid	string	Obrigatório. O UUID do pedido do paciente que requer ação.
AssignedUserUuid	string	Obrigatório. O UUID do utilizador específico a quem será atribuída a responsabilidade.

Atribuir Pedido ao Grupo de Utilizadores

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

Semelhante à atribuição a um único utilizador, esta função atribui um pedido de paciente a um grupo inteiro, permitindo fluxos de trabalho em equipa onde qualquer membro do grupo pode tratar da tarefa.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
PatientOrderUuid	string	Obrigatório. O UUID do pedido do paciente a ser atribuído ao grupo.
AssignedUserGroupUuid	string	Obrigatório. O UUID do grupo de utilizadores a quem será atribuído o pedido.

Ciclo de Vida do Pedido do Paciente e Recuperação de Dados

Criar Pedido do Paciente

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

Esta função cria um novo pedido de paciente para agendar e gerir estudos de imagem dentro do sistema. Os parâmetros obrigatórios devem ser fornecidos para uma criação bem-sucedida.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
InstitutionUuid	string	Obrigatório. UUID da instituição onde o pedido do paciente está a ser criado.
PatientName	string	Obrigatório. Nome completo do paciente.
PatientId	string	Obrigatório. Identificador único do paciente, como um ID nacional ou MRN.
PatientBirthdate	string (AAAA-MM-DD)	Obrigatório. Data de nascimento do paciente em formato ISO.
Modality	string	Obrigatório. Tipo de modalidade como CT, MR, US, etc.
OtherPatientId	string	Opcional. Um identificador adicional para o paciente, se aplicável.
PatientSex	string	Opcional. Género do paciente (ex: M, F, O).
StudyDescription	string	Opcional. Descrição do estudo de imagem solicitado.
AccessionNumber	string	Opcional. Número de acesso único para o pedido, se aplicável.
PatientComplaints	string	Opcional. Texto descrevendo as queixas ou sintomas do paciente.
OrderScheduledDatetime	string (AAAA-MM-DD HH:MM)	Opcional. A data e hora de início agendadas para o procedimento.
RequestedProcedureId	string	Opcional. Identificador para o procedimento solicitado.
RequestedProcedureDescription	string	Opcional. Descrição do procedimento solicitado.
RequestingPhysician	string	Opcional. Nome do médico que solicitou o estudo.
ReferringPhysiciansName	string	Opcional. Nome do médico que encaminhou, se diferente do solicitante.
ScheduledEquipmentUuid	string	Opcional. UUID do equipamento de imagem a ser utilizado para o procedimento agendado.

Obter Propriedades do Pedido do Paciente

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

Esta função recupera o conjunto completo de propriedades para um pedido de paciente único e específico.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
PatientOrderInstitutionUuid	string	Obrigatório. O UUID da instituição à qual o pedido pertence.
PatientOrderUuid	string	Obrigatório. O UUID do pedido específico do paciente a recuperar.

Pesquisar por Pedidos de Pacientes

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

Esta função recupera uma lista de pedidos de pacientes com base numa combinação de filtros de pesquisa, como nome do paciente, ID, modalidade e datas de estudo ou nascimento. Permite funcionalidades de pesquisa avançada para instituições que gerem múltiplos pedidos.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
InstitutionUuidList	List	Lista de UUIDs identificando as instituições para pesquisar pedidos de pacientes.
PatientName	string	Opcional. Filtrar pelo nome completo do paciente.
PatientId	string	Opcional. Filtrar pelo identificador único do paciente.
OtherPatientId	string	Opcional. Identificador secundário para o paciente, se disponível.
AccessionNumber	string	Opcional. Filtrar pelo número de acesso atribuído ao estudo.
ModalityList	List	Lista de modalidades (ex: CT, MR, US) para filtrar os resultados da pesquisa.
StudyDateFrom	string (AAAA-MM-DD)	Opcional. Data de início do intervalo de datas do estudo para filtrar resultados.
StudyDateTo	string (AAAA-MM-DD)	Opcional. Data de fim do intervalo de datas do estudo para filtrar resultados.
PatientBirthdateFrom	string (AAAA-MM-DD)	Opcional. Data de início do intervalo de datas de nascimento para filtrar pacientes por idade.
PatientBirthdateTo	string (AAAA-MM-DD)	Opcional. Data de fim do intervalo de datas de nascimento para filtrar pacientes por idade.

Apagar Pedido do Paciente

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

Esta função apaga permanentemente um pedido de paciente do sistema. Requer tanto o UUID da instituição quanto o UUID específico do pedido do paciente para garantir a precisão e evitar apagamentos acidentais.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
PatientOrderInstitutionUuid	string	Obrigatório. UUID da instituição proprietária do pedido do paciente. Garante que o contexto correto é utilizado para o apagamento.
PatientOrderUuid	string	Obrigatório. UUID do pedido específico do paciente a ser apagado. Isto identifica unicamente o pedido no sistema.

Obter Conteúdo da Tag Dicom

Obter Conteúdo da Tag DICOM

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

Esta função recupera os valores de tags DICOM específicas das imagens associadas a um pedido de paciente.

Parâmetros Obrigatórios	Tipo de Dados	Descrição
UserName	string	O nome de utilizador (endereço de e-mail) para a conta PostDICOM. (da inicialização)
Password	string	A palavra-passe associada à conta PostDICOM. (da inicialização)
WebAddress	string	O URL base da API. (da inicialização)
PatientOrderInstitutionUuid	string	Obrigatório. O UUID da instituição onde o pedido reside.
PatientOrderUuid	string	Obrigatório. O UUID do pedido que contém as imagens.
PatientSeriesUuid	string	Opcional. Se fornecido, as tags serão lidas apenas desta série específica.
DicomTagIdList	List	Opcional. Uma lista de IDs de Tag DICOM a recuperar.