01. DADOS GERAIS

02. SITUAÇÃO/REQUISITO

Ao incluir um ou mais beneficiários através do endpoint PLIncAutoBenModel, tornou-se necessário gravar os opcionais.

03. SOLUÇÃO

Durante o processamento de criação de um beneficiário, os opcionais são automaticamente vinculados ao seu cadastro, considerando as seguintes situações:

Pessoa Jurídica

Para que a gravação ocorra corretamente:

• O plano (produto no cadastro de produtos) que possui os opcionais vinculados deve estar associado ao subcontrato.
• O código do plano (produto) deve ser informado na propriedade B2N_CODPRO no body da requisição, que será refletido no campo BA1_CODPLA no cadastro de beneficiários

Pessoa Física

Para que a gravação ocorra corretamente:

• O plano (produto no cadastro de produtos) deve estar configurado com os opcionais vinculados.
• O código do plano (produto) deve ser informado na propriedade B2N_CODPRO no body da requisição, que será refletido no campo BA1_CODPLA no cadastro de beneficiários.

Parâmetro de Controle – MV_PLCAROP

A gravação dos opcionais é controlada pelo parâmetro MV_PLCAROP, que pode assumir os seguintes valores:

Schema de Retorno

Quando houver a gravação de um ou mais opcionais, o response do endpoint exibirá uma seção identificada pelo ID DETAILOPC quando a inclusão de um ou mais beneficiários ocorrer com sucesso.

Essa seção conterá as seguintes propriedades principais:

• MATRICULA - Matrícula do beneficiário ao qual os opcionais foram vinculados.
• RESULT - Resultado da gravação.

A propriedade RESULT retorna uma string em formato JSON, contendo os detalhes da operação.

Estrutura do JSON na Propriedade RESULT

O JSON retornado em RESULT possui as seguintes propriedades:

• product - Código do opcional (cadastrado como produto no cadastro de produtos) para o qual foi realizada a tentativa de gravação.
• version - Versão do opcional.
• response - Objeto que representa o resultado da tentativa de gravação do opcional, contendo:

• • success: indica se a gravação foi bem-sucedida.
    • true → gravação realizada com sucesso.
    • false → gravação não realizada.
  • message: em caso de falha (success = false), retorna o possível motivo da não gravação.

{
   "id": "DETAILOPC",
   "modeltype": "GRID",
   "optional": 1,
   "struct": [
       {
            "id": "MATRICULA",
            "order": 1
       },
       {
            "id": "RESULT",
            "order": 2
       }
   ],
   "items": [
       {
            "id": 1,
            "deleted": 0,
            "fields": [
                {
                    "id": "MATRICULA",
                    "value": "00010001000152008"
                },
                {
                    "id": "RESULT",
                    "value": "[{\"product\":\"9896\",\"version\":\"001\",\"response\":{\"success\":true,\"message\":\"\"}},{\"product\":\"9897\",\"version\":\"001\",\"response\":                       					\"success\":true,\"message\":\"\"}}]"
                }
            ]
       },
       {
            "id": 2,
            "deleted": 0,
            "fields": [
                {
                    "id": "MATRICULA",
                    "value": "00010001000152016"
                },
                {
                    "id": "RESULT",
                    "value": "[{\"product\":\"9896\",\"version\":\"001\",\"response\":{\"success\":true,\"message\":\"\"}},{\"product\":\"9897\",\"version\":\"001\",\"response\":{\"success\":true,\"message\":\"\"}}]"
               }
           ]
       }
    ]
}

Pontos de Entrada PLOPCPJ e PLOPCPF

Foram desenvolvidos dois pontos de entrada que permitem definir regras para determinar se um opcional deve ou não ser gravado, em complemento ao parâmetro MV_PLCAROP.

Funcionamento Geral

• Ambos os pontos de entrada retornam a mesma estrutura.
• A diferença entre eles está no tipo de beneficiário:

• PLOPCPJ → executado quando o beneficiário é Pessoa Jurídica (PJ).
• PLOPCPF → executado quando o beneficiário é Pessoa Física (PF).

Esses pontos podem conter a mesma regra ou regras distintas, mas o objetivo final é sempre o mesmo: permitir ou não a gravação do opcional em processamento.

Execução dos pontos de entrada

• Tanto o PLOPCPJ quanto o PLOPCPF são executados no momento da gravação dos opcionais.
• O retorno do ponto de entrada define se o opcional em processamento deve ou não ser gravado, de acordo com a regra implementada.

Exemplo de Execução

Se houver previsão de gravação de dois opcionais, por exemplo 0001 e 0002:

1. Antes de gravar o opcional 0001, o ponto de entrada é executado.
2. Em seguida, antes de gravar o opcional 0002, o ponto de entrada é executado novamente.

Ou seja, o processo é repetido para cada opcional individualmente.

Estrutura de Entrada

Os pontos de entrada recebem como parâmetro (PARAMIXB) um objeto JSON com os seguintes atributos:

O retorno deve ser um objeto JSON com a seguinte estrutura:

#Include 'Totvs.ch'   

User Function PLOPCPF()
	
	Local oJRet := JsonObject():new()
	
	If paramixm["beneficiaryRegistration"] == "00010001000153004" .AND. ;
	   paramixm["entityType "]	           == "F"                 .AND. ;    
	   paramixm["optionalCode"]	           == "1234"              .AND. ;    
	   paramixm["optionalVersion"]	       == "001" 

		oJRet["success"] := .F.
		oJRet["message"] := "Beneficiário sem opcional"
	Else
		oJRet["success"] := .T.
		oJRet["message"] := ""
	EndIf
	
Return oJRet

04. DEMAIS INFORMAÇÕES

Alteração de dicionário SX3 (X3_VALID):

05. ASSUNTOS RELACIONADOS

Para informações detalhadas sobre o funcionamento do endpoint, consulte a documentação oficial disponível no link abaixo:

API PLIncAutoBenModel - Protocolo de Inclusão de Beneficiários Aprovado Automaticamente