Histórico da Página

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 posiçã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
billingType (query)	Tipo de cobrança a ser retornada, sendo: 1 = Cobrança a Faturar 2 = Cobrança já Faturado	*required
fields (query)	Filtro de campos dos registros

Request

Não possui body!

Operação realizada com sucesso (200)

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

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": "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"
    }
  ]
}

Bloco de código

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

{
  "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": []
}

Dados Inválidos (404)

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

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

{
  "code": "E003",
  "message": "Sem Cobrança a Faturar",
  "detailedMessage": "Não existe nenhuma cobrança a ser faturado para o mês e ano informado."
}

Tabela de Código de Erros

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

Code	message	detailedMessage
E001	Beneficiário não encontrado.	Não foi encontrado nenhum Beneficiário com a matricula {subscriberId}
E002	Parâmetros obrigatórios	Obrigatório informar o ano base, mês base e tipo da cobrança
E003	Sem Cobrança a Faturar	Não existe nenhuma cobrança a ser faturado para o mês e ano informado.
E004	Nenhuma Cobrança já Faturada	Não existe nenhuma cobrança já faturada para o mês e ano informado.
E005	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.

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

Versões comparadas

Versão antiga 3

Nova versão 4

Chave

CONTEÚDO

01. VISÃO GERAL

02. EXEMPLO DE UTILIZAÇÃO

Valor de Cobrança

Endpoint

Parâmetros

Request

Operação realizada com sucesso (200)

Dados Inválidos (404)

Tabela de Código de Erros

03. TELA VALOR DE COBRANÇA

04. TELA VALOR DE COBRANÇA

05. TABELAS UTILIZADAS