Especificação Técnica ACSS

(1)

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

(2)

Í

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

(3)

1

I

NTRODUÇÃ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.

(4)

2

Â

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.

(5)

3

R

EQUISITOS DE

U

TILIZAÇÃO DO

S

ERVIÇ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.

(6)

4

R

ETORNO DO

S

ERVIÇ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.

(7)

5

F

LUXO DE

E

XECUÇÃO

Abaixo representa-se em alto nível o fluxo de execução deste serviço.

Prescrição MCDT Validar Entidade # Registos Pesquisar Utente = 1 Prescrição válida? Não Registar Prescrição MCDT Sim Início Fim Sim Entidade autorizada? <> 1 Erro Aviso Sucesso Fim Fim Não Legenda: Regista Prescrição Pendente

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.

(8)

6

M

ODELO DE

C

OMUNICAÇÃ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.

(9)

7

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...);

(10)

8

 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

(11)

9 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.

(12)

10

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.

(13)

11 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;

(14)

12

C

ARACTERÍSTICAS

,

R

EGRAS E

V

ALIDAÇÕ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

(15)

13

E

STRUTURAS DE

D

ADOS

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

RequisicoesMCDT rreq:ListaRequisicaoMCDTBody Lista de Requisições

ListaRequisicaoMCDTBody

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

MessageHeader int:MessageHeaderType Cabeçalho do pedido; a responsabilidade

de preenchimento é da ACSS MessageBody rreq:RegistoRequisicaoMCDTMessageBodyOutpu

t

Corpo da Resposta

RegistoRequisicaoMCDTMessageBodyOutput

ListaResultadosOperacao rreq:ListaRequisicaoMCDTBodyOutput Lista com os resultados da inserção das Requisições de MCDT

(16)

14

ListaRequisicaoMCDTBodyOutput

ResultadoOperacao rreq:RequisicaoMCDTBodyOutput Resultado do Registo de uma Requisição de MCDT

RequisicaoMCDTBodyOutput

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

Code Texto Código representativo do estado da

invocação (Sucesso, Erro, etc.)

Description Texto Descrição do código de estado da

(17)

15

T

ABELAS DE

R

EFERÊNCIA DE

M

ENSAGENS DE

R

ETORNO

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 Acção

Sucesso Requisição registada/anulada com sucesso Erro Solicita o reenvio da requisição

Aviso 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

entidade

Aviso

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

(18)

16

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:

 MessageHeader: RequestKey

Reenvio de Mensagens

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.

(19)

17

I

NFORMAÇÃO

O

PERACIONAL

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

(20)

18

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.