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.
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.
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.
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:
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).
O Layout utilizado na API, deverá utilizar exclusivamente a tabela BA1. |
Abaixo será apresentado um exemplo de cada método da API PLAltBenModel.
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â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. |
{ "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" } ] } ] } ] } |
{ "errorCode": 404, "errorMessage": "The server can't find the requested resource." } |
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â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.
{ "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.
{ "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" } ] } ] } ] } ] } |
{ "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" } |
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âmetro | Obrigatório | Tipo | Descrição |
---|---|---|---|
pk | Sim | Caracter | Valor da chave primaria do alias do modelo em encodado em base64. |
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.
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âmetro | Obrigatório | Tipo | Descrição |
---|---|---|---|
pk | Sim | Caracter | Valor da chave primaria do alias do modelo em encodado em base64. |
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.
true |
{ "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" } |
Outras Ações / Ações relacionadas
Ação | Descrição |
---|---|
Não se aplica | Não se aplica |
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. |