Histórico da Página
...
- Visão Geral
- Exemplo de utilização
- Títulos de Cobrança
- Composição do Título
- PDF do Título
- Tabela de Código de Erros
- Tela Títulos de Cobrança do Beneficiário
- Outras Ações / Ações relacionadas
- Outras Ações / Ações relacionadas
- Tela Títulos de Cobrança do Beneficiário
- 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 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
...
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:
|
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
| ||
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:
| |
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:
|
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 |
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{ "items": [ { "e1_prefixo": "PLS", "e1_num": "000007042000007023", "e1_parcela": "", "e1_tipo": "DPNCC", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "20222021-101-1725", "e1_valor": 419200.01, "e1_baixa": "20222021-101-1722", "e1_saldo": 0, "e1_valliq": 419200.01, "status": "B", "latedays": 0, "titleid": "PLS000007042PLS000007023 DPNCC" }, { "e1_prefixo": "PLS", "e1_num": "000007043000007037", "e1_parcela": "", "e1_tipo": "DPNCC", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "2022-101-1725", "e1_valor": 39950, "e1_baixa": "2022-101-1719", "e1_saldo": 2000, "e1_valliq": 19950, "status": "B", "Platedays": 0, "titleid": "PLS000007043PLS000007037 DPNCC" }, { "e1_prefixo": "PLS", "e1_num": "000007044000007038", "e1_parcela": "", "e1_tipo": "DP", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "2022-102-1725", "e1_valor": 399590, "e1_baixa": "2022-1-19", "e1_saldo": 3990, "e1_valliq": 0590, "status": "A"B", "latedays": 0, "titleid": "PLS000007044PLS000007038 DP" }, { "e1_prefixo": "PLS", "e1_num": "000007045000007038", "e1_parcela": "", "e1_tipo": "DPNCC", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "2022-102-1725", "e1_valor": 39950, "e1_baixa": "2022-101-1719", "e1_saldo": 0, "e1_valliq": 39950, "status": "B", "titleidlatedays": "PLS000007045 DP"0, }, "titleid": "PLS000007038 NCC" }, { "e1_prefixo": "PLS", "e1_num": "000007046000007039", "e1_parcela": "", "e1_tipo": "DP", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "2022-103-1725", "e1_valor": 399590, "e1_baixa": "2022-10-17", "e1_saldo": 309590, "e1_valliq": 900, "status": "P""A", "latedays": 343, "titleid": "PLS000007046PLS000007039 DP" }, { "e1_prefixo": "PLS", "e1_num": "000007047000007039", "e1_parcela": "", "e1_tipo": "DPNCC", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "2022-103-1725", "e1_valor": 47550, "e1_baixa": "2022-111-1619", "e1_saldo": 172.540, "e1_valliq": 252.4650, "status": "PB", "titleidlatedays": "PLS000007047 DP"0, "titleid": "PLS000007039 NCC" }, { "e1_prefixo": "PLS", "e1_num": "000007048000007042", "e1_parcela": "", "e1_tipo": "DP", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "2022-10-17", "e1_valor": 475419, "e1_baixa": "2022-10-17", "e1_saldo": 0, "e1_valliq": 475419, "status": "B", "latedays": 0, "titleid": "PLS000007048PLS000007042 DP" }, { "e1_prefixo": "PLS", "e1_num": "000007049000007044", "e1_parcela": "", "e1_tipo": "DP", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "2022-10-17", "e1_valor": 475399, "e1_baixa": "2022-11-12", "e1_saldo": 265399, "e1_valliq": 2000, "status": "PA", "latedays": 137, "titleid": "PLS000007049PLS000007044 DP" }, { "e1_prefixo": "PLS", "e1_num": "000007050000007045", "e1_parcela": "", "e1_tipo": "DP", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "2022-10-2417", "e1_valor": 475399, "e1_baixa": "2022-10-17", "e1_saldo": 4750, "e1_valliq": 0399, "status": "AB", "latedays": 0, "titleid": "PLS000007050PLS000007045 DP" }, { "e1_prefixo": "PLS", "e1_num": "000007051000007047", "e1_parcela": "", "e1_tipo": "DP", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "2022-10-2417", "e1_valor": 475, "e1_baixa": "2022-10-17", "e1_saldo": 0475, "e1_valliq": 4750, "status": "BA", "latedays": 137, "titleid": "PLS000007051PLS000007047 DP" }, { "e1_prefixo": "PLS", "e1_num": "000007052000007048", "e1_parcela": "", "e1_tipo": "DP", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "2022-1110-2317", "e1_valor": 475, "e1_baixa": "2022-1110-1217", "e1_saldo": 850, "e1_valliq": 200475, "status": "P"B", "latedays": 0, "titleid": "PLS000007052PLS000007048 DP" }, { "e1_prefixo": "PLS", "e1_num": "000007053000007050", "e1_parcela": "", "e1_tipo": "DP", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "2022-1210-2324", "e1_valor": 475, "e1_baixa": "", "e1_saldo": 475, "e1_valliq": 0, "status": "A", "titleidlatedays": "PLS000007053130, "titleid": "PLS000007050 DP" }, { "e1_prefixo": "UNIPLS", "e1_num": "TFC01B000007051", "e1_parcela": "", "e1_tipo": "NFDP", "e1_cliente": "TMSWBI", "e1_loja": "01", "e1_nomcli": "VITOR MIGUEL FREITAS", "e1_vencrea": "20232022-110-2324", "e1_valor": 475, "e1_baixa": "2022-10-17", "e1_saldo": 4750, "e1_valliq": 0475, "status": "AB", "titleidlatedays": "UNITFC01B NF"0, } ], "hasNexttitleid": false, "remainingRecords": 0, "struct": ["PLS000007051 DP" }, { "fielde1_prefixo": "E1_PREFIXOPLS", "typee1_num": "C242536471", "titlee1_parcela": "Prefixo", "descriptione1_tipo": "Prefixo do tituloDP", "picturee1_cliente": "@!TMSWBI", "sizee1_loja": 3"01", "decimalse1_nomcli": 0"VITOR MIGUEL FREITAS", "cboxe1_vencrea": []"2022-11-24", }, {"e1_valor": 200, "fielde1_baixa": "E1_NUM", "typee1_saldo": "C"200, "titlee1_valliq": "No. Titulo"0, "descriptionstatus": "Numero do TituloA", "picturelatedays": "@!"99, "sizetitleid": 9, "decimals": 0, "cbox": []"PLS242536471 DP" }, { "fielde1_prefixo": "E1_PARCELAPLS", "typee1_num": "C365890285", "titlee1_parcela": "Parcela", "descriptione1_tipo": "Parcela do TituloDP", "picturee1_cliente": "@!TMSWBI", "sizee1_loja": 1"01", "decimalse1_nomcli": 0 "VITOR MIGUEL FREITAS", "cboxe1_vencrea": []"2022-12-12", }, {"e1_valor": 300, "fielde1_baixa": "E1_TIPO", "typee1_saldo": "C"300, "titlee1_valliq": "Tipo"0, "descriptionstatus": "Tipo do titulo"A", "picturelatedays": "@!"81, "sizetitleid": 3, "decimals": 0, "cbox": []PLS365890285 DP" }, { "fielde1_prefixo": "E1_CLIENTEPLS", "typee1_num": "C000007053", "titlee1_parcela": "Cliente", "descriptione1_tipo": "Codigo do ClienteDP", "picturee1_cliente": "@!TMSWBI", "sizee1_loja": 6"01", "decimalse1_nomcli": 0"VITOR MIGUEL FREITAS", "cboxe1_vencrea": []"2022-12-23", }, {"e1_valor": 475, "fielde1_baixa": "E1_LOJA", "typee1_saldo": "C"475, "titlee1_valliq": "Loja"0, "descriptionstatus": "Loja do ClienteA", "picturelatedays": "@!"70, "sizetitleid": 2,"PLS000007053 DP" } ], "decimalshasNext": 0false, "remainingRecords": 0, "cboxstruct": [] }, { "field": "E1_NOMCLIPREFIXO", "type": "C", "title": "Nome ClientePrefixo", "description": "Nome ReduzidoPrefixo do Clientetitulo", "picture": "@!", "size": 203, "decimals": 0, "cbox": [] }, { "field": "E1_VENCREANUM", "type": "DC", "title": "VenctoNo. realTitulo", "description": "VencimentoNumero real do Titulo", "picture": "@!", "size": 89, "decimals": 0, "cbox": [] }, { "field": "E1_VALORPARCELA", "type": "NC", "title": "Vlr.TituloParcela", "description": "ValorParcela do Titulo", "picture": "@E 9,999,999,999,999.99@!", "size": 161, "decimals": 20, "cbox": [] }, { "field": "E1_BAIXATIPO", "type": "DC", "title": "DT BaixaTipo", "description": "Data de BaixaTipo do Titulotitulo", "picture": "@!", "size": 83, "decimals": 0, "cbox": [] }, { "field": "E1_SALDOCLIENTE", "type": "NC", "title": "SaldoCliente", "description": "SaldoCodigo ado ReceberCliente", "picture": "@E 9,999,999,999,999.99@!", "size": 166, "decimals": 20, "cbox": [] }, { "field": "E1_VALLIQLOJA", "type": "NC", "title": "Vlr.Liq BaixLoja", "description": "ValorLoja Liquidodo da BaixaCliente", "picture": "@E 9,999,999,999,999.99@!", "size": 162, "decimals": 20, "cbox": [] }, { "field": "E1_NOMCLI", ] "type": "C", "totalValuestitle": 5815 } |
Dados Inválidos (404)
...
code
...
...
message
...
...
detailedMessage
...
...
"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. |
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"code": "E001",
"message": "Beneficiário não encontrado.",
"detailedMessage": "Não foi encontrado nenhum beneficiário com a matricula 00011008000026010"
} |
Informações | ||
---|---|---|
| ||
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 |
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"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. |
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"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 |
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"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. |
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"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. |
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"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
...
04. TELA TÍTULOS DE COBRANÇA DO BENEFICIÁRIO
Principais Campos e Parâmetros
Campo | Descrição | |
---|---|---|
MV_PLSEXTP | MV_PLTITAB | MV_PLTITBX |
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