Este documento tem como objetivo demonstrar a utilização da API Declarações para a integração do TOTVS Saúde Planos Linha Protheus com a Mobile Saúde, onde será disponibilizado ao beneficiário as declarações (Carta de Quitação e Declaração anual de Imposto de Renda) contendo relação de eventos (itens) e valores relacionados à declaração selecionada.
A API utilizará o padrão REST.
Segue os métodos utilizados na API:
Abaixo serão apresentados exemplos de cada método.
A autenticação é realizada através da Api /token, onde será retornado a chave e token a ser adicionado no header de cada método.
Este método irá retornar todas as declarações (Carta de Quitação e Declaração anual de Imposto de Renda) solicitadas pelo beneficiário.
A quantidade de anos que o sistema irá listar nas declarações deverá ser informado no campo Qt. Anos Dec (BA0_MSDECL) no cadastro da operadora.
Exemplo: caso seja informado o valor 3, o sistema irá listar as declarações dos últimos 3 anos.
No campo List. Decla. (BA0_MSDECD) no cadastro da operadora, deverá ser informado os tipos de declarações que serão utilizadas na API.
Url | Método | Header Content-Type | Descrição |
|---|---|---|---|
| https://<url>:<porta>/rest/mobileSaude/v1/listaDeclaracoes | POST | application/json | Retorna uma lista de declarações |
Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| chaveBeneficiario | Não | Caracter | Chave do Beneficiário (CPF ou Matricula) |
| chaveBeneficiarioTipo | Não | Caracter | Tipo de Login do Beneficiário (CPF ou Matricula) |
| multiContract | Não | Lógico | Utilização de Multi Contratos pelo Beneficiário |
| matriculaContrato | Sim | Caracter | Matricula do Beneficiário |
{
"chaveBeneficiarioTipo": "CPF",
"multiContract": false,
"chaveBeneficiario": "71461963990",
"matriculaContrato": "00011008000013019"
} |
{
"status": true,
"tipoDeclaracoes": [
{
"nome": "Imposto de Renda",
"declaracoes": [
{
"nome": "2021-00011008000013019",
"idDeclaracao": "2021:IRPF:00011008000013019",
"codigoContrato": "00011008000013"
},
{
"nome": "2020-00011008000013019",
"idDeclaracao": "2020:IRPF:00011008000013019",
"codigoContrato": "00011008000013"
},
{
"nome": "2019-00011008000013019",
"idDeclaracao": "2019:IRPF:00011008000013019",
"codigoContrato": "00011008000013"
}
]
},
{
"nome": "Carta de Quitação",
"declaracoes": [
{
"nome": "2021-00011008000013019",
"idDeclaracao": "2021:CQ:00011008000013019",
"codigoContrato": "00011008000013"
},
{
"nome": "2020-00011008000013019",
"idDeclaracao": "2020:CQ:00011008000013019",
"codigoContrato": "00011008000013"
},
{
"nome": "2019-00011008000013019",
"idDeclaracao": "2019:CQ:00011008000013019",
"codigoContrato": "00011008000013"
}
]
}
]
} |
{
"status": false,
"motivoCritica": "Nenhum beneficiário encontrado para os parâmetros informados."
} |
| Atributo | Tipo | Descrição |
|---|---|---|
| status | Lógico | True: Indica que a requisição foi bem-sucedida False: Indica que a requisição foi mal sucedida |
| motivoCritica | Caracter | Motivo pelo qual não foi possível realizar a requisição, quando o status for igual a False |
| tipoDeclaracoes | Array | Lista de objetos de “tipoDeclaracao“ |
| nome (Objeto tipoDeclaracoes) | Caracter | Nome que identifica a lista de declaração |
| declaracoes | Array | Lista de objetos de “declaracoes“ |
| nome (Objeto declaracoes) | Caracter | Nome que identifica a declaração (Ano + Matricula do Beneficiário) |
| idDeclaracao | Caracter | Chave de identificação da declaração no sistema (Ano + Declaração + Matricula) |
| codigoContrato | Caracter | Código do Contrato do Beneficiário (Operadora + Empresa + Matricula) |
Este método irá retornar uma URL ou um caracter BASE64 contendo o arquivo PDF da declaração.
Esse método irá receber a chave de identificação da declaração que foi retornado no método listaDeclaracoes. A Chave deverá conter o ano, tipo da declaração a ser gerada e a matricula do beneficiário.
Através Modo PDF (BA0_MSPDFM) no cadastro da operadora, será definido o tipo de PDF que será gerado (URL ou base64). Quando utilizado via URL, deverá informar no campo URL PDF (BA0_MSPDFU) o caminho para acessar pela internet.
| Url | Método | Header Content-Type | Descrição |
|---|---|---|---|
| https://<url>:<porta>/rest/mobileSaude/v1/declaracaoPdf | POST | application/json | Retorna a declaração em PDF |
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| idDeclaracao | Sim | Caracter | Chave de identificação da declaração no sistema (Ano + Declaração + Matricula) |
{
"idDeclaracao": "2021:IRPF:00011008000013019"
} |
{
"status": true,
"url": "c:\\protheus12127\\protheus_data\\web\\pp\\imagens-pls\\relatorios\\impostoRenda.pdf",
"base64": ""
} |
{
"status": false,
"motivoCritica": "Não foi possível gerar o PDF"
} |
| Atributo | Tipo | Descrição |
|---|---|---|
| status | Lógico | True: Indica que a requisição foi bem-sucedida False: Indica que a requisição foi mal sucedida |
| motivoCritica | Caracter | Motivo pelo qual não foi possível realizar a requisição, quando o status for igual a False |
| base64 | Caracter em base64 | Conteúdo binário do tipo base64, do arquivo PDF da declaração. |
| url | Caracter | URL completo do arquivo PDF informado no cadastro da Operadora |
Outras Ações / Ações relacionadas
| Ação | Descrição |
|---|---|
| Não se aplica | Não se aplica |
Principais Campos e Parâmetros do TOTVS Saúde Planos Linha Protheus
| Campo | Descrição |
|---|---|
| BA0_MSPDFM | Informe se o download dos PDF´s das API´s Mobile Saúde será via download através de um URL HTTP ou o arquivo será transmitido via Base 64 no JSON de resposta. |
| BA0_MSPDFU | Informe a URL HTTP para download dos arquivos PDF´s na integração com a Mobile Saúde quando selecionado a opção via URL. |
| BA0_MSDECL | Indica a quantidade de anos que o sistema irá listar nas declarações. Exemplo: caso seja informado o valor 3, o sistema irá listar as declarações dos últimos 3 anos. |
| BA0_MSDECD | Indica as declarações que serão utilizadas na API. Imposto de renda, carta de quitação ou ambas. |