Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.


CONTEÚDO

  1. Visão Geral
  2. Exemplo de utilização
    1. Método listarDeclaracoes
      1. Regras de Negocio do Método
      2. EndPoint
      3. Parâmetros de Entrada do Método

      4. Exemplo

      5. Estrutura de Retorno

    2. Método declaracaoPdf
      1. Regras de Negocio do Método
      2. EndPoint
      3. Parâmetros de Entrada do Método

      4. Exemplo

      5. Estrutura de Retorno

  3. Tela Declarações Tela Declarações 
    1. Outras Ações / Ações relacionadas
  4. Tela Declarações Declarações 
    1. Principais Campos e Parâmetros
  5. Tabelas utilizadas


01. VISÃO GERAL
Âncora
VISAO
VISAO

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.

02. EXEMPLO DE UTILIZAÇÃO
Âncora
EXEMPLO
EXEMPLO

Segue os métodos utilizados na API:

  • declaracoeslistaDeclaracoes: Retorna uma lista de declarações do beneficiário.
  • pdfDeclaracaodeclaracaoPdf: Retorna uma URL ou um caracter BASE64 contendo o arquivo PDF da declaração.

...

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.

Método

...

listaDeclaracoes
Âncora
DECLARACAO
DECLARACAO

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. 

Regras de Negocio do Método
Âncora
DECLARACAOREGRA
DECLARACAOREGRA

A quantidade de anos que o sistema irá listar nas declarações deverá ser informado no campo Qt. Anos Dec (BA0_MSDECL no ) 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. 

Se o Login for realizado por CPF, o sistema irá listar as declarações de todos os contratos vinculado aquele CPF.

Se o Login for realizado por matricula, o sistema irá listar somente as declarações daquele contrato.

...

Endpoint
Âncora
DECLARACAOENDPOINT
DECLARACAOENDPOINT

Url

Método

Header Content-Type

Descrição

https://<url>:<porta>/rest/mobileSaude/v1/declaracoeslistaDeclaracoesPOSTapplication/jsonRetorna uma lista de declarações

Parâmetros de Entrada do Método
Âncora
DECLARACAOPARAMETROS
DECLARACAOPARAMETROS

Parâmetro

Obrigatório

Tipo

Descrição

chaveBeneficiarioSimNãoCaracterChave do Beneficiário (CPF ou Matricula)
chaveBeneficiarioTipoSimNãoCaracterTipo de Login do Beneficiário (CPF ou Matricula)
multiContractSimNãoLógicoUtilização de Multi Contratos pelo Beneficiário
matriculaContratoSimCaracterMatricula do Beneficiário 

Exemplo
Âncora
DECLARACAOEXEMPLO
DECLARACAOEXEMPLO


Bloco de código
languagec#
themeMidnight
titleRequest body
linenumberstrue
collapsetrue
{
    "chaveBeneficiarioTipo": "CPF",
    "multiContract": truefalse,
    "chaveBeneficiario": "71461963990",
    "matriculaContrato": "7646163309000011008000013019"
}
Bloco de código
languagec#
themeMidnight
titleAPI Retorno - Sucesso
linenumberstrue
collapsetrue
{
    "status": true,
    "tiposDeclaracoestipoDeclaracoes": [
        {
            "declaracoesnome": [
                {
                    "nomeDeclaracao": "2021-00010050000002004",
                    "codigoContrato": "00010050000002",
  "Imposto de Renda",
                  "idDeclaracao"declaracoes": "2021:IRPF:00010050000002004"
            [
    },
                {
                    "nomeDeclaracaonome": "20202021-0001005000000200400011008000013019",
                    "codigoContratoidDeclaracao": "000100500000022021:IRPF:00011008000013019",
                    "idDeclaracaocodigoContrato": "2020:IRPF:0001005000000200400011008000013"
                },
                {
                    "nomeDeclaracaonome": "20192020-0001005000000200400011008000013019",
                    "codigoContrato": "00010050000002",
                    "idDeclaracao": "2019:IRPF:00010050000002004"
                }
            ],
            "nome": "Imposto de Renda"
        },
        {
            "declaracoes": [
                {
                    "nomeDeclaracao": "2021-000100500000020042020:IRPF:00011008000013019",
                    "codigoContrato": "0001005000000200011008000013",
                    "idDeclaracao": "2021:CQ:00010050000002004"
                },
                {
                    "nomeDeclaracaonome": "2020-00010050000002004",
                    "codigoContrato": "00010050000002"2019-00011008000013019",
                    "idDeclaracao": "20202019:CQIRPF:00010050000002004"
                },
                {00011008000013019",
                    "nomeDeclaracaocodigoContrato": "2019-0001005000000200400011008000013",
                    "codigoContrato": "00010050000002",}
                    "idDeclaracao": "2019:CQ:00010050000002004"
     ]
           },
            ],{
            "nome": "Carta de Quitação"
        },
        {
            "declaracoes": [
                {
                    "nomeDeclaracaonome": "2021-0001005000000800200011008000013019",
                    "codigoContrato": "00010050000008",
                    "idDeclaracao": "2021:IRPF:00010050000008002"
                },
                {
                    "nomeDeclaracao": "2020-00010050000008002CQ:00011008000013019",
                    "codigoContrato": "00010050000008",
                    "idDeclaracao": "2020:IRPF:0001005000000800200011008000013"
                },
                {
                    "nomeDeclaracaonome": "20192020-0001005000000800200011008000013019",
                    "codigoContrato": "00010050000008",
                    "idDeclaracao": "20192020:IRPF:00010050000008002"
                }
            ],
            "nome": "Imposto de Renda"
        },
        {
            "declaracoes": [
                {
                    "nomeDeclaracao": "2021-00010050000008002CQ:00011008000013019",
                    "codigoContrato": "0001005000000800011008000013",
                    "idDeclaracao": "2021:CQ:00010050000008002"
                },
                {
                    "nomeDeclaracaonome": "20202019-0001005000000800200011008000013019",
                    "codigoContrato": "00010050000008",
                    "idDeclaracao": "20202019:CQ:00010050000008002"
                },
                {
                    "nomeDeclaracao": "2019-0001005000000800200011008000013019",
                    "codigoContrato": "00010050000008",
                    "idDeclaracao": "2019:CQ:0001005000000800200011008000013"
                }
            ],
            "nome": "Carta de Quitação"
        }
    ]
}
Bloco de código
languagec#
themeMidnight
titleRetorno API - Falha
linenumberstrue
collapsetrue
{
    "status": false,
    "motivoCritica": "Nenhum beneficiário encontrado para os parâmetros informados."
}

Estrutura de Retorno
Âncora
DECLARACAORETORNO
DECLARACAORETORNO

AtributoTipoDescrição
statusLógico

True: Indica que a requisição foi bem-sucedida

False: Indica que a requisição foi mal sucedida

motivoCriticaCaracterMotivo pelo qual não foi possível realizar a requisição, quando o status for igual a False
tipoDeclaracaotipoDeclaracoesArrayLista de objetos de “tipoDeclaracao
nome (Objeto tipoDeclaracaotipoDeclaracoes)CaracterNome que identifica a lista de declaração
declaracoesArrayLista de objetos de “declaracoes
nome (Objeto declaracoes)CaracterNome que identifica a declaração (Ano + Matricula do Beneficiário)
idDeclaracaoCaracterChave de identificação da declaração no sistema (Ano + Declaração + Matricula)
codigoContratoCaracterCódigo do Contrato do Beneficiário (Operadora + Empresa + Matricula)

Método

...

declaracaoPdf
Âncora
PDF
PDF

Este método irá retornar uma URL ou um caracter BASE64 contendo o arquivo PDF da declaração.

Regras de Negocio do Método
Âncora
PDFREGRA
PDFREGRA

Esse método irá receber a chave de identificação da declaração que foi retornado no método declaracoes 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.

Endpoint
Âncora
PDFENDPOINT
PDFENDPOINT

UrlMétodoHeader Content-TypeDescrição
https://<url>:<porta>/rest/mobileSaude/v1/pdfDeclaracaodeclaracaoPdfPOSTapplication/jsonRetorna a declaração em PDF

Parâmetros de Entrada do Método
Âncora
PDFPARAMETROS
PDFPARAMETROS

ParâmetroObrigatórioTipoDescrição
idDeclaracaoSimCaracterChave de identificação da declaração no sistema (Ano + Declaração + Matricula)

Exemplo
Âncora
PDFEXEMPLO
PDFEXEMPLO


Bloco de código
languagec#
themeMidnight
titleRequest body
linenumberstrue
collapsetrue
{
    "idDeclaracao": "20202021:CQIRPF:0001005000000800200011008000013019"
}
Bloco de código
languagec#
themeMidnight
titleAPI Retorno - Sucesso
linenumberstrue
collapsetrue
{
    "status": true,
    "url": "c:\\protheus12127\\protheus_data\\web\\pp\\imagens-pls\\relatorios\\impostoRenda.pdf",
    "base64": ""
}
Bloco de código
languagec#
themeMidnight
titleRetorno API - Falha
linenumberstrue
collapsetrue
{
    "status": false,
    "motivoCritica": "Não foi possível gerar o PDF"
}

Estrutura de Retorno
Âncora
PDFRETORNO
PDFRETORNO

AtributoTipoDescrição
statusLógico

True: Indica que a requisição foi bem-sucedida

False: Indica que a requisição foi mal sucedida

motivoCriticaCaracter Motivo pelo qual não foi possível realizar a requisição, quando o status for igual a False
base64Caracter em base64Conteúdo binário do tipo base64, do arquivo PDF da declaração.
urlCaracterURL completo do arquivo PDF informado no cadastro da Operadora


Card documentos
InformacaoA impressão do PDF da Carta de Quitação utiliza o ponto de entrada PLSQTDEB, por tanto é necessário compila-lo no ambiente. O mesmo estar disponível para download no portal do cliente. Lembrando que o Ponto de entrada deverá retornar um array nesse formato: {,T,, "", "nomeArquivo.PDF"}
TituloImportante!

03. TELA DECLARAÇÕES
Âncora
TELADECLARACOES1
TELADECLARACOES1

Outras Ações / Ações relacionadas

Âncora
TELADECLARACOES1
TELADECLARACOES1

AçãoDescrição
Não se aplicaNão se aplica

04. TELA DECLARAÇÕES
Âncora
TELADECLARACOES2
TELADECLARACOES2

Principais Campos e Parâmetros do TOTVS Saúde Planos Linha Protheus

...

Âncora

...

TELADECLARACOES2
TELADECLARACOES2

CampoDescrição
BA0_MSTLOGInformar o tipo de acesso de login na API da mobile saúde
BA0_MSMULT

Indica se o acesso a Mobile Saúde é Multi Contrato

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 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_MSDECDIndica as declarações que serão utilizadas na API. Imposto de renda: IRPF, carta de quitação : CQ, ambos: IRPF,CQ (Obrigatório utilizar a virgula para separar as declarações)ou ambas.

05. TABELAS UTILIZADAS
Âncora
TABELAS
TABELAS

  • SE1 - Contas a Receber
  • SE5 - Movimentação Bancaria         
  • BBT - Títulos Gerados
  • BM1 - Composição da Cobrança
  • B44 - Autorização Reembolso
  • BA0 - Cadastro de Operadoras



...