Especificação Técnica ACSS

Especificação Técnica ACSS ET.ACSS.011-2011 Serviço de Registo de Requisições de MCDT Interface para recepção de requisições electrónicas ICS DESCRITORES Sistema de recepção de requisições de meios complementares de diagnóstico, actos terapêuticos e consultas de especialidade, requisição, webservices, local de prescrição Documentos de Referência Data de Aprovação pela ACSS 2011-07-29 ELABORAÇÃO DCSTIC EDIÇÃO Julho de 2011 PREÇO ACSS reprodução proibida

ET.ACSS.011-2011 ÍNDICE Serviço de Registo de Requisições de MCDT...1 Interface para recepção de requisições electrónicas...1 Introdução...1 Âmbito...2 Requisitos de Utilização do Serviço...3 Retorno do Serviço...4 Fluxo de Execução...5 Modelo de Comunicação...6 Referências a Outros Documentos...6 Serviços Implementados...6 Registo Requisição MCDT... 6 Parâmetros de Entrada...6 Message Header... 7 Message Body... 8 Cabeçalho... 9 Utente... 9 MCDTAnulado... 9 Lista Items Requisição... 9 ItemRequisição... 10 Parâmetros de Saída...10 Características, Regras e Validações do serviço...12 Estruturas de Dados...13 RegistoRequisicaoMCDTProcessRequestType... 13 RegistoRequisicaoMCDTMessageBody... 13 ListaRequisicaoMCDTBody... 13 RegistoRequisicaoMCDTProcessResponse... 13 RegistoRequisicaoMCDTMessageBodyOutput... 13 ListaRequisicaoMCDTBodyOutput... 14 RequisicaoMCDTBodyOutput... 14 GenericCodeResult... 14 Tabelas de Referência de Mensagens de Retorno...15 Reenvio de Mensagens... 16 Informação Operacional...17 Endpoints...17 RegistoRequisicaoMCDTs... 17 Testes... 17 Produção... 17 WSDL...17 RegistoRequisicaoMCDTs... 17 Testes... 17 Produção... 17 Timeout...18 Segurança...18

INTRODUÇÃO Este documento serve o propósito de documentar tecnicamente o Serviço de Registo de Requisições de MCDT na Base de Dados Nacional de Prescrições (BDNP) disponibilizados pela Plataforma de Integração da ACSS. Todos os Serviços disponibilizados pela Plataforma de Integração da ACSS estão expostos na Gateway de Serviços da Plataforma de Integração da ACSS e o acesso aos mesmos é fornecido no âmbito do processo de certificação da responsabilidade da Unidade de Certificação e Normalização. A Documentação de Referência contempla um capítulo de especificação funcional - onde é disponibilizada informação mais detalhada no âmbito dos dados expostos pelo serviço, bem como na descrição do processo de negócio, e um capítulo de especificação técnica. Sempre que um Serviço disponibilizado pela Plataforma de Integração da ACSS utilizar Estruturas de Dados do Modelo de Dados Canónico da Plataforma de Integração da ACSS será feita referência a documentação de referência do Modelo de Dados Canónico, onde é possível analisar mais detalhadamente a definição das mesmas. 1

ÂMBITO O Serviço de Registo de Requisições de MCDT possibilita o registo de requisições na Base de Dados Nacional de Prescrições. Estas requisições deverão ter origem numa qualquer aplicação informática que disponibilize a funcionalidade de prescrição eletrónica de MCDT certificada pela ACSS. Concebido com o intuito de responder às necessidades de diversas entidades que operam na área da saúde, no âmbito da prescrição eletrónica de MCDT, este serviço visa promover a interoperabilidade entre as mesmas e a BDNP, recorrendo a standards tecnológicos com elevada disseminação no mercado. 2

REQUISITOS DE UTILIZAÇÃO DO SERVIÇO As aplicações que disponibilizem a funcionalidade de prescrição eletrónica de MCDT deverão utilizar este serviço, de preferência online e no ato de prescrição de MCDT, garantindo o envio da informação das requisições para a BDNP. Este requisito não é ainda de carácter obrigatório, no entanto sê-lo-á num futuro próximo, no âmbito do processo de desmaterialização da Prescrição de MCDT. O Software deverá estar preparado para garantir o reenvio das requisições que, por motivos técnicos ou por erro, não tenham tido sucesso no seu envio. Deverá ter a capacidade identificar as requisições que não foram enviadas com sucesso, e repetir o seu envio até ser ultrapassado o problema técnico (Problemas de comunicações, erro técnico devolvido pelo serviço, etc.) As requisições que sejam recepcionadas na BDNP mas em que existe uma mensagem de aviso, deverão ser analisadas, pelos fornecedores, no sentido de ser realizado um diagnóstico e se apurar se estamos perante uma não conformidade da prescrição. 3

RETORNO DO SERVIÇO Nas situações em que o serviço devolve um erro, ou em situações de indisponibilidade do serviço, torna-se necessário o reenvio da requisição. O Software deverá assegurar o seu reenvio até obter uma resposta com sucesso. Nas situações em que existe sucesso na receção da requisição mas seja retornado um aviso, deve ser analisada a causa que originou o aviso e deve ser corrigido o problema de forma a evitar avisos em situações futuras: 1. Avisos relacionados com o Profissional devem ser reportados à ACSS. Este aviso identifica que o profissional não é conhecido no sistema Central pelo que deverá ser notificado. 2. Avisos relacionados com o Local de Prescrição devem ser reportados à ACSS. Este aviso identifica que o local de prescrição não é conhecido no sistema Central pelo que deverá ser notificado. 3. Avisos relacionados com o utente: deve o Software verificar se a informação do utente está de acordo com a informação disponibilizada pelo RNU. Na situação de o subsistema identificado na prescrição ser o SNS (a comparticipação é assegurada SNS), o Software deverá assegurar que as prescrições emitidas são coerentes com a informação residente no Registo Nacional de Utentes (Nº de utente, nome, data de nascimento). 4. Avisos relacionados com o MCDT; deve a entidade verificar se a tabela de referência de MCDT Convencionados se encontra atualizada. 4

FLUXO DE EXECUÇÃO Abaixo representa-se em alto nível o fluxo de execução deste serviço. Prescrição MCDT Início Validar Entidade Entidade autorizada? Não Sim Fim Pesquisar Utente # Registos <> 1 = 1 Prescrição válida? Não Regista Prescrição Pendente Sim Legenda: Registar Prescrição MCDT Erro Aviso Fim Fim Sucesso Figura 1 Registo de Requisição de MCDT O serviço de Registo de Requisições tem 3 tipos de respostas possíveis: Sucesso, Aviso e Erro. Para mais informações sobre estas mensagens e ações a tomar relativamente a cada uma, consulte as Tabelas de Referência de Mensagens de Retorno, identificadas na Especificação Técnica deste documento. 5

MODELO DE COMUNICAÇÃO Referências a Outros Documentos De forma a respeitar as melhores práticas implementadas pela Plataforma de Integração da ACSS são reutilizadas estruturas de dados existentes na mesma. É exemplo disso o elemento do tipo RequisicaoType que é parte integrante da Estrutura de MCDT do Modelo de Dados Canónico da Plataforma de Integração da ACSS. Os elementos constantes das tabelas abaixo têm um cariz funcional e podem não representar a totalidade dos dados definidos nas mensagens expostas pelo serviço. Como complemento desta informação consulte, neste documento, o capítulo Especificação Técnica. Serviços Implementados Registo Requisição MCDT Este web service fornece as seguintes funcionalidades: Registo de uma Requisição de MCDT Anulação de uma Requisição de MCDT Parâmetros de Entrada Os parâmetros de entrada do serviço de Registo de Requisição de MCDT estão divididos em duas secções como se pode ver na imagem em baixo: Fig. 1 Estrutura dos dados de Entrada A secção MessageHeader engloba os dados técnicos do pedido efectuado (por ex: identificar a identidade que faz o pedido). A sessão MessageBody contém todos os dados relativos à Requisição emitida pela entidade externa que invocou o serviço. 6

Message Header Na imagem seguinte, representa-se a constituição do Message Header. Fig. 2 Estrutura MessageHeader Como se pode visualizar, esta parte do pedido de Registo de Requisição, é construída por 6 secções: From - entidades externas que acedem ao pedido; To - entidade de destino do pedido. Type - tipo de mensagem enviada (síncrona ou assíncrona); Operation - tipo de operação a realizar (Inserir, Anular, etc...); SentOn Data do Envio da mensagem; 7

ActivateOn Data de Activação da mensagem. Message Body O primeiro aspecto que se deve salientar no Message Body é que este permite a recepção de várias Requisições em simultâneo. Como se pode verificar na imagem seguinte, o elemento MessageBody é constituído pelo elemento Requisições MCDT que é simplesmente uma lista de Requisições de MCDT. Fig. 3 RegistoRequisicaoMCDT Body É no elemento RequisicaoMCDT que é definida cada Requisição a ser inserida. Para a inserção ser efectuada com sucesso existem vários elementos que obrigatoriamente têm que ser enviados. Fig. 4 Estrutura RequisicaoMCDT De seguida serão especificados os elementos, de maior relevância, deste segmento. 8

Cabeçalho Neste segmento da mensagem deverá ser preenchida a informação relativa a: Número da Requisição Emitida; Número de Vias da Requisição; Local de Emissão da Requisição; Identificação do Profissional que emite a requisição; Informação clínica fornecida na criação da requisição; Data de Emissão da Requisição; Informação da Entidade responsável pelo utente, caso aplicável; Indicação se o exame é realizado no domicilio; Indicação se o exame é urgente; Indicação se o exame é isento de taxa; Indicação se o exame é para ser realizado numa instituição externa. Utente Para a criação duma requisição é necessária a associação a um Utente. Para localizar o Utente correcto é obrigatório o preenchimento de 1 dos 2 grupos seguintes: 1. Envio do Numero do Serviço Nacional de Saúde do Utente (recomendado); 2. Envio do Nome, Data de Nascimento, Sexo, Nacionalidade e Freguesia de Naturalidade do Utente (quando aplicável); MCDTAnulado Este campo específica se estamos a tratar uma requisição anulada ou não. Este campo composto, informará se é uma anulação ou não (S/N), a data, profissional e local em que a mesma foi anulada. Deste modo o serviço terá de permitir, para além da criação de requisições, a anulação de requisições previamente criadas. Para distinção entre uma inserção e uma anulação para além do campo Operation do MessageHeader especificar o código Anular, o campo MCDTAnulado deverá conter informação relativa a essa anulação, nomeadamente: Código de Anulação; Motivo de Anulação; Data de Anulação; Lista Items Requisição Neste campo será colocada a informação relativa aos exames prescritos na Requisição de MCDT a ser inserida. Este campo é composto por elementos do tipo ItemRequisição, elemento este que especifica cada um dos exames prescritos. 9

ItemRequisição Este campo, tal como referido anteriormente, especifica a informação relativa a um determinado exame a ser executado no âmbito da requisição. A sua estrutura pode ser analisada na imagem seguinte. Para melhor análise da sua estrutura consultar o documento Estrutura de MCDT do Modelo de Dados Canónico da Plataforma de Integração da ACSS. Fig. 5 - Estrutura ItemRequisicao No âmbito destes serviços poderão ser ignorados os seguintes campos deste elemento: ExameCronico; Parâmetros de Saída A estrutura dos dados de retorno é em tudo semelhante à estrutura dos dados de entrada. Existe apenas uma pequena diferença que é importante referir de forma a se puder interpretar os dados de resposta. Tal como nos dados de entrada, a estrutura de resposta está dividida em duas secções 10

Fig. 6 - Estrutura de Retorno do Serviço O MessageHeader é igual ao mesmo campo nos dados de entrada. É no campo MessageBody que existe a pequena diferença que irá ser de seguida referida. O MessageBody da estrutura de resposta, tal como a estrutura de entrada, é constituída por uma lista de objectos. Fig. 7 - Estrutura MessageBody de saida Tal como na estrutura de entrada o pedido pode conter diversas requisições. Na resposta também é feita a distinção entre as diferentes requisições, ou seja o processamento é individual e é criada uma resposta para cada requisição. A estrutura ResultadoOperacao é constituída por 2 componentes, tal como se pode verificar na imagem seguinte: Fig. 8 - Estrutura ResultadoOperacao No campo GenericCodeResult virá a informação relativa ao (in)sucesso da operação enquanto que a estrutura RequisiçãoMCDT é igual à descrita anteriormente como elemento de entrada. No entanto para resposta apenas deverá ser tomado em consideração os seguintes campos da mensagem: MessageHeader; GenericCodeResult; NumeroRequisicao Presente no Cabecalho da RequisicaoMCDT. 11

CARACTERÍSTICAS, REGRAS E VALIDAÇÕES DO SERVIÇO 1. A autenticação e autorização da entidade são validadas através do cabeçalho WS-Security 2. O serviço deve ser invocado por requisição de MCDT. 3. O serviço permite inserir uma requisição de MCDT ou anular uma requisição já existente no sistema. 4. O número de requisição (Numero) é de preenchimento obrigatório. 5. A data da requisição (Data) é de preenchimento obrigatório. 6. Para registar uma requisição é necessário identificar o utente a quem foi prescrita essa mesma requisição. Seguem-se os dados mínimos que devem ser enviados para identificar o utente: a. Número do utente do Serviço Nacional de Saúde (NumeroSNS), quando aplicável; b. Nome do Utente (NomeCompleto); c. Data de Nascimento (DataNascimento). d. Sexo; e. País da nacionalidade, de acordo com a norma ISO 3166-1, alpha 2 Nota 1: Podem ser enviados mais dados de identificação do utente Nota 2: O número do utente é obrigatório se a entidade financeira responsável for o SNS ou o CNPRP; Nota 3: O número de beneficiário é de preenchimento obrigatório para qualquer utente, excepto nas seguintes situações: a) O utente é beneficiário apenas do SNS; b) O utente é cidadão estrangeiro e não possui número de utente, nem cartão de EFR nacional, nem documento de direito. Neste caso a EFR deverá ser 999998 (Independente). c) Na situação da EFR ser o próprio utente ou uma Entidade Terceira. Neste caso a EFR deverá ser 999998 (Independente). Nota 4: O nº de utente, caso esteja preenchido, é preferencial relativamente aos restantes dados, para efeitos de validação. Podem ser enviados mais dados do utente; estes são apenas os considerados mínimos obrigatórios. 7. O elemento Profissional é de preenchimento obrigatório. 8. O elemento Grupo Funcional da estrutura Profissional é de preenchimento obrigatório. Os valores possíveis para este elemento são: a. Médicos 05 b. Dentistas 06 c. Odontologistas 07 9. O elemento LocalPrescricao é de preenchimento obrigatório. 10. Uma requisição, cuja EFR seja o SNS, deve obedecer às seguintes regras: a. Só pode ter no máximo 6 MCDT b. Os MCDT têm que pertencer à tabela de convencionados publicada no site da ACSS e em vigor à data da requisição 12

ESTRUTURAS DE DADOS RegistoRequisicaoMCDTProcessRequestType Elemento Tipo Descrição MessageHeader int:messageheadertype Cabeçalho do pedido; a responsabilidade de preenchimento é da ACSS MessageBody rreq:registorequisicaomcdtmessagebody Corpo do Pedido RegistoRequisicaoMCDTMessageBody Elemento Tipo Descrição RequisicoesMCDT rreq:listarequisicaomcdtbody Lista de Requisições ListaRequisicaoMCDTBody Elemento Tipo Descrição RequisicaoMCDT emcdt:requisicaotype Requisição de MCDT, de acordo com a especificação do Modelo de Dados Canónico da Plataforma de Integração da ACSS. RegistoRequisicaoMCDTProcessResponse Elemento Tipo Descrição MessageHeader int:messageheadertype Cabeçalho do pedido; a responsabilidade de preenchimento é da ACSS MessageBody rreq:registorequisicaomcdtmessagebodyoutpu Corpo da Resposta t RegistoRequisicaoMCDTMessageBodyOutput Elemento Tipo Descrição ListaResultadosOperacao rreq:listarequisicaomcdtbodyoutput Lista com os resultados da inserção das Requisições de MCDT 13

ListaRequisicaoMCDTBodyOutput Elemento Tipo Descrição ResultadoOperacao rreq:requisicaomcdtbodyoutput Resultado do Registo de uma Requisição de MCDT RequisicaoMCDTBodyOutput Elemento Tipo Descrição GenericCodeResult int:genericcodetype Elemento representativo do estado da invocação (Sucesso, Erro, etc.) RequisicaoMCDT emcdt:requisicaotype Requisição, de acordo com a especificação do Modelo de Dados Canónico da Plataforma de Integração da ACSS. GenericCodeResult Elemento Tipo Descrição Code Texto Código representativo do estado da invocação (Sucesso, Erro, etc.) Description Texto Descrição do código de estado da invocação 14

TABELAS DE REFERÊNCIA DE MENSAGENS DE RETORNO O serviço de Registo de MCDT tem 3 grandes tipos de mensagens de retorno. Identificam-se de seguida os estados possíveis para as mensagens retornadas pelo serviço: Estado Sucesso Erro Aviso Acção Requisição registada/anulada com sucesso Solicita o reenvio da requisição Aceita a requisição e devolve código de código/informação incorrecta ou insuficiente Juntamente com o código de Sucesso é enviado também na mensagem o número da requisição inserida ou anulada. Valores possíveis para a mensagem: Código Descrição Tipo 201101000 Requisição Inserida com Sucesso Sucesso 201101001 Requisição anulada com sucesso Sucesso 201104001 Erro ao pesquisar Utente Aviso 201104002 Erro ao Pesquisar o Profissional Aviso 201104003 Erro ao Pesquisar o Local de Emissão Aviso 201104004 Erro ao obter Entidade Responsável Aviso 201104005 Erro ao obter Modulo de Consulta Aviso 201104006 Erro ao obter MCDT Aviso 201104007 Requisição contem MCDT(s) com Área MCDT (Lado) Inválido Aviso 201104008 Erro ao inserir Requisição Aviso 201104009 Erro ao inserir itens de Requisição Aviso 201104010 Número de Requisição já existe Aviso 201104011 Tipo de Cartão de Entidade Inválido Aviso 201104012 Requisição a anular não existe Aviso 201104013 Dados insuficientes para cartão CESD Aviso 201104014 Número de Beneficiário obrigatório para esta Aviso entidade 201104015 Requisição contém MCDT(s) inválido(s) Aviso 201104016 Requisição contem MCDT(s) com Produto Inválido Aviso 201104017 Requisição não respeita normas definidas Aviso 201104018 A Requisição tem demasiados MCDTs Aviso 201104019 Uma requisição apenas pode ter MCDTs de uma Área Aviso 201104020 A Requisição Possui exames que não podem Aviso 15

Código Descrição Tipo estar na mesma requisição 201105001 Erro ao pesquisar o Num. Requisição Erro 201105002 Erro no Processamento. Contactar ACSS Erro 201105003 Numero de Requisição não Preenchido Erro Juntamente com o código de erro, será enviado à entidade um número único (GUID) que deverá ser guardado para futura identificação desse mesmo pedido. Esse identificador é enviado na resposta, na seguinte localização: Reenvio de Mensagens MessageHeader: RequestKey O reenvio da mensagem será apenas necessário em duas situações: a. Na eventualidade de um erro, o que originará uma mensagem com código de erro (Ver tabela de valores possíveis), b. Caso o serviço não responda, ou responda com uma mensagem inválida. Ambas as situações requerem contacto com a ACSS para que se possa averiguar e resolver o problema existente, possibilitando assim o reenvio da requisição a ser processada. Sendo retornado um aviso (ver tabela valores de possíveis) está garantido o armazenamento de todas as mensagens enviadas, pelo que não é necessário o seu reenvio. Caso seja devolvido um aviso, a ACSS deverá ser igualmente contactada de forma a que seja corrigido o erro que originou o aviso. 16

INFORMAÇÃO OPERACIONAL Endpoints Todos os serviços registados na Plataforma de Integração da ACSS são expostos na Gateway de Serviços da mesma. Abaixo estão enumerados os endpoints deste serviço em ambiente de testes e produção. RegistoRequisicaoMCDTs Testes http://wsgw-teste.min-saude.pt:8000/gateway/services/registorequisicaomcdts Produção A DEFINIR WSDL Todos os serviços registados na Plataforma de Integração da ACSS são expostos na Gateway de Serviços da mesma. Abaixo estão enumeradas as localizações dos WSDL s deste serviço em ambiente de testes e produção. RegistoRequisicaoMCDTs Testes http://wsgw-teste.min-saude.pt:8000/gateway/services/registorequisicaomcdts?wsdl Produção A DEFINIR 17

Timeout O serviço estará configurado para fechar a ligação, retornando timeout ao fim de 30 segundos de tempo de invocação. Quando este problema surge é necessário o reenvio da mensagem. A autorização de reenvio está dependente de contacto prévio com a ACSS, por parte da entidade emissora, para esclarecimento da origem do timeout. Segurança A todas as entidades deverá ser fornecido credenciais de acesso. Estas credenciais de acesso (constituídas por um login e uma password) deverão ser incluídas no cabeçalho WS-Security (http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd) do serviço, de forma que seja possível efectuar a autenticação e autorização da entidade invocadora contra o servidor LDAP da ACSS. 18