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ção

Nome

Descrição

Abreviação

Nome

Descrição

M

Mandatório

O preenchimento do atributo é obrigatório. Caso o atributo esteja nulo ou em branco, seu "response" será rejeitado.

C

Condicional

O atributo pode tornar-se obrigatório quando um ou mais atributos auxiliares for preenchido / atualizado.

OP

Opcional

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-Type

Descrição

Endpoint

Método

Header Content-Type

Descrição

exemplo.com/listarDeclaracoes

Atenção

O endpoint obrigatoriamente deve terminar com "/listarDeclaracoes".



POST

application/json

Endpoint 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 

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

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

status

M

Boolean

Indica que a requisição foi bem sucedida

True 

tipoDeclaracoes

M

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

alerta

OP

String

Caso 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

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

nome

M

String

Nome que identifica a lista de declaração que será enviada

Texto livre

declaracoes

M

Array de objetos "declaracao"

Retorna um array de objetos do tipo "declaracao"

Caso nenhuma declaração seja encontrada, este array deve estar vazio

Objeto declaracao

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

nome

M

String

Nome que identifica a declaração, em caso de declarações anuais retornar o Ano da competência

Texto livre

idDeclaracao

M

String

Retorna 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 interno

Texto livre

codigoContrato

M

String

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

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

status

M

Boolean

Indica que a requisição foi mal sucedida.

false

motivoCritica

M

String

Motivo 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-Type

Descrição

Endpoint

Método

Header Content-Type

Descrição

exemplo.com/declaracaoPdf



POST

application/json

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

Parâmetros de entrada

Parâmetro

Obrigatório

Tipo

Descrição

Parâmetro

Obrigatório

Tipo

Descriçã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

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

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

status

M

Boolean

Indica que a requisição foi bem sucedida.

True

url

C

String

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

base64

C

String

Retorna 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

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

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

status

M

Boolean

Indica que a requisição foi mal sucedida

false

motivoCritica

M

String

Motivo pelo qual não foi possível realizar a requisição

Formato: Texto Livre

Retorno da API - Falha



Mobile Saúde - 2019