Histórico da Página
CONTEÚDO
- 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 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
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:
| ||
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": "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 } |
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 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{ "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 } ] } ] } |
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 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{ "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..." } |
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 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{ "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
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. |
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