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