Declarações

Objetivo

Este documento tem como objetivo orientar a construção dos webservices para apresentação  de declarações, comumente utilizados para ara declarações de Carta de Quitação e Declaração anual de Imposto de Renda, INSS, e também pode ser utilizado para exibição de outros tipos de documentos.

Necessidade

Disponibilizar ao beneficiário a declarações (IRPF, INSS e etc) contendo relação de itens e valores relacionados à declaração selecionada, no IRPF por exemplo a relação das despesas com o plano de saúde, seja mensalidade, participações financeiras e reembolso.

O beneficiário necessita ainda que este relatório possa ser exportado para PDF e enviado por e-mail ou impresso.

Informações

Avisos
  1. Só são suportadas integrações no padrão REST.
  2. O campo "Regra de preenchimento" esclarece quais regras / validações serão aplicadas ou quais os conteúdos serão permitidos ou rejeitados. As ações descritas aqui devem ser implementadas por seus WS, evitando que os conteúdos inválidos sejam criticados pelo nosso sistema de integrações.
Critérios de preenchimento
AbreviaçãoNomeDescrição
MMandatórioO preenchimento do atributo é obrigatório. Caso o atributo esteja nulo ou em branco, seu "response" será rejeitado.
CCondicionalO atributo pode tornar-se obrigatório quando um ou mais atributos auxiliares for preenchido / atualizado.
OPOpcional

Seu preenchimento não é obrigatório. Pode-se enviar NULL para objetos, ou arrays vazios para tipos Array

Método "listarDeclaracoes"

Este método irá retornar a lista de débitos relacionados ao localizador (chaveBeneficiario). A quantidade de débitos retornados, o período e a regra deste retorno fica a critério da operadora.

Regras de negócio

  1. Este método deverá receber a identificação do beneficiário (parâmetro chaveBeneficiario);
    1. Deverá avaliar se o beneficiário requisitante tem direitos para solicitar esta informação;
    2. Deverá retornar uma lista de declarações ordenado da forma como deseja apresentar ao usuário;
      1. A quantidade de declarações que será retornada é da sua escolha, mas recomendamos no máximo 12 meses ou todos os que estão em aberto, para não sobrecarregar a requisição;

Endpoint

Endpoint
Método
Header Content-TypeDescrição

exemplo.com/listarDeclaracoes

Atenção

O endpoint obrigatoriamente deve terminar com "/listarDeclaracoes".

POST

application/jsonEndpoint que retorna lista de débitos relacionados ao localizador

Parâmetros de entrada

Request body

Atenção

No corpo da requisição serão enviadas as informações do atributo integração do retorno do login.



Objetos e atributos de retorno

Atenção

Os atributos devem seguir exatamente os mesmos nomes indicados nesta documentação, caso contrário, serão rejeitados pelo validador de integração.

Exemplo do atributo "tipoDeclaracoes":

  • tipo-declaracoes
  • tipo_declaracoes
  • tipos
  • tipoDeclaracoes (concordo)

Descrição dos objetos e atributos de retorno - Sucesso

Está indicado abaixo a estrutura de retorno do seu método de listaDeclaracoes Esse método deve obedecer as regras indicadas no objeto principal e em seus desdobramentos.

Objeto principal
AtributoCritérioTipoDescriçãoRegra de preenchimento
statusM

Boolean

Indica que a requisição foi bem sucedida

True 

tipoDeclaracoesMArray de objetos "tipoDeclaracao"Retornar um array de objetos “tipoDeclaracao“.Caso nenhum tipo seja encontrado, ou as declarações estejam vazias, este array deve estar vazio.
alertaOPStringCaso queira enviar um alerta para os beneficiário no ato da apresentação dos débitos, insira o conteúdo aqui. Utilize textos curtos para facilitar a leitura.

Formato: Texto Livre. 

Objeto tipodeclaracao
AtributoCritérioTipoDescriçãoRegra de preenchimento
nomeMStringNome que identifica a lista de declaração que será enviadaTexto livre
declaracoesMArray de objetos "declaracao"Retorna um array de objetos do tipo "declaracao"Caso nenhuma declaração seja encontrada, este array deve estar vazio
Objeto declaracao
AtributoCritérioTipoDescriçãoRegra de preenchimento
nomeMStringNome que identifica a declaração, em caso de declarações anuais retornar o Ano da competênciaTexto livre
idDeclaracaoMStringRetorna o código da declaração do beneficiário, este código pode ser composto pois ele deve ser capaz de identificar tanto o tipo de declaração quanto o seu código internoTexto livre
codigoContratoMString

Código que identifica de qual contrato esta declaração está vinculada

ASCII (nao permite especiais). 

Este código deve ter o mesmo conteúdo do atributo codigoContrato da estrutura “beneficiario“

Retorno da API - Sucesso

{
    "status": true,
    "tipoDeclaracoes": [
        {
            "nome": "Imposto de Renda",
            "declaracoes": [
                {
                    "nome": "2017",
                    "idDeclaracao": "2017:IRPF:3020170703122646",
                    "codigoContrato": "688030"
                },
                {
                    "nome": "2018",
                    "idDeclaracao": "2018:IRPF:3020170703122646",
                    "codigoContrato": "786503"
                },
                {
                    "nome": "2019",
                    "idDeclaracao": "2019:IRPF:3020170703122646",
                    "codigoContrato": "203949"
                }
            ]
        },
        {
            "nome": "Carta de Quitação",
            "declaracoes": [
                {
                    "nome": "2017",
                    "idDeclaracao": "2017:CQ:3020170703122646",
                    "codigoContrato": "688658"
                },
                {
                    "nome": "2018",
                    "idDeclaracao": "2018:CQ:3020170703122646",
                    "codigoContrato": "932844"
                },
                {
                    "nome": "2019",
                    "idDeclaracao": "2019:CQ:3020170703122646",
                    "codigoContrato": "789163"
                }
            ]
        }
    ]
}

Descrição dos objetos e atributos de retorno - Falha

Está indicado abaixo a estrutura de retorno do seu método de listaDeclaracoes. Esse método deve obedecer as regras indicadas no objeto principal e em seus desdobramentos.

Objeto principal
AtributoCritérioTipoDescriçãoRegra de preenchimento
statusM

Boolean

Indica que a requisição foi mal sucedida.false
motivoCriticaMStringMotivo pelo qual não foi possível realizar a requisição.

Este campo é obrigatório quando o status igual a false.

Formato: Texto Livre

Retorno da API - Falha

{
    "status": false,
    "motivoCritica": ""
}

Método "declaracaoPdf"

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

Regras de Negócio

  • Será adicionado ao corpo da requisição as informações enviadas no atributo integracao no retorno do login.

Endpoint

Endpoint
Método
Header Content-TypeDescrição

exemplo.com/declaracaoPdf

Atenção

O endpoint obrigatoriamente deve terminar com "/declaracaoPdf".

POST

application/jsonEndpoint que retorna uma URL ou um campo BASE64 contendo o arquivo PDF da declaração

Parâmetros de entrada

ParâmetroObrigatórioTipoDescrição

idDeclaracao

M

String

Código da declaração do beneficiário, o mesmo que é retornado na listagem de declarações.

Request body

{
  "idDeclaracao": "<idDeclaracao>"
}

Objetos e atributos de retorno

Atenção

Os atributos devem seguir exatamente os mesmos nomes indicados nesta documentação, caso contrário, serão rejeitados pelo validador de integração.

Exemplo do atributo "status":

  • Status
  • situacao
  • status (concordo)

Descrição dos objetos e atributos de retorno - Sucesso

Está indicado abaixo a estrutura de retorno do seu método de declaracaoPdf. Esse método deve obedecer as regras indicadas no objeto principal e em seus desdobramentos.

Objeto principal
AtributoCritérioTipoDescriçãoRegra de preenchimento
statusM

Boolean

Indica que a requisição foi bem sucedida.

True

urlCString

Retorna a URL do arquivo PDF no seu servidor. Essa URL precisa ser publica para ser acessada diretamente pelo aplicativo do usuário.

Caso o atributo base64 esteja vazio, este atributo torna-se obrigatório
base64CStringRetorna conteúdo binário, tipo base64, do arquivo PDF da declaração.

Formato: base64.

Caso o atributo url esteja vazio, este atributo torna-se obrigatório

Retorno da API - Sucesso

{
    "status": true,
    "url": "https://ms-publico.s3-sa-east-1.amazonaws.com/mockups/declaracoes/declaracaoIR.pdf",
	"base64": ""
}

Descrição dos objetos e atributos de retorno - Falha

Está indicado abaixo a estrutura de retorno do seu método de delcaracaoPdf. Esse método deve obedecer as regras indicadas no objeto principal e em seus desdobramentos.

Objeto principal
AtributoCritérioTipoDescriçãoRegra de preenchimento
statusM

Boolean

Indica que a requisição foi mal sucedidafalse
motivoCriticaMStringMotivo pelo qual não foi possível realizar a requisição

Formato: Texto Livre

Retorno da API - Falha

{
    "status": false,
    "motivoCritica": ""
}

Mobile Saúde - 2019