Envio de requisições/solicitações e cancelamento de coletas

Atenção: Esse capítulo é uma transcrição do arquivo original enviado pela empresa responsável pelo Sistema de Gestão Pública de Saúde, para acessar o documento original na integra realize o download abaixo

Integração laboratório - Envio de Solicitação.pdf

Objetivo do documento

Este manual de interoperabilidade tem como objetivo permitir que as empresas responsáveis pelos sistemas de laboratórios terceirizados desenvolvam drivers de comunicação capazes de receber requisições de exames, assim como o cancelamento das mesmas, provenientes do sistema de gestão em saúde pública.

Com essa integração, o laboratório contratado terá acesso rápido e automatizado às informações disponibilizadas pelo cliente, o que agilizará significativamente as atividades laboratoriais do dia a dia.

Detalhes Técnicos

Pré-requisitos

- É necessário que o sistema do laboratório terceirizado seja capaz de receber a requisição do SIS, utilizando os protocolos REST ou SOAP. O protocolo REST é mais leve e utiliza métodos HTTP para interação com recursos, enquanto o protocolo SOAP é mais estruturado e utiliza XML para definir a estrutura da mensagem. A escolha entre REST e SOAP dependerá das necessidades específicas do projeto e das capacidades do sistema de laboratório terceirizado.
- No caso em que a instalação local do software de laboratório terceirizado não possui um endereço de entrada externo, é necessário acionar a equipe técnica da Vivver para estabelecer uma rede VPN. Essa VPN permitirá a conexão com o host do laboratório, viabilizando a comunicação segura entre os sistemas. Dessa forma, mesmo sem um endereço externo, a integração poderá ser realizada de forma adequada.
- Em casos onde a aplicação estiver com instalação local, e for necessário o uso da VPN, o endpoint do laboratório terceiro deve estar preparado para receber as requisições através da porta 7001.
- No caso da utilização da VPN, deverá ser parametrizado no SIS o host do certificado utilizado na VPN onde o software de laboratório terceirizado está localizado.
- O cliente deve parametrizar as unidades de saúde que enviarão os dados de solicitação de exames. Caso essa parametrização não seja realizada, nenhuma unidade enviará automaticamente os dados de solicitação de exames.
- A unidade de saúde deve criar e recepcionar a solicitação de exames, incluindo os respectivos exames que serão integrados, para que a transmissão seja realizada via webservice.

Envio de requisições - Fluxo simplificado

Após o alinhamento dos códigos do laboratório terceiro e a ativação do serviço para a unidade específica, no momento em que a coleta de amostras dos exames for registrada, as solicitações serão enviadas para uma fila de transmissão interna. Em um curto intervalo de tempo, as solicitações da fila serão transmitidas via webservice.

No processo de transmissão, o sistema Vivver aguardará o retorno do request dos exames para atualizar os dados nas respectivas solicitações. Isso garante que posteriormente, os resultados sejam recebidos e registrados corretamente, proporcionando a atualização dos dados pertinentes ao atendimento médico e à rotina laboratorial.

Endereço do Serviço

URL do Serviço: http://url_endpoint/InterfaceService.asmx ou host da VPN
Método HTTP: POST
SOAPAction: "ReceberPedido"
Content-Type: text/xml;charset=UTF-8

Definição do XML de envio de envio de requisição

Campo	Descrição	Tipo do Dado	Tamanho
pedido_lab.ordem_servico	Número da solicitação de exames no Sistema de Gestão Pública de Saúde	Numérico	13
pedido_lab.codigo_pedido	Número da solicitação de exames no Sistema de Gestão Pública de Saúde	Numérico	13
pedido_lab.pedido.codigo	Número da solicitação de exames no Sistema de Gestão Pública de Saúde	Numérico	13
pedido_lab.pedido.ordem_servico	Número da solicitação de exames no Sistema de Gestão Pública de Saúde	Numérico	13
pedido_lab.pedido.origem	Nome da unidade saúde que solicitou os exames	Texto	255
pedido_lab.pedido.profissional	Nome do profissional da unidade de saúde que solicitou os exames	Texto	255
pedido_lab.pedido.ufconselho	UF do conselho do profissional que solicitou os exames	Texto	2
pedido_lab.pedido.orgaoemissor	Nome do órgão emissor do profissional solicitante	Texto	255
pedido_lab.pedido.numconselho	Número do conselho do profissional solicitante	Texto	13
pedido_lab.pedido.equipe	Número INE da equipe em que o profissional solicitante está vinculado	Numérico	10
pedido_lab.pedido.posto	Posto de Coleta sugerido	Texto	120
pedido_lab.pedido.urgente	Indica se o exame é urgente (S = Sim, N = Não)	Texto	1
pedido_lab.pedido.cnesUnidadeExecutante	Código CNES da unidade de saúde que executará o exame.	Numérico	7
pedido_lab.pedido.codconvenio	Código do plano de saúde no sis relacionado a solicitação	Numérico	3
pedido_lab.pedido.convenio	Descrição do plano de saúde relacionado a solicitação.	Texto	255
pedido_lab.pedido.observacao	Justificativa da solicitação	Texto	1400
pedido_lab.pedido.gestante	Indica se no momento da solciitação a paciente está gestante (S ou N).	Texto	1
pedido_lab.pedido.codcid	Código do cid relacionado a solicitação.	Texto	4
pedido_lab.pedido.datahora	Data e hora da solicitação YYYY-MM-DD HH:MM:SS	Texto	19
pedido_lab.paciente.codigo	Número prontuário do paciente no Sistema de Gestão Pública de Saúde	Numérico	13
pedido_lab.paciente.nome	Nome do paciente no Sistema de Gestão Pública de Saúde	Texto	120
pedido_lab.paciente.sexo	Sexo do paciente no Sistema de Gestão Pública de Saúde	Texto	1
pedido_lab.paciente.dt_nascimento	Data de nascimento do paciente no Sistema de Gestão Pública de Saúde - AA-MM-DD	Texto	8
pedido_lab.paciente.raca	Código da raça/cor informada no cadastro do paciente: BRANCA PRETA PARDA AMARELA INDIGENA	Numérico	2
pedido_lab.paciente.etnia	Enviada somente se a tag raca for 05, conforme tabela padrão do SUS. O código enviado é uma referência ao código usado no eSUS : https://integracao.esusab.ufsc.br/ledi/documentacao/referencias/dicionario.html - Etnia	Texto	4
pedido_lab.paciente.altura	Altura do paciente informada no momento da coleta	Numérico	3
pedido_lab.paciente.peso	Peso do paciente informado no momento da coleta	Numérico	3
pedido_lab.paciente.cns	Número do cartão nacional do SUS do paciente	Numérico	15
pedido_lab.paciente.obscoleta	Observação da coleta	Texto	255
pedido_lab.paciente.nomemae	Nome da mãe do paciente no SIS	Texto	255
pedido_lab.paciente.nomesocial	Nome social do paciente informado no SIS	Texto	255
pedido_lab.paciente.endereco	Endereço de residência do paciente	Texto	255
pedido_lab.paciente.cep	CEP de residência do paciente	Numérico	8
pedido_lab.paciente.telefone	Telefone principal do paciente informado no SIS	Numérico	15
pedido_lab.paciente.email	E Mail do paciente preenchido no SIS	Texto	255
pedido_lab.paciente.rg	Número do documento de identidade do paciente	Texto	20
pedido_lab.paciente.cpf	Número CPF do paciente	Numérico	11
pedido_lab.exames.exame.codigo	Código do exame no Sistema de Gestão Pública de Saúde	Numérico	10
pedido_lab.exames.exame.amostra	ID da amostra da solicitação / código de barras da amostra	Numérico	13
pedido_lab.exames.exame.amostras.amostra.amostra.cbarra	ID da amostra da solicitação / código de barras da amostra	Numérico	13
pedido_lab.exames.exame.descricao	Descrição do exame no Sistema de Gestão Pública de Saúde	Numérico	70
pedido_lab.exame.recoleta	Indica se houve registro de problema na coleta S ou N	Texto	1
pedido_lab.exame.codmotivorecoleta	Código do motivo de problema na coleta quando existir recoleta for S	Numérico	3
pedido_lab.exame.desmotivorecoleta	Descrição do motivo de problema na coleta quando recoleta for S	Texto	255
pedido_lab.exames.exame.questionario.codigoPergunta	Código de identificação da pergunta do questionário respondido para o exame	Numérico	4
pedido_lab.exames.exame.questionario.pergunta	Descrição da pergunta do questionário	Texto	120
pedido_lab.exames.exame.questionario.resposta	Respostas das perguntas do questionário	Texto	120
pedido_lab.exames.anamnese.””tag_name””	Este bloco traz os mesmos dados das tags questionário acima, porém em uma estrutura diferente, onde o campo tag_name parametrizado nas perguntas e seus respectivos valores são enviadas como tag do objeto anamnese.	Texto	120
pedido_lab.exames.exame.itens.item.codigoItem	Código do item de resultado do exame no Sistema de Gestão Pública de Saúde	Numérico	4
pedido_lab.exames.exame.itens.item.sgl	Sigla do item de resultado do exame no Sistema de Gestão Pública de Saúde	Texto	10
pedido_lab.exames.exame.itens.item.descricao	Descrição da sigla do item de resultado do exame no Sistema de Gestão Pública de Saúde	Texto	70

Envio de requisição via cURL

# Envio de requisição via cURL
curl --location 'http://url_endpoint/InterfaceService.asmx' \
--header 'SOAPAction: ReceberPedido' \
--header 'Content-Type: text/xml;charset=UTF-8' \
--data 'PASTE_XML_HERE'

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:viv="http://www.vivver.com.br"
                  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <viv:ReceberPedido>
            <pedidoLab>
                <ordemServico>2022060003391</ordemServico>
                <codigoPedido>2022060003391</codigoPedido>
                <identificador/>
                <usuarioWebId/>

                <pedido>
                    <codigo>2022060003391</codigo>
                    <ordemServico>2022060003391</ordemServico>
                    <origem>LABORATORIO MUNICIPA</origem>
                    <profissional>PROFISSIONAL TESTE</profissional>
                    <ufconselho>MG</ufconselho>
                    <orgaoemissor/>
                    <numconselho>99999</numconselho>
                    <equipe/>
                    <posto>LABORATORIO MUNICIPAL</posto>
                    <urgente>N</urgente>
                    <cnesUnidadeExecutante>9999999</cnesUnidadeExecutante>
                    <codconvenio xsi:nil="true"/>
                    <convenio xsi:nil="true"/>
                    <observacao/>
                    <gestante>N</gestante>
                    <codcid xsi:nil="true"/>
                    <datahora>2022-06-30 11:23</datahora>
                </pedido>

                <paciente>
                    <codigo>166906</codigo>
                    <nome>Teste um</nome>
                    <sexo>F</sexo>
                    <dtNascimento>2024-01-01</dtNascimento>
                    <raca>03</raca>
                    <etnia/>
                    <altura xsi:nil="true"/>
                    <peso xsi:nil="true"/>
                    <cns>999999999999999</cns>
                    <obscoleta xsi:nil="true"/>
                    <nomemae>Estrangeira</nomemae>
                    <nomesocial xsi:nil="true"/>
                    <endereco>RUA TESTE ,1, CENTRO, MUNICIPIO TESTE</endereco>
                    <cep>35599999</cep>
                    <telefone>99999999</telefone>
                    <email xsi:nil="true"/>
                    <rg/>
                    <cpf>99999999999</cpf>
                </paciente>

                <exames>
                    <exame>
                        <codigo>299</codigo>
                        <amostra>047860200108</amostra>

                        <amostras>
                            <amostra>
                                <cBarra>047860200108</cBarra>
                            </amostra>
                        </amostras>

                        <obsexame/>
                        <descricao>HEMATOCRITO</descricao>

                        <questionario>
                            <codigoPergunta>1</codigoPergunta>
                            <pergunta>teste 1</pergunta>
                            <resposta>10</resposta>

                            <codigoPergunta>2</codigoPergunta>
                            <pergunta>teste 2</pergunta>
                            <resposta>Sim</resposta>

                            <codigoPergunta>3</codigoPergunta>
                            <pergunta>teste 3</pergunta>
                            <resposta>["", "Não pratica"]</resposta>
                        </questionario>

                        <anamnese>
                            <teste1>10</teste1>
                            <teste2>S</teste2>
                            <teste3>N</teste3>
                        </anamnese>

                        <recoleta>N</recoleta>
                        <codmotivorecoleta xsi:nil="true"/>
                        <desmotivorecoleta xsi:nil="true"/>

                        <itens>
                            <item>
                                <codigoItem>1</codigoItem>
                                <sgl>HEMAT</sgl>
                                <descricao>HEMATOCRITO</descricao>
                            </item>
                            <item>
                                <codigoItem>999</codigoItem>
                                <sgl>IntExa</sgl>
                                <descricao>Integração Exame</descricao>
                            </item>
                        </itens>
                    </exame>
                </exames>
            </pedidoLab>
        </viv:ReceberPedido>
    </soapenv:Body>
</soapenv:Envelope>

Definição do XML esperado no response de envio de requisição

Campo	Descrição	Tipo do Dado	Tamanho
ordemServico	Código da ordem de serviço	String	50
codigoPedido	Código do pedido do cliente	String	50
exames.exame.codigo	Código do exame	String	50
exames.exame.amostras.amostra.codig oBarra	Código de barras da amostra - não é obrigatório	String	50
exames.exame.amostras.amostra.etique ta	Dados da etiqueta	String	50
retorno	Situação da geração do pedido	Boolean	50
desErro	Descrição da situaçãp geração do pedido	String	50

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body>
        <ReceberPedidoResponse xmlns="http://www.vivver.com.br">
            <ReceberPedidoResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
                <ordemServico>2023090000007</ordemServico>
                <codigoPedido>2023090000007</codigoPedido>

                <exames>
                    <exame>
                        <codigo>127</codigo>
                        <amostra>0121000208</amostra>
                    </exame>
                </exames>

                <retorno>true</retorno>
                <desErro i:nil="true"/>
            </ReceberPedidoResult>
        </ReceberPedidoResponse>
    </s:Body>
</s:Envelope>

Envio de cancelamento - Fluxo Simplificado

No momento em que o cancelamento da coleta de um determinado exame da solicitação, ou de todos, é efetuado, a situação do registro já existente na fila de transmissão interna é atualizada para ser cancelada. Em um curto intervalo de tempo, estes cancelamentos da fila serão transmitidos via webservice para método específico.

Endereço do Serviço

URL do Serviço: http://url_endpoint/InterfaceService.asmx ou host da VPN
Método HTTP: POST
SOAPAction: "ReceberCancelamento"
Content-Type: text/xml;charset=UTF-8

Definição do XML de envio de envio de requisição

Campo	Descrição	Tipo do Dado	Tamanho
pedidoLab.identificador	Nome do sistema de gestão em saúde pública	String fixa	SISGS
pedido_lab.pedido.codigo	Número da solicitação de exames no SIS Vivver	Numérico	13
pedido_lab.pedido.ordem_servico	Número da solicitação de exames no SIS Vivver	Numérico	13
pedido_lab.pedido.cancelamentoTotal	Indica se é cancelamento outal ou somente de determinado registro	boolean	false ou true
pedido_lab.pedido.exames.exame.codigo	Código do exame cancelado	Integer	5
pedido_lab.pedido.exames.exame.codmotivorecoleta	Código no SIS do motivo do cancelamento da amostra	Integer	5
pedido_lab.pedido.exames.exame.desmotivorecoleta	Descrição do motivo do cancelamento da amostra	Texto	255

# Envio de requisição via cURL para cancelamento de exames
curl -X POST http://vpn1.root.ooo:7017/InterfaceService.asmx \
-H "SOAPAction: \"ReceberCancelamento\"" \
-H "Content-Type: text/xml;charset=UTF-8" \
-d 'PASTE_XML_HERE'

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:viv="http://www.vivver.com.br"
                  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <viv:ReceberCancelamento>
            <pedidoLab>
                <identificador>SISGS</identificador>

                <pedido>
                    <codigo>2024080000008</codigo>
                    <ordemServico>2024080000008</ordemServico>
                    <cancelamentoTotal>false</cancelamentoTotal>
                </pedido>

                <exames>
                    <exame>
                        <codigo>1554</codigo>
                        <codmotivorecoleta>32</codmotivorecoleta>
                        <desmotivorecoleta>AMOSTRA INSUFICIENTE</desmotivorecoleta>
                    </exame>
                    <exame>
                        <codigo>10</codigo>
                        <codmotivorecoleta>31</codmotivorecoleta>
                        <desmotivorecoleta>AMOSTRA INCORRETA</desmotivorecoleta>
                    </exame>
                </exames>
            </pedidoLab>
        </viv:ReceberCancelamento>
    </soapenv:Body>
</soapenv:Envelope>

Definição do XML esperado no response de envio de cancelamento

Campo	Descrição	Tipo do Dado	Tamanho
pedido.codigo	Número da solciitação	String	50
exames.exame.codigo	Código do exame	String	50
exames.exame.desricaoRetorno	Descrição da situação do cancelamento do exame	String	50
.situacao	Situação da geração do cancelamento	Boolean	50
descricao	Descrição da situaçãp geração do cancelamento	String	50

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:s="http://www.w3.org/2001/XMLSchema">
    <SOAP-ENV:Body>
        <ReceberCancelamentoResponse xmlns="http://www.example.com">
            <ReceberCancelamentoResult>true</ReceberCancelamentoResult>

            <s01:retornoLab xmlns="http://www.example.com/cancelamento"
                            xmlns:s01="http://www.example.com">
                <pedido>
                    <codigo>2024080000087</codigo>
                </pedido>

                <exames>
                    <exame>
                        <codigo>839</codigo>
                        <descricaoRetorno>Exame(s) Cancelado(s) com sucesso.</descricaoRetorno>
                    </exame>
                    <exame>
                        <codigo>003</codigo>
                        <descricaoRetorno>Exame(s) Cancelado(s) com sucesso.</descricaoRetorno>
                    </exame>
                </exames>

                <situacao>true</situacao>
                <descricao>Processo realizado com sucesso.</descricao>
            </s01:retornoLab>
        </ReceberCancelamentoResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>