Histórico da Página

...

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

Image Modified

Parâmetros

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

billingType *required

fields (query)

Image Modified

Tipo de cobrança a ser retornada, sendo:

1 = Cobrança a Faturar
2 = Cobrança já Faturado

Filtro de campos dos registros

...

Request

Não possui body!

...

Operação realizada com sucesso (200)

credits

baseMonth

Image Removed

Valor de cobrança do mês/ano informado do beneficiáriodebts

Image Removed

familyAmount

Image Removed

employerCredits

Image Removed

employerDebts

Image Removed

employerAmount

Image Removed

amount

Image Removed

amountType

Image Removed

beneficiaries

Image Removed

beneficiaries.subscriberId

Image Removed

beneficiaries.name

Image Removed

beneficiaries.amount

Image Removed

beneficiaries.compositions

Image Removed

beneficiaries.compositions.typeCode

Image Removed

beneficiaries.compositions.typeDescription

Image Removed

beneficiaries.compositions.type

Image Removed

beneficiaries.compositions.retroactive

Image Removed

beneficiaries.compositions.value

Image Removed

beneficiaries.compositions.observation

Image Removed

beneficiaries.compositions.product

Image Removed

beneficiaries.compositions.outputType

Image Removed

accumulated

Image Removed

accumulated.type

Image Removed

accumulated.balance1

Image Removed

accumulated.balance2

Image Removed

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

Bloco de código

language	c#
theme	Midnight
title	Exemplo de retorno - Sucesso (A Faturar)
linenumbers	true
collapse	true

{
   "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"
               },
               {

Bloco de código

language	c#
theme	Midnight
title	Exemplo de retorno - Sucesso (A Faturar)
linenumbers	true
collapse	true

{
  "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": "101103",
                  "typeDescription":"TAXA "PRODUTO/PLANO (MENSALIDADE)INSCRICAO/ADESAO",
                  "type": "Débito",
                  "retroactive": "Não",
                  "value": 48010,
                  "observation": "6042",
                  "product": "000000000000000000000000000035",
                  "outputType": "501"
               }
            },]
         {}
      ],
      "typeCodeaccumulated": "103",[
         {
            "typeDescriptiontype": "TAXA INSCRICAO/ADESAO"[151] - Serv. Aux. (SADT) (CO-P.)",
            "typebalance1": "Débito50.00",
            "retroactivebalance2": "Não10.00",
         }
 "value": 10,
    ]
   },
   "observationbillsAlreadyBilled": "60",
    {
      "productcollectionNumber": "000000000000000000000000000035",
          "outputTypetitle": "501",
        }"credits":0,
      "debts":0,
  {
    "employerCredits":0,
      "typeCodeemployerDebts": "130"0,
      "amount":0,
      "typeDescriptionamountType": "CREDITO SERV ACESSORIOD",
          "typebeneficiaries": "Crédito",[
          "retroactive": "Não",
 
      ],
      "valueaccumulated":[
 50,
        
  "observation": "",
   ]
   }
}

Bloco de código

language	c#
theme	Midnight
title	Exemplo de retorno - Sucesso (Já Faturado)
linenumbers	true
collapse	true

{
    "productbaseMonth": "00000000000000000000000000003512",
          "outputTypebaseYear": "501"
        }
      ]
    }2022",
    "billsToBill":{
      "subscriberIdcredits": "00011008000030029"0,
      "namedebts": "CAUE MATEUS FILIPE PEREIRA"0,
      "familyAmount":0,
      "amountemployerCredits": 3200,
      "compositionsemployerDebts": [0,
      "employerAmount":0,
  {
    "amount":0,
      "typeCodeamountType": "101D",
      "beneficiaries":[
     "typeDescription": "PRODUTO/PLANO (MENSALIDADE)",
    
      ],
      "typeaccumulated": "Débito",[
         
 "retroactive": "Não",
    ]
   },
   "valuebillsAlreadyBilled":{
  310,
    "collectionNumber":"000100000232",
      "observationtitle":"PLS000007052 "42DP",
          "productcredits": "000000000000000000000000000035"0,
          "outputTypedebts": "501"475,
        }"employerCredits":0,
      "employerDebts":0,
  {
    "amount":475,
      "typeCodeamountType": "103D",
      "beneficiaries":[
       "typeDescription": "TAXA INSCRICAO/ADESAO",
 {
            "typesubscriberId": "Débito00011008000027010",
            "retroactivename": "Não"HERNANDES ALVES DA SILVA",
            "valueamount": 10196,
            "observationcompositions": "42",
[
              "product": "000000000000000000000000000035",
 {
                  "outputTypetypeCode": "501101",
         }
      ]
    }
  ],
  "accumulated": [
"typeDescription":"PRODUTO/PLANO (MENSALIDADE)",
            {
      "type": "[151] - Serv. Aux. (SADT) (CO-P.)",
"Débito",
                  "balance1retroactive": "50.00Não",
        "balance2": "10.00"
    }
  ]
}

Bloco de código

language	c#
theme	Midnight
title	Exemplo de retorno - Sucesso (Já Faturado)
linenumbers	true
collapse	true

{
     "collectionNumbervalue": "000100000232"196,
        "title          "observation": "PLS000007052 DP21",
  "credits": 0,
  "debts": 475,
  "employerCredits": 0,
  "employerDebts": 0,
  "amount": 475,
    "amountTypeproduct": "D000000000000000000000000000035",
      "beneficiaries": [
      {
      "subscriberIdoutputType": "00011008000027010501",
           "name": "HERNANDES ALVES DA SILVA",}
      "amount": 196,      ]
      "compositions": [
   },
         {
            "typeCodesubscriberId": "10100011008000027028",
            "typeDescriptionname": "PRODUTO/PLANO (MENSALIDADE)"FABIANA SOPHIA MELO",
            "typeamount": "Débito"279,
            "retroactivecompositions": "Não",
[
               {
       "value": 196,
          "observationtypeCode": "21101",
          "product": "000000000000000000000000000035",
          "outputTypetypeDescription":"PRODUTO/PLANO (MENSALIDADE)"501",
        }
      ]
    }"type":"Débito",
     {
      "subscriberId": "00011008000027028",
      "nameretroactive": "FABIANA SOPHIA MELONão",
           "amount": 279,
      "compositionsvalue": [279,
        {
          "typeCodeobservation": "10135",
                  "typeDescriptionproduct": "PRODUTO/PLANO (MENSALIDADE)"000000000000000000000000000035",
          "type": "Débito",
           "retroactiveoutputType": "Não501",
              "value": 279,
 }
           "observation": "35", ]
         }
 "product": "000000000000000000000000000035",
    ],
      "outputTypeaccumulated": "501"
  [
      }
      ]
    }
  ],
  "accumulated": [] }
}

...

Mensagens de Erros

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

Bloco de código

language	c#
theme	Midnight
title	Exemplo de retorno - Falha
linenumbers	true
collapse	true

{
  "code": "E001E003",
  "message": "Beneficiário não encontrado.Falha ao processar a Cobrança",
  "detailedMessage": "Não foi encontrado nenhum beneficiário com a matricula 00011008000026010 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

Composição do título não encontrado.

Não foi encontrado nenhuma composição para o título {titleId}

E003

Não permitido a geração do PDF

Não é permitido gerar o pdf para o status atual do título {titleId}

E004

Título não encontrado.

Não foi encontrado no contas a receber (Financeiro) o título {titleId}

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

...

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

04. TELA VALOR DE COBRANÇA

Principais Campos e Parâmetros

04. TELA VALOR DE COBRANÇA

Principais Campos e Parâmetros

Descrição

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	Campo

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

Versões comparadas

Versão antiga 1

Nova versão Atual

Chave

01. VISÃO GERAL

02. EXEMPLO DE UTILIZAÇÃO

Valor de Cobrança

Endpoint

Parâmetros

Request

Operação realizada com sucesso (200)

Mensagens de Erros

Tabela de Código de Erros

03. TELA VALOR DE COBRANÇA

04. TELA VALOR DE COBRANÇA

04. TELA VALOR DE COBRANÇA

05. TABELAS UTILIZADAS