Histórico da Página

...

Visão Geral
Exemplo de utilização
1. Títulos de Cobrança
2. Composição do Título
3. PDF do Título
Tela Títulos de Cobrança do Beneficiário
1. Outras Ações / Ações relacionadas
Tela Títulos de Cobrança do Beneficiário
1. Principais Campos e Parâmetros
Tabelas utilizadas

01. VISÃO GERAL

Este documento tem como objetivo demonstrar a utilização dos endpoints de títulos de cobrança do beneficiário, que faz parte da api beneficiaryPosition do Produto TOTVS Saúde Planos Linha Protheus (totvsHealthPlans).

/totvsHealthPlans/v1/beneficiaryPosition/{subscriberId}/titles
/totvsHealthPlans/v1/beneficiaryPosition/titles/{titleId}/compositions
/totvsHealthPlans/v1/beneficiaryPosition/titles/{titleId}/pdf

Esses endpoints são utilizados 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

...

Retorna o histórico de títulos de cobrança do beneficiário.

Endpoint

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

Image Modified

Parâmetros

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
SubscriberId (path)	Image Modified	Número da carteirinha do beneficiário	*required
status (query)	Image Modified	Filtro dos títulos pelo status, sendo: A = Títulos em aberto P = Títulos com baixa parcial B = Títulos baixados D = Demais Títulos, todos os status, inclusive títulos que não são de origem SIGAPLS
initialDate (query)	Image Modified

data

Data inicial dos títulos: 'AAAA-MM-DD'
finalDate (query)	Image Modified

data

Data final dos títulos: 'AAAA-MM-DD'
page (query)	Image Modified	Paginação da Coleção
pageSize (query)	Image Modified	Quantidade de Itens por Página
order (query)	Image Modified	Ordenação da Coleção
fields (query)	Image Modified	Filtro de campos dos registros
filter (query)	Image Modified	Indica o filtro querystring recebido (pode se utilizar um filtro oData)

...

Request

Não possui body!

...

Operação realizada com sucesso (200)

items	Image Modified	Títulos de Cobrança do beneficiário
items.{campo do SX3}	Image Modified	Os campos retornados da tabela SE1: e1_prefixo e1_num e1_parcela e1_tipo e1_cliente e1_loja e1_nomcli e1_vencrea e1_valor e1_baixa e1_saldo e1_valliq
items.status	Image Modified	Status do título, sendo: Aberto (A), Baixado Parcial (P), Baixado (B) Campo: E1_SALDO e E1_VALOR
items.titleid	Image Modified	Chave identificador do título para ser utilizado nos endpoints: /totvsHealthPlans/v1/beneficiaryPosition/titles/{titleId}/compositions /totvsHealthPlans/v1/beneficiaryPosition/titles/{titleId}/pdf Campo: E1_PREFIXO+E1_NUM+E1_PARCELA+E1_TIPO
totalValues	Image Modified	Valor total de todos os títulos encontrado Campo: E1_VALOR
struct	Image Modified	Estrutura dos fields de acordo com o dicionário de dados (SX3)
hasNext	Image Modified	Indica se ainda existem registros a serem retornados
remainingRecords	Image Modified	Quantidade de registros ainda existem para retorno

Bloco de código

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

{
  "items": [
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007042",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-10-17",
      "e1_valor": 419,
      "e1_baixa": "2022-10-17",
      "e1_saldo": 0,
      "e1_valliq": 419,
      "status": "B",
      "titleid": "PLS000007042 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007043",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-10-17",
      "e1_valor": 399,
      "e1_baixa": "2022-10-17",
      "e1_saldo": 200,
      "e1_valliq": 199,
      "status": "P",
      "titleid": "PLS000007043 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007044",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-10-17",
      "e1_valor": 399,
      "e1_baixa": "",
      "e1_saldo": 399,
      "e1_valliq": 0,
      "status": "A",
      "titleid": "PLS000007044 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007045",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-10-17",
      "e1_valor": 399,
      "e1_baixa": "2022-10-17",
      "e1_saldo": 0,
      "e1_valliq": 399,
      "status": "B",
      "titleid": "PLS000007045 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007046",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-10-17",
      "e1_valor": 399,
      "e1_baixa": "2022-10-17",
      "e1_saldo": 309,
      "e1_valliq": 90,
      "status": "P",
      "titleid": "PLS000007046 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007047",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-10-17",
      "e1_valor": 475,
      "e1_baixa": "2022-11-16",
      "e1_saldo": 172.54,
      "e1_valliq": 252.46,
      "status": "P",
      "titleid": "PLS000007047 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007048",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-10-17",
      "e1_valor": 475,
      "e1_baixa": "2022-10-17",
      "e1_saldo": 0,
      "e1_valliq": 475,
      "status": "B",
      "titleid": "PLS000007048 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007049",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-10-17",
      "e1_valor": 475,
      "e1_baixa": "2022-11-12",
      "e1_saldo": 265,
      "e1_valliq": 200,
      "status": "P",
      "titleid": "PLS000007049 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007050",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-10-24",
      "e1_valor": 475,
      "e1_baixa": "",
      "e1_saldo": 475,
      "e1_valliq": 0,
      "status": "A",
      "titleid": "PLS000007050 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007051",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-10-24",
      "e1_valor": 475,
      "e1_baixa": "2022-10-17",
      "e1_saldo": 0,
      "e1_valliq": 475,
      "status": "B",
      "titleid": "PLS000007051 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007052",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-11-23",
      "e1_valor": 475,
      "e1_baixa": "2022-11-12",
      "e1_saldo": 85,
      "e1_valliq": 200,
      "status": "P",
      "titleid": "PLS000007052 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007053",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-12-23",
      "e1_valor": 475,
      "e1_baixa": "",
      "e1_saldo": 475,
      "e1_valliq": 0,
      "status": "A",
      "titleid": "PLS000007053 DP"
    },
    {
      "e1_prefixo": "UNI",
      "e1_num": "TFC01B",
      "e1_parcela": "",
      "e1_tipo": "NF",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2023-1-23",
      "e1_valor": 475,
      "e1_baixa": "",
      "e1_saldo": 475,
      "e1_valliq": 0,
      "status": "A",
      "titleid": "UNITFC01B    NF"
    }
  ],
  "hasNext": false,
  "remainingRecords": 0,
  "struct": [
    {
      "field": "E1_PREFIXO",
      "type": "C",
      "title": "Prefixo",
      "description": "Prefixo do titulo",
      "picture": "@!",
      "size": 3,
      "decimals": 0,
      "cbox": []
    },
    {
      "field": "E1_NUM",
      "type": "C",
      "title": "No. Titulo",
      "description": "Numero do Titulo",
      "picture": "@!",
      "size": 9,
      "decimals": 0,
      "cbox": []
    },
    {
      "field": "E1_PARCELA",
      "type": "C",
      "title": "Parcela",
      "description": "Parcela do Titulo",
      "picture": "@!",
      "size": 1,
      "decimals": 0,
      "cbox": []
    },
    {
      "field": "E1_TIPO",
      "type": "C",
      "title": "Tipo",
      "description": "Tipo do titulo",
      "picture": "@!",
      "size": 3,
      "decimals": 0,
      "cbox": []
    },
    {
      "field": "E1_CLIENTE",
      "type": "C",
      "title": "Cliente",
      "description": "Codigo do Cliente",
      "picture": "@!",
      "size": 6,
      "decimals": 0,
      "cbox": []
    },
    {
      "field": "E1_LOJA",
      "type": "C",
      "title": "Loja",
      "description": "Loja do Cliente",
      "picture": "@!",
      "size": 2,
      "decimals": 0,
      "cbox": []
    },
    {
      "field": "E1_NOMCLI",
      "type": "C",
      "title": "Nome Cliente",
      "description": "Nome Reduzido do Cliente",
      "picture": "@!",
      "size": 20,
      "decimals": 0,
      "cbox": []
    },
    {
      "field": "E1_VENCREA",
      "type": "D",
      "title": "Vencto real",
      "description": "Vencimento real do Titulo",
      "picture": "",
      "size": 8,
      "decimals": 0,
      "cbox": []
    },
    {
      "field": "E1_VALOR",
      "type": "N",
      "title": "Vlr.Titulo",
      "description": "Valor do Titulo",
      "picture": "@E 9,999,999,999,999.99",
      "size": 16,
      "decimals": 2,
      "cbox": []
    },
    {
      "field": "E1_BAIXA",
      "type": "D",
      "title": "DT Baixa",
      "description": "Data de Baixa do Titulo",
      "picture": "",
      "size": 8,
      "decimals": 0,
      "cbox": []
    },
    {
      "field": "E1_SALDO",
      "type": "N",
      "title": "Saldo",
      "description": "Saldo a Receber",
      "picture": "@E 9,999,999,999,999.99",
      "size": 16,
      "decimals": 2,
      "cbox": []
    },
    {
      "field": "E1_VALLIQ",
      "type": "N",
      "title": "Vlr.Liq Baix",
      "description": "Valor Liquido da Baixa",
      "picture": "@E 9,999,999,999,999.99",
      "size": 16,
      "decimals": 2,
      "cbox": []
    }
  ],
  "totalValues": 5815
}

...

Dados Inválidos (404)

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": "E001",
  "message": "Beneficiário não encontrado.",
  "detailedMessage": "Não foi encontrado nenhum beneficiário com a matricula 00011008000026010"
}

03. TELA TÍTULOS DE COBRANÇA DO BENEFICIÁRIO

Outras Ações / Ações relacionadas

...

Composição do Título

Retorna a composição do Título no PLS (Tabela BM1)

Endpoint

https://<url>:porta>/rest/totvsHealthPlans/v1/beneficiaryPosition/titles/{titleId}/compositions

Image Added

Parâmetros

Authorization (header)	Image Added	Cabeçalho usado para autorização das requisições	*required
Content-Type (header)	Image Added	'application/json' é o formato do conteúdo	*required
titleId (path)	Image Added	Chave identificador do título retornado no endpoint:/totvsHealthPlans/v1/beneficiaryPosition/{subscriberId}/titles Atributo: titleId	*required
fields (query)	Image Added	Filtro de campos dos registros

...

Request

Não possui body!

...

Operação realizada com sucesso (200)

collectionNumber	Image Added	Numero do lote de cobrança que o título foi gerado Campo: BM1_PLNUCO
month	Image Added	Mês de cobrança do título Campo: BM1_MES
year	Image Added	Ano de cobrança do título Campo: BM1_ANO
debts	Image Added	Valor total de débitos do título Campo: BM1_VALOR
credits	Image Added	Valor total de créditos do título Campo: BM1_VALOR
amount	Image Added	Valor total de crédito e débito Campo: BM1_VALOR
amountType	Image Added	Tipo do valor total, sendo Débito ou Crédito.
beneficiaries	Image Added	Beneficiários vinculados ao título
beneficiaries.subscriberId	Image Added	Carteirinha do beneficiário Campo: BM1_MATUSU
beneficiaries.name	Image Added	Nome do beneficiário Campo: BM1_NOMUSR
beneficiaries.compositions	Image Added	Composição do título do beneficiário
beneficiaries.compositions.typeCode	Image Added	Código do lançamento do faturamento Campo: BM1_CODTIP
beneficiaries.compositions.typeDescription	Image Added	Descrição do lançamento do faturamento Campo: BM1_DESTIP
beneficiaries.compositions.type	Image Added	Tipo do lançamento, sendo Débito ou Crédito. Campo: BM1_TIPO
beneficiaries.compositions.value	Image Added	Valor da composição do lançamento Campo: BM1_VALOR

Bloco de código

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

{
  "collectionNumber": "00000232",
  "month": "01",
  "year": "2022",
  "debts": 419,
  "credits": 0,
  "amount": 419,
  "amountType": "Débito",
  "beneficiaries": [
    {
      "subscriberId": "00011008000027010",
      "name": "HERNANDES ALVES DA SILVA",
      "compositions": [
        {
          "typeCode": "101",
          "typeDescription": "Produto/Plano (Mensalidade)",
          "type": "Débito",
          "value": 120
        },
        {
          "typeCode": "103",
          "typeDescription": "Taxa Inscricao/Adesao",
          "type": "Débito",
          "value": 10
        }
      ]
    },
    {
      "subscriberId": "00011008000027028",
      "name": "FABIANA SOPHIA MELO",
      "compositions": [
        {
          "typeCode": "101",
          "typeDescription": "Produto/Plano (Mensalidade)",
          "type": "Débito",
          "value": 279
        },
        {
          "typeCode": "103",
          "typeDescription": "Taxa Inscricao/Adesao",
          "type": "Débito",
          "value": 10
        }
      ]
    }
  ]
}

...

Dados Inválidos (404)

code	Image Added	Código identificador do erro. (Tabela de Erros)
message	Image Added	Literal no idioma da requisição descrevendo o erro para o usuário.
detailedMessage	Image Added	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": "E002",
  "message": "Composição do título não encontrado.",
  "detailedMessage": "Não foi encontrado nenhuma composição para o título PLS000007022 DP"
}

PDF do Título

Retorna o pdf do boleto do título em base 64

Endpoint

https://<url>:porta>/rest/totvsHealthPlans/v1/beneficiaryPosition/titles/{titleId}/pdf

Image Added

Parâmetros

Authorization (header)

Image Added

Cabeçalho usado para autorização das requisições

*required

Content-Type (header)

Image Added

'application/json' é o formato do conteúdo

*required

titleId (path)

Image Added

Chave identificador do título retornado no endpoint:/totvsHealthPlans/v1/beneficiaryPosition/{subscriberId}/titles

Atributo: titleId

*required

...

Request

Não possui body!

...

Operação realizada com sucesso (200)

documentNumber

Image Added

Número do título

Campo: E1_NUM

base64

Image Added

PDF do título no formato base 64

Bloco de código

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

{
"documentNumber": "000007042",
"base64": "JVBERi0xLjMKJbe+raoKMSAwIG9iago8PAovVHlw..."
}

...

Dados Inválidos (404)

code	Image Added	Código identificador do erro. (Tabela de Erros)
message	Image Added	Literal no idioma da requisição descrevendo o erro para o usuário.
detailedMessage	Image Added	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": "E004",
  "message": "Título não encontrado.",
  "detailedMessage": "Não foi encontrado no contas a receber (Financeiro) o título PLS000007022 DP"
}

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	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}

03. TELA TÍTULOS DE COBRANÇA DO BENEFICIÁRIO

Outras Ações / Ações relacionadas

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

04. TELA TÍTULOS DE COBRANÇA DO BENEFICIÁRIO

Principais Campos e Parâmetros

CampoDescrição	Descrição
BA1_CODINT, BA1_CODEMP, BA1_MATRIC, BA1_TIPREG, BA1_DIGITO	Carteirinha do beneficiário
E1_PREFIXO, E1_NUM, E1_PARCELA, E1_TIPO	Chave identificar do título (titleId)
MV_PLSEXTP	Tipos cujos títulos devem ser exibidos no filtro do status D (Demais Títulos)
MV_PLTITAB	Tipos de títulos que devem ser ocultados no filtro do status A (Títulos em Abertos) e P (Títulos baixados parcialmente)
MV_PLTITBX	Tipos de títulos que devem ser ocultados no filtro do status B (Títulos baixados)

05. TABELAS UTILIZADAS

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

Árvore de páginas

Versões comparadas

Versão antiga 1

Nova versão 2

Chave

01. VISÃO GERAL

02. EXEMPLO DE UTILIZAÇÃO

Endpoint

Parâmetros

Request

Operação realizada com sucesso (200)

Dados Inválidos (404)

03. TELA TÍTULOS DE COBRANÇA DO BENEFICIÁRIO

Composição do Título

Endpoint

Parâmetros

Request

Operação realizada com sucesso (200)

Dados Inválidos (404)

PDF do Título

Endpoint

Parâmetros

Request

Operação realizada com sucesso (200)

Dados Inválidos (404)

Tabela de Código de Erros

03. TELA TÍTULOS DE COBRANÇA DO BENEFICIÁRIO

04. TELA TÍTULOS DE COBRANÇA DO BENEFICIÁRIO

05. TABELAS UTILIZADAS