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.
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.
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 |
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.
Endpoint | Método | Header Content-Type | Descrição | |
---|---|---|---|---|
exemplo.com/listarDeclaracoes
| POST | application/json | Endpoint que retorna lista de débitos relacionados ao localizador |
No corpo da requisição serão enviadas as informações do atributo integração do retorno do login. |
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":
|
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.
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. |
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 |
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“ |
{ "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" } ] } ] } |
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.
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 |
{ "status": false, "motivoCritica": "" } |
Este método irá retornar uma URL ou um campo BASE64 contendo o arquivo PDF da declaraçã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â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. |
{ "idDeclaracao": "<idDeclaracao>" } |
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":
|
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.
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 |
{ "status": true, "url": "https://ms-publico.s3-sa-east-1.amazonaws.com/mockups/declaracoes/declaracaoIR.pdf", "base64": "" } |
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.
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 |
{ "status": false, "motivoCritica": "" } |