API Atualização Cadastral - Mobile Saúde

CONTEÚDO

1. Visão Geral
2. Exemplo de utilização
   1. Método submit_formulario
      1. Regras de Negocio do Método
      2. EndPoint

      3. Parâmetros de Entrada do Método

      4. Exemplo

      5. Estrutura de Retorno

   2. Método atualiza_status_protocolo
      1. Regras de Negocio do Método
      2. EndPoint

      3. Parâmetros de Entrada do Método

3. Tela Atualização Cadastral
   1. Outras Ações / Ações relacionadas
      
4. Tela Atualização Cadastral
   1. Principais Campos e Parâmetros
      
5. Tabelas utilizadas

01. VISÃO GERAL

Este documento tem como objetivo demonstrar a utilização da API Atualização Cadastral para a integração do TOTVS Saúde Planos Linha Protheus com a Mobile Saúde, onde o beneficiário irá solicitar suas alterações cadastrais. 

Os protocolos serão gerados na rotina de Analise de Beneficiários para que a Operadora analise as solicitações.

Lembrando que essa API deverá ser integrada com o Call-Back da Mobile Saúde, Para saber como o Call-Back funciona na atualização cadastra, siga esse link: CallBack - Atualização Cadastral

A API utilizará o padrão REST.

02. EXEMPLO DE UTILIZAÇÃO

Segue os métodos utilizados na API:

• submit_formulario: Inseri uma nova solicitação de atualização cadastral para análise, o beneficiário poderá envia seus dados pessoais, correções e alterações de seu cadastro, além de arquivos de comprovante.
• atualiza_status_protocolo: Atualiza o status de um protocolo de atualização cadastral iniciado. (Esse método é utilizado para enviar o status do TOTVS Saúde Planos Linha Protheus para a Mobile Saúde)

Abaixo será apresentado exemplo do método. 

A autenticação é realizada através da Api /token, onde será retornado a chave e token a ser adicionado no header de cada método.

Método submit_formulario

Este método irá inserir um novo protocolo de alteração cadastral do beneficiário na Analise de Beneficiários (PLSA977AB).

Regras de Negocio do Método

Para utilização do método é necessário realizar o de/para da Mobile Saúde com o TOTVS Saúde Planos Linha Protheus, através da rotina De/Para de Integrações (PLIntegDePara), esse cadastro ficará por padrão a partir da release 12.1.2210 na pasta: Atualizações > Integrações > De/Para Integrações

Segue um exemplo do cadastro de de/para:

Será necessário realizar esses três tipos de De/para no cadastro, sendo a Referência sempre PMOBATUCADMOD

• Cadastro de De/para Normal: O campo externo é o conteúdo do atributo do JSON (campos.name) referente a Mobile Saúde, o campo interno é o campo cadastrado no Layout Genérico (Será sempre campos da tabela BA1), o tipo deverá ser igual a 0  - Campo.
• Cadastro de De/para de Arquivos para Download: O campo externo é o conteúdo do atributo do JSON (campos.name) referente a Mobile Saúde, não precisa informar o campo interno, é necessário colocar o Valor URL igual a 1 - Sim
• Cadastro de De/para de Valores: O campo externo é o conteúdo do atributo do JSON (campos.name) referente a Mobile Saúde, o campo interno é o campo cadastrado no Layout Genérico (Será sempre campos da tabela BA1), o tipo deverá ser igual a 1 - Campo, o valor externo é o conteúdo correspondente a Mobile Saúde e o valor interno é o conteúdo correspondendo a Protheus. Nesse caso, o status da Mobile 0 corresponde ao status 1 do Protocolo de Alteração (BBA_STATUS). 

Para facilitar a implantação foi criado o CSV para importar os de/para da mobile automaticamente via Wizard: b7v-de_para_integracoes.csv

Porém o de/para de status precisa ser incluído manualmente, conforme tabela abaixo:

O método utiliza o layout genérico Web, portanto é necessário ter cadastrado o Layout PPLALTBEN para que o sistema valide os dados da API com base no Layout, será feita as seguintes validações:  

• Se o campo encontra-se no Layout
• Se o campo permite edição (B91_EDITAR)

Caso os dados informados na API sejam validados, o sistema irá gravar um novo protocolo na Analise de Beneficiários para o tipo Alteração. Além disso será verificado se os campos informados no protocolo estão configurados no Layout para aprovar automaticamente ou passar por analise.

Essa configuração é realizada na Configuração Complementar (B2C) do Layout Genérico, informando a variável VALIDA e o valor .T., o campo irá passar por analise e não informando variável VALIDA, será feita a atualização automática dos dados no cadastro do beneficiário (BA1). Para mais informações sobre o cadastro do Layout Genérico Web, acessem esse link: Layout Genérico Web - PLSCADLAY

Se todos os campos forem atualizados automaticamente, o protocolo ficará com o status igual a Aprovado Automaticamente (BBA_STATUS igual a 7), se pelo menos algum campo precisar de analise, o status será Em Analise (BBA_STATUS igual a 2).

Endpoint

Parâmetros de Entrada do Método

Exemplo

{
   "protocolo":"41750520220318145554",
   "id_operadora":"1",
   "mshash":"ZDhkNjY0MDY3NTgwMTg0Y2I4ZWE3ZmZiZGEyNDM0NmMwZDI0YmQwYw==",
   "tipo":"",
   "nome":"SEBASTIAO CARLOS FELIPE MELO",
   "matricula":"00011008000007035",
   "matricula_titular":"00011008000007035",
   "campos":[
      {
         "id":"10",
         "label":"bairro",
         "name":"atualizacao_cadastral_bairro",
         "value":"Centro"
      },
      {
         "id":"11",
         "label":"endereco",
         "name":"atualizacao_cadastral_endereco",
         "value":"Rua Teste"
      },
      {
         "id":"11",
         "label":"endereco",
         "name":"atualizacao_cadastral_comprovante_de_endereco",
         "value":"https://centraldeatendimento.totvs.com/hc/article_attachments/360027449931/mceclip2.png"
      }
   ]
}

{
    "status": "0",
    "mshash": "ZDhkNjY0MDY3NTgwMTg0Y2I4ZWE3ZmZiZGEyNDM0NmMwZDI0YmQwYw==",
    "protocolo": "41750520220318145554"
}

{
    "timestamp": "2022-03-21T17:23:15-03:00",
    "data": [],
    "status": false,
    "critica": [
        {
            "cod": 0,
            "trace": "",
            "origem": "/mobileSaude/submit_formulario",
            "descricao": "Protocolo informado já existente no sistema. [41750520220318145551]"
        }
    ],
    "msg": "Protocolo informado já existente no sistema. [41750520220318145551]"
}

Estrutura de Retorno

Método atualiza_status_protocolo

Este método será utilizado pelo sistema para comunicar com a API da Mobile Saúde para atualizar o status do protocolo solicitado.

Regras de Negocio do Método

Deverá ser cadastrado no campo URL Status (BA0_MSURST), o Endpoint fornecido pelo Mobile Saúde para atualizar o status do protocolo.

Quando o usuário aprovar ou negar a atualização do protocolo na Analise de Beneficiários, o sistema irá realizar a comunicação desse método com a Mobile Saúde.

Também é possível atualizar o status do protocolo através do botão Outras Ações > Atualizar Status da Rotina de Analise de beneficiários.

Endpoint

Parâmetros de Entrada do Método

Veja um exemplo de como a comunicação com a API é feita na prática: 

03. TELA ATUALIZAÇÃO CADASTRAL

Outras Ações / Ações relacionadas

04. TELA ATUALIZAÇÃO CADASTRAL

Principais Campos e Parâmetros

05. TABELAS UTILIZADAS

• BBA - Cabeçalho da Solicitação de Beneficiários
• B7L - Itens das Alterações Solicitadas 
• BA0 - Cadastro de Operadoras
• B90 - Layout Genérico Web
• B7C - Grupos de Campos do Layout Genérico Web
• B91 - Campos do Layout Genérico Web
• B2C - Configurações dos Campos do Layout Genérico Web
• BA1 - Cadastro de Beneficiários
• B7V - Cadastro de De/para de Integrações