1 Objetivo
2 Necessidade
3 Informações
- 3.1 Avisos
- 3.2 Critérios de preenchimento
4 Método "listarDeclaracoes"
- 4.1 Regras de negócio
- 4.2 Endpoint
  - 4.2.1 Atenção
- 4.3 Parâmetros de entrada
- 4.4 Request body
  - 4.4.1 Atenção
- 4.5 Objetos e atributos de retorno
  - 4.5.1 Atenção
- 4.6 Descrição dos objetos e atributos de retorno - Sucesso
  - 4.6.1 Objeto principal
  - 4.6.2 Objeto tipodeclaracao
  - 4.6.3 Objeto declaracao
- 4.7 Retorno da API - Sucesso
- 4.8 Descrição dos objetos e atributos de retorno - Falha
  - 4.8.1 Objeto principal
- 4.9 Retorno da API - Falha
5 Método "declaracaoPdf"
- 5.1 Regras de Negócio
- 5.2 Endpoint
  - 5.2.1 Atenção
- 5.3 Parâmetros de entrada
- 5.4 Request body
- 5.5 Objetos e atributos de retorno
  - 5.5.1 Atenção
- 5.6 Descrição dos objetos e atributos de retorno - Sucesso
  - 5.6.1 Objeto principal
- 5.7 Retorno da API - Sucesso
- 5.8 Descrição dos objetos e atributos de retorno - Falha
  - 5.8.1 Objeto principal
- 5.9 Retorno da API - Falha

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

Só são suportadas integrações no padrão REST.
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

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

Base de Conhecimento - Público

Declarações

Objetivo

Necessidade

Informações

Avisos

Critérios de preenchimento

Método "listarDeclaracoes"

Regras de negócio

Endpoint

Atenção

Parâmetros de entrada

Request body

Atenção

Objetos e atributos de retorno

Atenção

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

Objeto principal

Objeto tipodeclaracao

Objeto declaracao

Retorno da API - Sucesso

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

Objeto principal

Retorno da API - Falha

Método "declaracaoPdf"

Regras de Negócio

Endpoint

Parâmetros de entrada

Request body

Objetos e atributos de retorno

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

Objeto principal

Retorno da API - Sucesso

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

Objeto principal

Retorno da API - Falha