InstitucionalBlogService DeskStatus Page

Informe de rendimentos

stable

Suggest Edits

Este endpoint permite obter os dados necessários para gerar informes de rendimentos das contas de pagamento (pessoa física e jurídica) e de outras fontes pagadoras dos clientes do parceiro Bankly.

A partir das informações retornadas nas requisições, nosso parceiro poderá estruturar seu próprio documento de informe de rendimentos para disponibilizá-lo a seus clientes.

Requisição

Requisição HTTP

GET https://api-mtls.sandbox.bankly.com.br/accounts/{{accountNumber}}/income-report?calendar={{anoCalendario}}

--location --request GET 'https://api-mtls.sandbox.bankly.com.br/accounts/{{accountNumber}}/income-report?calendar={{anoCalendario}}' \  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'api-version: 2.0' \  
--header 'Authorization: Bearer {{accessToken}}' \

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:

ScopeDescrição
income.report.readConcede acesso para a leitura do recurso de informe de rendimento.

Cabeçalhos (Headers)

NomeDescrição
api-verionObrigatório. Utilize este endpoint na versão 2.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.

Parâmetros da rota (Path)

No path desta requisição envie os seguintes campos:

NomeTipoDescrição
accountNumberpathObrigatório. Número da conta da qual se deseja obter os dados para o informe.
calendarqueryAno para a geração das informações do informe de rendimento. O valor padrão será o ano atual da consulta menos um.

Corpo da requisição (Body)

Não é necessário enviar campos no body desta requisição.

Resposta (Response)

O status code 200 indicará que a solicitação foi completada com sucesso.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

NomeTipoDescrição
dataobjectObjeto que contém os dados de response do informe de rendimento.
data.holderobjectObjeto que contém informações sobre o titular da conta.
data.holder.documentobjectObjeto que contém as informações do documento do titular da conta.
data.holder.document.valuestringNúmero de documento do titular da conta.
data.holder.document.typestringTipo do documento do titular da conta.
data.holder.typeenumTipo do titular da conta (CUSTOMER ou BUSINESS).
data.holder.namestringNome do titular da conta.
data.holder.createdAtstringData da criação da entidade titular da conta.
data.accountobjectObjeto que contém informações sobre a conta do titular.
data.account.branchstringNúmero da agência.
data.account.numberstringNúmero da conta.
data.payersarray of objectsLista que contém os dados de informe de rendimento com as fontes pagadoras.
data.payers[].sourceobjectObjeto que contém informações sobre a fonte pagadora.
data.payers[].source.namestringNome da fonte pagadora.
data.payers[].source.documentobjectObjeto que contém informações do documento da fonte pagadora.
data.payers[].source.document.valuestringNúmero de documento da fonte pagadora (CNPJ).
data.payers[].source.document.typestringTipo do documento da fonte pagadora (sempre será CNPJ).
data.payers[].groupstringGrupo da ficha de bens e direitos a ser informado na declaração.
data.payers[].currenciesdictionary<string, object>Dicionário de dados que contém como chave a sigla da moeda.
data.payers[].currencies.codestringCódigo do bem a ser declarado.
data.payers[].currencies.balances[]array of objectsLista de saldos da conta.
data.payers[].currencies.balances[].yearstringAno do saldo.
data.payers[].currencies.balances[].amountobjectObjeto que contém o saldo da conta.
data.payers[].currencies.balances[].amount.valuenumberValor referente ao saldo da conta.
data.payers[].currencies.balances[].amount.currencystringSigla da moeda do saldo.
data.payers[].netIncomedictionary<string, object>Dicionário de dados do rendimento líquido que contém como chave o tipo de rendimento. Importante: Este objeto somente será retornado caso a conta possua algum valor de rendimento.
data.payers[].netIncome.yearnumberAno calendário do rendimento líquido.
data.payers[].netIncome.amountobjectObjeto que contém os dados de rendimento.
data.payers[].netIncome.amount.valuenumberValor do rendimento líquido.
data.payers[].netIncome.amount.currencystringMoeda do valor do rendimento.
links[]array of objectsLinks de próximos estados válidos da entidade/recurso.
links[].urlstringURLs que podem ser utilizadas em um próximo estado da entidade. Nesse caso, trata-se da própria requisição realizada.
links[].relstringDescrição de como a URL se relaciona com o recurso atual.
links[].methodstringTipo de verbo que deve ser utilizado para acessar a URL. Nesse caso, é o GET.
metadatadictionary<string, object>Metadados da requisição.
{
    "data": {
        "holder": {
            "document": {
                "value": "47742663023",
                "type": "CPF"
            },
            "type": "CUSTOMER",
            "name": "Nísia Floresta",
            "createdAt": "2022-09-29T00:00:00Z"
        },
        "account": {
            "branch": "0001",
            "number": "1100284335"
        },
        "payers": [
            {
                "source": {
                    "name": "Acesso Soluções De Pagamento SA - Instituição de Pagamento",
                    "document": {
                        "value": "13140088000199",
                        "type": "CNPJ"
                    }
                },
                "group": "",
                "currencies": {
                    "brl": {
                        "code": "",
                        "balances": [
                            {
                                "year": 2022,
                                "amount": {
                                    "value": 50999.11,
                                    "currency": "BRL"
                                }
                            },
                            {
                                "year": 2023,
                                "amount": {
                                    "value": 991.11,
                                    "currency": "BRL"
                                }
                            }
                        ]
                    }
                }
            }
        ]
    },
    "links": [
        {
            "url": "/api/accounts/1133/income-report",
            "rel": "get_income_report",
            "method": "GET"
        }
    ],
    "metadata": {}
}

👍

Dica

Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status CodeCódigoMensagemDescrição
400INCOME_REPORT_NOT_AVAILABLEIncome report is not available in the moment, please later try again.Informe de rendimento para um determinado ano calendário não disponível para consulta.
400CALENDAR_NOT_ALLOWEDThe calendar informed is not allowed.Ano calendário informado não permitido para realização da consulta.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400.

Eventos

Este endpoint não possui eventos relacionados a ele.

Updated 2 months ago