Histórico da Página
...
- Visão Geral
- Exemplo de utilização
- Valor de Cobrança
- Tabela de Códigos de Erros
- Tela Valor de Cobrança
- Outras Ações / Ações relacionadas
- Outras Ações / Ações relacionadas
- Tela Valor de Cobrança
- Principais Campos e Parâmetros
- 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) |
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)
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 |
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"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 | ||||||||||
| ||||||||||
{ "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 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{ "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 | ||||||||||
| ||||||||||
{ "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 | 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. |
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{ "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}
Não permitido a geração do PDF
Não é permitido gerar o pdf para o status atual do título {titleId}
Título não encontrado.
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
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 | Descrição
05. TABELAS UTILIZADAS
- BA1 - Beneficiários
- BM1 - Composição da Cobrança
- SE1 - Títulos no Contas a Receber
- BA3 - Famílias