API PLAltBenModel - Protocolo de Alteração de Beneficiários

CONTEÚDO

Visão Geral
Exemplo de utilização
1. Layout Genérico Web
2. Get API
3. Post API
4. Put API
5. Delete API
Tela API PLAltBenModel
1. Outras Ações / Ações relacionadas
Tela API PLAltBenModel
1. Principais Campos e Parâmetros
Tabelas utilizadas

01. VISÃO GERAL

Este documento tem como objetivo demonstrar a utilização da API PLAltBenModel, onde será realizada a solicitação de um novo protocolo de alteração de beneficiários.

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

A API utilizará o padrão REST.

02. EXEMPLO DE UTILIZAÇÃO

Foi desenvolvido o modelo de dados (ModelDef) para alterar os dados do beneficiário, e através da classe FWRestModel foi feita a publicação do modelo para que seja consumido via API padrão REST.

Para retornar a lista de registros referente ao modelo de dados deve-se efetuar um GET sem informar a <PK>. Os registros listados terão filtrados pelas filiais que o usuário tem acesso (isso se o campo filial existir.)

Para inserir um registro deve-se efetuar um POST sem informar a <PK> e enviar no body o conteúdo a ser inserido.

Ao informar o parâmetro <PK> será acessado um registro em específico e assim podendo ser utilizado os métodos GET, PUT, DELETE.

Além disso, a API poderá receber alguns filtros (QueryStrings) no headers da requisição, como:

Key	Descrição
STARTINDEX	Indica a partir que qual index deverá ser retornado (padrão: 1)
INTERNALID	Indica se deve retornar o ID(Recno) como informação complementar das linhas do GRID (padrão: false)
FIRSTLEVEL	Habilita o retorno dos sub modelos (padrão: true)
FILTER	Filtro que será aplicado no método SetFilter()
FIELDVIRTUAL	Habilita o retorno de campos virtuais (padrão: false)
FIELDS	Indica os campos a serem filtrados no retorno do modelo, incluindo os sub modelos, caso não informado todos os campos serão retornados
FIELDEMPTY	Habilita o retorno de campos sem valores (padrão: false)
FIELDDETAIL	Habilita mostrar mais informações nos campos do modelo (padrão: 10)
DEBUG	Valor booleano para habilitar o modo debug (padrão: false)
COUNT	Quantidade de registro que devem ser retornados (padrão: 10)
CACHE	Indica se sera feito cache do total de registros por alias, refere-se ao valor do total no retorno (padrão: true)

Exemplo de utilização: Key igual FILTER e value igual BBA_CODSEQ=000770, será retornado somente o protocolo com o código sequencial com o numero 000770.

FWRestModel

Para mais informações de como utilizar esse modelo de API, acessem a documentação da classe FWRestModel.

A autenticação da API é realizada pelo headers Authorization, Type Basic Auth, Usuário e Senha do Protheus.

LAYOUT GENÉRICO WEB

Algumas regras na API poderão ser adicionadas pelo Layout genérico Web, o mesmo deverá ser adicionada no MV_PLLAYAL.

Por exemplo: MV_PLLAYAL = PPLALTBEN, a api irá utilizar as configurações contidas nessa layout genérico.

Pelo Layout o sistema irá utilizar as seguintes regras no modelo de dados para validar a alteração de beneficiários:

Campos que não permite alterar: B91_EDITAR igual a .F.
Campos que necessitam de aprovação da Operadora, B2C_VAR igual a VALIDA.

Esse configuração de VALIDA é realizada na Configuração Complementar (B2C) do Layout Genérico, informando a variável VALIDA e o valor .T., ou seja, o campo irá passar por analise, caso não seja informado, 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).

Importante

O Layout utilizado na API, deverá utilizar exclusivamente a tabela BA1.

Abaixo será apresentado um exemplo de cada método da API PLAltBenModel.

GET API

Endpoint

Url	Método	Header Content-Type	Descrição
https://<url>:<porta>/rest/fwmodel/PLAltBenModel/[pk]	GET	application/json	Retorna os protocolo da analise de beneficiários, para retornar somente um protocolo deverá ser informado a pk do mesmo.

Parâmetro <PK> é opcional, sendo usado pra retornar os detalhes de um protocolo.

Parâmetros de Entrada do Método

Parâmetro	Obrigatório	Tipo	Descrição
pk	Não	Caracter	Valor da chave primaria do alias do modelo em encodado em base64, esse valor será obtido ao consultar todos os protocolos.

Exemplo

Request body

API Retorno - Sucesso

{
    "total": 1,
    "count": 1,
    "startindex": 1,
    "resources": [
        {
            "id": "PLAltBenModel",
            "operation": 1,
            "pk": "TSBTUCAgICAwMDA3ODQ=",
            "models": [
                {
                    "id": "MASTERBBA",
                    "modeltype": "FIELDS",
                    "fields": [
                        {
                            "id": "BBA_FILIAL",
                            "order": 1,
                            "value": "M SP"
                        },
                        {
                            "id": "BBA_CODSEQ",
                            "order": 2,
                            "value": "000784"
                        },
                        {
                            "id": "BBA_TIPSOL",
                            "order": 3,
                            "value": "2"
                        },
                        {
                            "id": "BBA_STATUS",
                            "order": 4,
                            "value": "7"
                        },
                        {
                            "id": "BBA_CODINT",
                            "order": 5,
                            "value": "0001"
                        },
                        {
                            "id": "BBA_CODEMP",
                            "order": 6,
                            "value": "1008"
                        },
                        {
                            "id": "BBA_CONEMP",
                            "order": 7,
                            "value": "000000000001"
                        },
                        {
                            "id": "BBA_VERCON",
                            "order": 8,
                            "value": "001"
                        },
                        {
                            "id": "BBA_SUBCON",
                            "order": 9,
                            "value": "000000004"
                        },
                        {
                            "id": "BBA_VERSUB",
                            "order": 10,
                            "value": "001"
                        },
                        {
                            "id": "BBA_MATRIC",
                            "order": 11,
                            "value": "00011008000019017"
                        },
                        {
                            "id": "BBA_EMPBEN",
                            "order": 12,
                            "value": "MARIO IGOR RAFAEL CARDOSO"
                        },
                        {
                            "id": "BBA_CODPRO",
                            "order": 13,
                            "value": "0001"
                        },
                        {
                            "id": "BBA_VERSAO",
                            "order": 14,
                            "value": "001"
                        },
                        {
                            "id": "BBA_DATSOL",
                            "order": 15,
                            "value": "20220607"
                        },
                        {
                            "id": "BBA_HORSOL",
                            "order": 16,
                            "value": "13:52"
                        },
                        {
                            "id": "BBA_NROPRO",
                            "order": 18,
                            "value": "41750520220607000784"
                        },
                        {
                            "id": "BBA_TIPMAN",
                            "order": 19,
                            "value": "2"
                        },
                        {
                            "id": "BBA_CPFTIT",
                            "order": 20,
                            "value": "28896585201"
                        },
                        {
                            "id": "BBA_APROVA",
                            "order": 21,
                            "value": "T"
                        }
                    ]
                }
            ]
        }
    ]
}

Retorno API - Falha

{
    "errorCode": 404,
    "errorMessage": "The server can't find the requested resource."
}

POST API

Endpoint

Url	Método	Header Content-Type	Descrição
https://<url>:<porta>/rest/fwmodel/PLAltBenModel/	POST	application/json	Realiza a inclusão de um novo protocolo de alteração na analise de beneficiários

Parâmetros de Entrada do Método

Parâmetro (fields)	Obrigatório	Tipo	Descrição
BBA_MATRIC	Sim	Caracter	Matricula do Beneficiário que será feita a atualização dos dados.

B7L_CAMPO	Sim	Caracter	Campo do sistema para realizar a alteração (Tabela BA1).
B7L_VLPOS	Sim	Caracter	Novo Conteúdo do campo.
B7L_USR	Sim	Caracter	Usuário que solicitou a alteração.

DIRECTORY	Não	Caracter	Diretório http do arquivo para anexar ao protocolo de alteração.
FILENAME	Não	Caracter	Nome para ao arquivo.

Os demais parâmetros do json, segue o mesmo padrão para toda requisição de POST.

Exemplo

Request body

{
    "id": "PLAltBenModel",
    "operation": 3,
    "models": [
        {
            "id": "MASTERBBA",
            "modeltype": "FIELDS",
            "fields": [
                {
                    "id": "BBA_MATRIC",
                    "order": 1,
                    "value": "00011008000019017"
                }
            ],
            "models": [
                {
                    "id": "DETAILB7L",
                    "modeltype": "GRID",
                    "items": [
                        {
                            "id": 1,
                            "deleted": 0,
                            "fields": [
                                {
                                    "id": "B7L_CAMPO",
                                    "value": "BA1_EMAIL"
                                },
                                {
                                    "id": "B7L_VLPOS",
                                    "value": "[email protected]"
                                },
                                {
                                    "id": "B7L_USER",
                                    "value": "API TOTVS"
                                }
                            ]
                        }
                    ]
                },
                {
                    "id": "DETAILANEXO",
                    "modeltype": "GRID",
                    "items": [
                    {
                        "id": 1,
                        "deleted": 0,
                        "fields": [
                            {
                                "id": "DIRECTORY",
                                "value": "https://centraldeatendimento.totvs.com/hc/article_attachments/360027449931/mceclip2.png"
                            },
                            {
                                "id": "FILENAME",
                                "value": "Teste_alteracao"
                            }
                        ]
                    }
                ]
                }
            ]
        }
    ]
}

Ao solicitar um POST com sucesso, o mesmo irá retornar o protocolo como se tivesse realizado um GET com a pk correspondente ao protocolo.

API Retorno - Sucesso

{
    "id": "PLAltBenModel",
    "operation": 1,
    "pk": "TSBTUCAgICAwMDA3ODY=",
    "models": [
        {
            "id": "MASTERBBA",
            "modeltype": "FIELDS",
            "fields": [
                {
                    "id": "BBA_FILIAL",
                    "order": 1,
                    "value": "M SP"
                },
                {
                    "id": "BBA_CODSEQ",
                    "order": 2,
                    "value": "000786"
                },
                {
                    "id": "BBA_TIPSOL",
                    "order": 3,
                    "value": "2"
                },
                {
                    "id": "BBA_STATUS",
                    "order": 4,
                    "value": "7"
                },
                {
                    "id": "BBA_CODINT",
                    "order": 5,
                    "value": "0001"
                },
                {
                    "id": "BBA_CODEMP",
                    "order": 6,
                    "value": "1008"
                },
                {
                    "id": "BBA_CONEMP",
                    "order": 7,
                    "value": "000000000001"
                },
                {
                    "id": "BBA_VERCON",
                    "order": 8,
                    "value": "001"
                },
                {
                    "id": "BBA_SUBCON",
                    "order": 9,
                    "value": "000000004"
                },
                {
                    "id": "BBA_VERSUB",
                    "order": 10,
                    "value": "001"
                },
                {
                    "id": "BBA_MATRIC",
                    "order": 11,
                    "value": "00011008000019017"
                },
                {
                    "id": "BBA_EMPBEN",
                    "order": 12,
                    "value": "MARIO IGOR RAFAEL CARDOSO"
                },
                {
                    "id": "BBA_CODPRO",
                    "order": 13,
                    "value": "0001"
                },
                {
                    "id": "BBA_VERSAO",
                    "order": 14,
                    "value": "001"
                },
                {
                    "id": "BBA_DATSOL",
                    "order": 15,
                    "value": "20220607"
                },
                {
                    "id": "BBA_HORSOL",
                    "order": 16,
                    "value": "14:58"
                },
                {
                    "id": "BBA_NROPRO",
                    "order": 18,
                    "value": "41750520220607000786"
                },
                {
                    "id": "BBA_TIPMAN",
                    "order": 19,
                    "value": "2"
                },
                {
                    "id": "BBA_CPFTIT",
                    "order": 20,
                    "value": "28896585201"
                },
                {
                    "id": "BBA_APROVA",
                    "order": 21,
                    "value": "T"
                }
            ],
            "models": [
                {
                    "id": "DETAILB7L",
                    "modeltype": "GRID",
                    "struct": [
                        {
                            "id": "B7L_FILIAL",
                            "order": 1
                        },
                        {
                            "id": "B7L_SEQUEN",
                            "order": 2
                        },
                        {
                            "id": "B7L_ALIAS",
                            "order": 3
                        },
                        {
                            "id": "B7L_CAMPO",
                            "order": 4
                        },
                        {
                            "id": "B7L_ALIACH",
                            "order": 5
                        },
                        {
                            "id": "B7L_CHAVE",
                            "order": 6
                        },
                        {
                            "id": "B7L_VLANT",
                            "order": 7
                        },
                        {
                            "id": "B7L_VLPOS",
                            "order": 8
                        },
                        {
                            "id": "B7L_GRAVAD",
                            "order": 9
                        },
                        {
                            "id": "B7L_TIPO",
                            "order": 10
                        },
                        {
                            "id": "B7L_RECREG",
                            "order": 11
                        },
                        {
                            "id": "B7L_DATA",
                            "order": 12
                        },
                        {
                            "id": "B7L_HORA",
                            "order": 13
                        },
                        {
                            "id": "B7L_USER",
                            "order": 14
                        },
                        {
                            "id": "B7L_CHVREG",
                            "order": 15
                        }
                    ],
                    "items": [
                        {
                            "id": 1,
                            "deleted": 0,
                            "fields": [
                                {
                                    "id": "B7L_FILIAL",
                                    "value": "M SP"
                                },
                                {
                                    "id": "B7L_SEQUEN",
                                    "value": "00000712"
                                },
                                {
                                    "id": "B7L_ALIAS",
                                    "value": "BA1"
                                },
                                {
                                    "id": "B7L_CAMPO",
                                    "value": "BA1_EMAIL"
                                },
                                {
                                    "id": "B7L_ALIACH",
                                    "value": "BBA"
                                },
                                {
                                    "id": "B7L_CHAVE",
                                    "value": "000786"
                                },
                                {
                                    "id": "B7L_VLANT",
                                    "value": "[email protected]"
                                },
                                {
                                    "id": "B7L_VLPOS",
                                    "value": "[email protected]"
                                },
                                {
                                    "id": "B7L_GRAVAD",
                                    "value": "T"
                                },
                                {
                                    "id": "B7L_TIPO",
                                    "value": "2"
                                },
                                {
                                    "id": "B7L_RECREG",
                                    "value": "439"
                                },
                                {
                                    "id": "B7L_DATA",
                                    "value": "20220607"
                                },
                                {
                                    "id": "B7L_HORA",
                                    "value": "14:58"
                                },
                                {
                                    "id": "B7L_USER",
                                    "value": "API TOTVS"
                                }
                            ]
                        }
                    ]
                },
                {
                    "id": "DETAILANEXO",
                    "modeltype": "GRID",
                    "optional": 1,
                    "struct": [
                        {
                            "id": "CODSEQ",
                            "order": 1
                        },
                        {
                            "id": "DIRECTORY",
                            "order": 2
                        },
                        {
                            "id": "FILENAME",
                            "order": 3
                        }
                    ],
                    "items": [
                        {
                            "id": 1,
                            "deleted": 0,
                            "fields": [
                                {
                                    "id": "CODSEQ",
                                    "value": "000786"
                                },
                                {
                                    "id": "DIRECTORY",
                                    "value": "TESTE_ALTERACAO.PNG"
                                },
                                {
                                    "id": "FILENAME",
                                    "value": "Teste_alteracao"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Retorno API - Falha

{
    "errorCode": 400,
    "errorMessage": "\r\n --- Erro no Modelo ---\r\nId submodelo origem:[DETAILB7L]\r\nId campo origem:[VLDDATA_POST]\r\nId submodelo erro: [DETAILB7L]\r\nId campo erro: []\r\nId erro: [VALID     ]\r\nMensagem de erro: [ O campo (B7L_VLPOS) não foi preenchido.[Item: 1]]\r\nMensagem da solução: [\r\n]\r\nValor atribuído: []\r\nValor anterior: []\r\n"
}

PUT API

Endpoint

Url	Método	Header Content-Type	Descrição
https://<url>:<porta>/rest/fwmodel/PLAltBenModel/[pk]	PUT	application/json	Realiza a alteração de um protocolo já existente na analise de beneficiários. (Somente os protocolos que não foram analisados ou finalizados poderão ser alterados).

Parâmetro <PK> obtido através dos métodos POST ou GET.

Parâmetros de Entrada do Método

Parâmetro	Obrigatório	Tipo	Descrição
pk	Sim	Caracter	Valor da chave primaria do alias do modelo em encodado em base64.

Exemplo

O JSON de envio do PUT é o mesmo realizado no POST, o que irá mudar é o atributo operation com o valor 4 e o valor dos campos que irão ser alterados.

O retorno da API será o mesmo do POST, caso realizado a alteração com sucesso, será retornado o protocolo como se tivesse realizado um GET com a pk correspondente ao protocolo. Caso ocorra alguma validação será apresentada a critica.

DELETE API

Endpoint

Url	Método	Header Content-Type	Descrição
https://<url>:<porta>/rest/fwmodel/PLAltBenModel/[pk]	DELETE	application/json	Realiza a exclusão de um protocolo já existente na analise de beneficiários. (Somente os protocolos que não foram analisados ou finalizados poderão ser excluídos).

Parâmetro <PK> obtido através dos métodos POST ou GET.

Parâmetros de Entrada do Método

Parâmetro	Obrigatório	Tipo	Descrição
pk	Sim	Caracter	Valor da chave primaria do alias do modelo em encodado em base64.

Exemplo

O JSON de envio do DELETE é o mesmo realizado no POST ou no PUT, o que irá mudar é o atributo operation com o valor 5.

API Retorno - Sucesso

true

Retorno API - Falha

{
    "errorCode": 400,
    "errorMessage": "\r\n --- Erro no Modelo ---\r\nId submodelo origem:[]\r\nId campo origem:[]\r\nId submodelo erro: [PLAltBenModel]\r\nId campo erro: []\r\nId erro: [VALID     ]\r\nMensagem de erro: [ Não é permitido excluir ou alterar protocolo de solicitação quando estiver em analise ou finalizado.]\r\nMensagem da soluçãoo: [\r\n]\r\nValor atribuído: []\r\nValor anterior: []\r\n"
}

03. TELA API PLALTBENMODEL

Outras Ações / Ações relacionadas

Ação	Descrição
Não se aplica	Não se aplica

04. TELA API PLALTBENMODEL

Principais Campos e Parâmetros

Campo	Descrição
MV_PLLAYAL	Define Layout Genérico Web que estará vinculado a API de alteração de Beneficiário para Analise.
BBA_MATRIC	Matricula do Beneficiário que irá atualizar os dados
B7L_CAMPO	Campo da tabela BA1 correspondente a alteração
B7L_VLPOS	Novo valor do campo da tabela BA1 informado no B7L_CAMPO.
MV_PLURDOW	Diretório web para salvar os arquivos recebidos via API do produto TOTVS Saúde Planos.

05. TABELAS UTILIZADAS

BBA - Cabeçalho Solic. Beneficiarios
B2N - Inclusão de Beneficiários
BA1 - Cadastro de Beneficiários
BA3 - Família
B90 - Layout Pag. Web
B91 - Campos Layout
ACB - Bancos de Conhecimentos
AC9 - Relação de Objetos x Entidades

Árvore de páginas

API PLAltBenModel - Protocolo de Alteração de Beneficiários

CONTEÚDO

01. VISÃO GERAL

02. EXEMPLO DE UTILIZAÇÃO

LAYOUT GENÉRICO WEB

GET API

Endpoint

Parâmetros de Entrada do Método

Exemplo

POST API

Endpoint

Parâmetros de Entrada do Método

Exemplo

PUT API

Endpoint

Parâmetros de Entrada do Método

Exemplo

DELETE API

Endpoint

Parâmetros de Entrada do Método

Exemplo

03. TELA API PLALTBENMODEL

04. TELA API PLALTBENMODEL

05. TABELAS UTILIZADAS