API beneficiaryPosition - Endpoint: Títulos de Cobrança do Beneficiário (Posição Financeira)

CONTEÚDO

Visão Geral
Exemplo de utilização
1. Títulos de Cobrança
2. Composição do Título
3. PDF do Título
4. Tabela de Código de Erros
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 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

Títulos de Cobrança

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

Endpoint

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

Parâmetros

Authorization (header)	Cabeçalho usado para autorização das requisições	*required
Content-Type (header)	'application/json' é o formato do conteúdo	*required
SubscriberId (path)	Número da carteirinha do beneficiário	*required
status (query)	Filtro dos títulos pelo status, sendo: A = Títulos em aberto P = Títulos com baixa parcial B = Títulos baixados Caso o status não seja informado, será retornado todos os status.
allTitles (query)	Demais Títulos, inclusive títulos que não são de origem SIGAPLS 0 = Não (Default) 1 = Sim
initialDate (query)	Data inicial dos títulos: 'AAAA-MM-DD'
finalDate (query)	Data final dos títulos: 'AAAA-MM-DD'
page (query)	Paginação da Coleção
pageSize (query)	Quantidade de Itens por Página
order (query)	Ordenação da Coleção
fields (query)	Filtro de campos dos registros
filter (query)	Indica o filtro querystring recebido (pode se utilizar um filtro oData)

Request

Não possui body!

Operação realizada com sucesso (200)

items		Títulos de Cobrança do beneficiário
items.{campo do SX3}		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		Status do título, sendo: Aberto (A), Baixado Parcial (P), Baixado (B) Campo: E1_SALDO e E1_VALOR
items.titleid		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
items.latedays		Quantidade de dias em atraso do título, considerando a data de vencimento (E1_VENCREA)
totalValues		Valor total de todos os títulos encontrado Campo: E1_VALOR
struct		Estrutura dos fields de acordo com o dicionário de dados (SX3)
hasNext		Indica se ainda existem registros a serem retornados
remainingRecords		Quantidade de registros ainda existem para retorno

Exemplo de retorno - Sucesso

{
  "items": [
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007023",
      "e1_parcela": "",
      "e1_tipo": "NCC",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2021-1-25",
      "e1_valor": 200.01,
      "e1_baixa": "2021-1-22",
      "e1_saldo": 0,
      "e1_valliq": 200.01,
      "status": "B",
      "latedays": 0,
      "titleid": "PLS000007023 NCC"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007037",
      "e1_parcela": "",
      "e1_tipo": "NCC",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-1-25",
      "e1_valor": 50,
      "e1_baixa": "2022-1-19",
      "e1_saldo": 0,
      "e1_valliq": 50,
      "status": "B",
      "latedays": 0,
      "titleid": "PLS000007037 NCC"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007038",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-2-25",
      "e1_valor": 590,
      "e1_baixa": "2022-1-19",
      "e1_saldo": 0,
      "e1_valliq": 590,
      "status": "B",
      "latedays": 0,
      "titleid": "PLS000007038 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007038",
      "e1_parcela": "",
      "e1_tipo": "NCC",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-2-25",
      "e1_valor": 50,
      "e1_baixa": "2022-1-19",
      "e1_saldo": 0,
      "e1_valliq": 50,
      "status": "B",
      "latedays": 0,
      "titleid": "PLS000007038 NCC"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007039",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-3-25",
      "e1_valor": 590,
      "e1_baixa": "",
      "e1_saldo": 590,
      "e1_valliq": 0,
      "status": "A",
      "latedays": 343,
      "titleid": "PLS000007039 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "000007039",
      "e1_parcela": "",
      "e1_tipo": "NCC",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-3-25",
      "e1_valor": 50,
      "e1_baixa": "2022-1-19",
      "e1_saldo": 0,
      "e1_valliq": 50,
      "status": "B",
      "latedays": 0,
      "titleid": "PLS000007039 NCC"
    },
    {
      "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",
      "latedays": 0,
      "titleid": "PLS000007042 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",
      "latedays": 137,
      "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",
      "latedays": 0,
      "titleid": "PLS000007045 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": "",
      "e1_saldo": 475,
      "e1_valliq": 0,
      "status": "A",
      "latedays": 137,
      "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",
      "latedays": 0,
      "titleid": "PLS000007048 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",
      "latedays": 130,
      "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",
      "latedays": 0,
      "titleid": "PLS000007051 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "242536471",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-11-24",
      "e1_valor": 200,
      "e1_baixa": "",
      "e1_saldo": 200,
      "e1_valliq": 0,
      "status": "A",
      "latedays": 99,
      "titleid": "PLS242536471 DP"
    },
    {
      "e1_prefixo": "PLS",
      "e1_num": "365890285",
      "e1_parcela": "",
      "e1_tipo": "DP",
      "e1_cliente": "TMSWBI",
      "e1_loja": "01",
      "e1_nomcli": "VITOR MIGUEL FREITAS",
      "e1_vencrea": "2022-12-12",
      "e1_valor": 300,
      "e1_baixa": "",
      "e1_saldo": 300,
      "e1_valliq": 0,
      "status": "A",
      "latedays": 81,
      "titleid": "PLS365890285 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",
      "latedays": 70,
      "titleid": "PLS000007053 DP"
    }
  ],
  "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": 5622.01
}

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

Pontos de Entrada

A rotina antiga da Posição do Beneficiário possuía alguns pontos de entrada para customizar a busca dos títulos e ordenação, portanto foi criado os seguintes pontos de entrada:

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

Parâmetros

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

Request

Não possui body!

Operação realizada com sucesso (200)

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

Exemplo de retorno - Sucesso

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

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

Parâmetros

Authorization (header)

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

*required

Content-Type (header)

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

*required

titleId (path)

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

Número do título

Campo: E1_NUM

base64

PDF do título no formato base 64

Exemplo de retorno - Sucesso

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

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": "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	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}	404
E003	Não permitido a geração do PDF	Não é permitido gerar o pdf para o status atual do título {titleId}	400
E004	Título não encontrado.	Não foi encontrado no contas a receber (Financeiro) o título {titleId}	404
E005	Cliente financeiro sem cobrança.	Não foi encontrado nenhuma cobrança para o cliente financeiro do beneficiário de matricula {subscriberId}	400

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

Campo	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 de títulos que não tem origem do PLS que devem ser exibidos (query param allTitles igual a 1)
MV_PLTITAB	Tipos de títulos que devem ser ocultados no filtro do query param 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 query param status B (Títulos baixados)
MV_PLCPSE1	Campos do Financeiro (Contas a Receber - SE1), que serão apresentados na tela de posição financeiro. Por padrão o sistema sempre irá mostrar os seguintes campos: E1_CLIENTE,E1_LOJA,E1_NOMCLI,E1_VENCREA,E1_PREFIXO,E1_NUM,E1_PARCELA,E1_TIPO,E1_VALOR,E1_SALDO,E1_VALLIQ,E1_BAIXA

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

API beneficiaryPosition - Endpoint: Títulos de Cobrança do Beneficiário (Posição Financeira)

CONTEÚDO

01. VISÃO GERAL

02. EXEMPLO DE UTILIZAÇÃO

Títulos de Cobrança

Endpoint

Parâmetros

Request

Operação realizada com sucesso (200)

Mensagens de Erros

Endpoint

Parâmetros

Request

Operação realizada com sucesso (200)

Mensagens de Erros

PDF do Título

Endpoint

Parâmetros

Request

Operação realizada com sucesso (200)

Mensagens de Erros

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