API beneficiaryPosition - Endpoint: Valor de Cobrança

CONTEÚDO

Visão Geral
Exemplo de utilização
1. Valor de Cobrança
2. Tabela de Códigos de Erros
Tela Valor de Cobrança
1. Outras Ações / Ações relacionadas
Tela Valor de Cobrança
1. Principais Campos e Parâmetros
Tabelas utilizadas

01. VISÃO GERAL

Este documento tem como objetivo demonstrar a utilização do endpoint de valor de cobrança do beneficiários, que faz parte da api beneficiaryPosition do Produto TOTVS Saúde Planos Linha Protheus (totvsHealthPlans).

/totvsHealthPlans/v1/beneficiaryPosition/{subscriberId}/billing

Esse endpoint será utilizado na nova tela de Gestão do Beneficiário, desenvolvida em PO UI. (Biblioteca de componentes baseado em Angular)

Clique aqui para detalhes sobre como habilitar o serviço de APIs

02. EXEMPLO DE UTILIZAÇÃO

Valor de Cobrança

Retorna a composição do valor de cobrança a ser faturado ou já faturado da família do beneficiário.

Endpoint

https://<url>:porta>/rest/totvsHealthPlans/v1/beneficiaryPosition/{subscriberId}/billing

Parâmetros

SubscriberId (path)	Número da carteirinha do beneficiário	*required
Authorization (header)	Cabeçalho usado para autorização das requisições	*required
Content-Type (header)	'application/json' é o formato do conteúdo	*required
baseMonth (query)	Mês base do valor de cobrança	*required
baseYear (query)	Ano base do valor de cobrança	*required
fields (query)	Filtro de campos dos registros

Request

Não possui body!

Operação realizada com sucesso (200)

baseMonth		Mês base da cobrança
baseYear		Ano base da cobrança
billsToBill		Cobrança à faturar
billsToBill.credits		Valor total de créditos para mês/ano informado
billsToBill.debts		Valor total de débitos para mês/ano informado
billsToBill.familyAmount		Valor total da família para mês/ano informado
billsToBill.employerCredits		Valor total de crédito patronal para mês/ano informado
billsToBill.employerDebts		Valor total de débito patronal para mês/ano informado
billsToBill.employerAmount		Valor total patronal para mês/ano informado
billsToBill.amount		Valor total da cobrança para mês/ano informado
billsToBill.amountType		Tipo do valor total da cobrança, sendo D (Débito) ou C (Crédito)
billsToBill.beneficiaries		Beneficiários da cobrança
billsToBill.beneficiaries.subscriberId		Carteirinha do Beneficiário Campo: BA1_CODINT+BA1_CODEMP+BA1_MATRIC+BA1_TIPREG+BA1_DIGITO
billsToBill.beneficiaries.name		Nome do beneficiário Campo: BA1_NOMUSR
billsToBill.beneficiaries.amount		Valor total do beneficiário na cobrança
billsToBill.beneficiaries.compositions		Composição do beneficiário
billsToBill.beneficiaries.compositions.typeCode		Código do tipo de lançamento de faturamento
billsToBill.beneficiaries.compositions.typeDescription		Descrição do lançamento de faturamento
billsToBill.beneficiaries.compositions.type		Tipo do lançamento, sendo Débito ou Crédito
billsToBill.beneficiaries.compositions.retroactive		Indica se o lançamento de faturamento é do tipo retroativo. (Sim ou Não) Os lançamentos retroativos são: 118 e 146
billsToBill.beneficiaries.compositions.value		Valor do lançamento na composição.
billsToBill.beneficiaries.compositions.observation		Observação do lançamento, podendo ser retornado a idade do beneficiário, cobrança pro-rata etc.
billsToBill.beneficiaries.compositions.product		Código do Produto da nota fiscal (SB1). Esse atributo será preenchido se o parâmetro MV_PLSNFBR estiver ativado (1).
billsToBill.beneficiaries.compositions.outputType		Tipo de saída da nota fiscal (TES). Esse atributo será preenchido se o parâmetro MV_PLSNFBR estiver ativado (1).
billsToBill.accumulated		Valores acumulados dos beneficiários
billsToBill.accumulated.type		Tipo do Lançamento
billsToBill.accumulated.balance1		Saldo 1
billsToBill.accumulated.balance2		Saldo 2
billsAlreadyBilled		Cobrança já faturada
billsAlreadyBilled.collectionNumber		Número do Lote de cobrança gerado
billsAlreadyBilled.title		Número do título de cobrança Campo: E1_PREFIXO+E1_NUM+E1_PARCELA+E1_TIPO
billsAlreadyBilled.credits		Valor total de créditos para mês/ano informado
billsAlreadyBilled.debts		Valor total de débitos para mês/ano informado
billsAlreadyBilled.employerCredits		Valor total de crédito patronal para mês/ano informado
billsAlreadyBilled.employerDebts		Valor total de débito patronal para mês/ano informado
billsAlreadyBilled.employerAmount		Valor total patronal para mês/ano informado Atributo retornado somente no tipo 1 = Cobrança a Faturar
billsAlreadyBilled.amount		Valor total da cobrança para mês/ano informado
billsAlreadyBilled.amountType		Tipo do valor total da cobrança, sendo D (Débito) ou C (Crédito)
billsAlreadyBilled.beneficiaries		Beneficiários da cobrança
billsAlreadyBilled.beneficiaries.subscriberId		Carteirinha do Beneficiário Campo: BA1_CODINT+BA1_CODEMP+BA1_MATRIC+BA1_TIPREG+BA1_DIGITO
billsAlreadyBilled.beneficiaries.name		Nome do beneficiário Campo: BA1_NOMUSR
billsAlreadyBilled.beneficiaries.amount		Valor total do beneficiário na cobrança
billsAlreadyBilled.beneficiaries.compositions		Composição do beneficiário
billsAlreadyBilled.beneficiaries.compositions.typeCode		Código do tipo de lançamento de faturamento
billsAlreadyBilled.beneficiaries.compositions.typeDescription		Descrição do lançamento de faturamento
billsAlreadyBilled.beneficiaries.compositions.type		Tipo do lançamento, sendo Débito ou Crédito
billsAlreadyBilled.beneficiaries.compositions.retroactive		Indica se o lançamento de faturamento é do tipo retroativo. (Sim ou Não) Os lançamentos retroativos são: 118 e 146
billsAlreadyBilled.beneficiaries.compositions.value		Valor do lançamento na composição.
billsAlreadyBilled.beneficiaries.compositions.observation		Observação do lançamento, podendo ser retornado a idade do beneficiário, cobrança pro-rata etc.
billsAlreadyBilled.beneficiaries.compositions.product		Código do Produto da nota fiscal (SB1). Esse atributo será preenchido se o parâmetro MV_PLSNFBR estiver ativado (1).
billsAlreadyBilled.beneficiaries.compositions.outputType		Tipo de saída da nota fiscal (TES). Esse atributo será preenchido se o parâmetro MV_PLSNFBR estiver ativado (1).
billsAlreadyBilled.accumulated		Valores acumulados dos beneficiários
billsAlreadyBilled.accumulated.type		Tipo do Lançamento
billsAlreadyBilled.accumulated.balance1		Saldo 1
billsAlreadyBilled.accumulated.balance2		Saldo 2

Exemplo de retorno - Sucesso (A Faturar)

{
   "baseMonth":"12",
   "baseYear":"2023",
   "billsToBill":{
      "credits":50,
      "debts":810,
      "familyAmount":760,
      "employerCredits":0,
      "employerDebts":0,
      "employerAmount":0,
      "amount":760,
      "amountType":"D",
      "beneficiaries":[
         {
            "subscriberId":"00011008000030010",
            "name":"NOAH CAIO BRITO",
            "amount":440,
            "compositions":[
               {
                  "typeCode":"101",
                  "typeDescription":"PRODUTO/PLANO (MENSALIDADE)",
                  "type":"Débito",
                  "retroactive":"Não",
                  "value":480,
                  "observation":"60",
                  "product":"000000000000000000000000000035",
                  "outputType":"501"
               },
               {
                  "typeCode":"103",
                  "typeDescription":"TAXA INSCRICAO/ADESAO",
                  "type":"Débito",
                  "retroactive":"Não",
                  "value":10,
                  "observation":"60",
                  "product":"000000000000000000000000000035",
                  "outputType":"501"
               },
               {
                  "typeCode":"130",
                  "typeDescription":"CREDITO SERV ACESSORIO",
                  "type":"Crédito",
                  "retroactive":"Não",
                  "value":50,
                  "observation":"",
                  "product":"000000000000000000000000000035",
                  "outputType":"501"
               }
            ]
         },
         {
            "subscriberId":"00011008000030029",
            "name":"CAUE MATEUS FILIPE PEREIRA",
            "amount":320,
            "compositions":[
               {
                  "typeCode":"101",
                  "typeDescription":"PRODUTO/PLANO (MENSALIDADE)",
                  "type":"Débito",
                  "retroactive":"Não",
                  "value":310,
                  "observation":"42",
                  "product":"000000000000000000000000000035",
                  "outputType":"501"
               },
               {
                  "typeCode":"103",
                  "typeDescription":"TAXA INSCRICAO/ADESAO",
                  "type":"Débito",
                  "retroactive":"Não",
                  "value":10,
                  "observation":"42",
                  "product":"000000000000000000000000000035",
                  "outputType":"501"
               }
            ]
         }
      ],
      "accumulated":[
         {
            "type":"[151] - Serv. Aux. (SADT) (CO-P.)",
            "balance1":"50.00",
            "balance2":"10.00"
         }
      ]
   },
   "billsAlreadyBilled":{
      "collectionNumber":"",
      "title":"",
      "credits":0,
      "debts":0,
      "employerCredits":0,
      "employerDebts":0,
      "amount":0,
      "amountType":"D",
      "beneficiaries":[
         
      ],
      "accumulated":[
         
      ]
   }
}

Exemplo de retorno - Sucesso (Já Faturado)

{
   "baseMonth":"12",
   "baseYear":"2022",
   "billsToBill":{
      "credits":0,
      "debts":0,
      "familyAmount":0,
      "employerCredits":0,
      "employerDebts":0,
      "employerAmount":0,
      "amount":0,
      "amountType":"D",
      "beneficiaries":[
         
      ],
      "accumulated":[
         
      ]
   },
   "billsAlreadyBilled":{
      "collectionNumber":"000100000232",
      "title":"PLS000007052 DP",
      "credits":0,
      "debts":475,
      "employerCredits":0,
      "employerDebts":0,
      "amount":475,
      "amountType":"D",
      "beneficiaries":[
         {
            "subscriberId":"00011008000027010",
            "name":"HERNANDES ALVES DA SILVA",
            "amount":196,
            "compositions":[
               {
                  "typeCode":"101",
                  "typeDescription":"PRODUTO/PLANO (MENSALIDADE)",
                  "type":"Débito",
                  "retroactive":"Não",
                  "value":196,
                  "observation":"21",
                  "product":"000000000000000000000000000035",
                  "outputType":"501"
               }
            ]
         },
         {
            "subscriberId":"00011008000027028",
            "name":"FABIANA SOPHIA MELO",
            "amount":279,
            "compositions":[
               {
                  "typeCode":"101",
                  "typeDescription":"PRODUTO/PLANO (MENSALIDADE)",
                  "type":"Débito",
                  "retroactive":"Não",
                  "value":279,
                  "observation":"35",
                  "product":"000000000000000000000000000035",
                  "outputType":"501"
               }
            ]
         }
      ],
      "accumulated":[
         
      ]
   }
}

Mensagens de Erros

code		Código identificador do erro. (Tabela de Erros)
message		Literal no idioma da requisição descrevendo o erro para o usuário.
detailedMessage		Mensagem técnica e mais detalhada do erro.

Exemplo de retorno - Falha

{
  "code": "E003",
  "message": "Falha ao processar a Cobrança",
  "detailedMessage": "Não foi possivel processar o valor de cobrança do beneficiário, verifique as configurações de faturamento da cobrança."
}

Tabela de Código de Erros

Código de erros informado no Json de retorno com falha:

Code	message	detailedMessage	Status Code
E001	Beneficiário não encontrado.	Não foi encontrado nenhum Beneficiário com a matricula {subscriberId}	404
E002	Parâmetros obrigatórios	Obrigatório informar o ano base e mês base	400
E003	Falha ao processar a Cobrança	Não foi possível processar o valor de cobrança do beneficiário, verifique as configurações de faturamento da cobrança.	400

03. TELA VALOR DE COBRANÇA

Outras Ações / Ações relacionadas

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

04. TELA VALOR DE COBRANÇA

Principais Campos e Parâmetros

Campo	Descrição
BA1_CODINT, BA1_CODEMP, BA1_MATRIC, BA1_TIPREG, BA1_DIGITO	Carteirinha do beneficiário
MV_PLSNFBR	Possibilita a geração de Nota Fiscal através da rotina de lote de cobrança. 0 = Desativar; 1=Ativar

05. TABELAS UTILIZADAS

BA1 - Beneficiários
BM1 - Composição da Cobrança
SE1 - Títulos no Contas a Receber
BA3 - Famílias

Árvore de páginas