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