Informe de rendimentos

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 (Request)

Requisição HTTP

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

--request GET
--url '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:

Scope	Descrição
`income.report.read`	Concede acesso para a leitura do recurso de informe de rendimento.

Cabeçalhos (Headers)

Nome	Descrição
`api-verion`	Obrigatório. Versão da API, que, neste caso, é 2.0.
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.

Parâmetros da rota (Path)

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

Nome	Tipo	Descrição
`accountNumber`	`path`	Obrigatório. Número da conta da qual se deseja obter os dados para o informe.
`calendar`	`query`	Ano para a geração das informações do informe de rendimento. O valor padrão é 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:

Nome	Tipo	Descrição
`data`	`object`	Objeto que contém informações sobre o response do informe de rendimento.
`data.holder`	`object`	Objeto que contém informações sobre o titular da conta.
`data.holder.document`	`object`	Objeto que contém as informações do documento do titular da conta.
`data.holder.document.value`	`string`	Número de documento do titular da conta.
`data.holder.document.type`	`string`	Tipo do documento do titular da conta.
`data.holder.type`	`string`	Tipo do titular da conta, que pode ser "CUSTOMER" ou "BUSINESS".
`data.holder.name`	`string`	Nome do titular da conta.
`data.holder.createdAt`	`string`	Data da criação da entidade titular da conta, no formato ISO 8601 - UTC.
`data.account`	`object`	Objeto que contém informações sobre a conta do titular.
`data.account.branch`	`string`	Número da agência.
`data.account.number`	`string`	Número da conta.
`data.payers`	`array of objects`	Lista de objetos contendo informações sobre o informe de rendimento com as fontes pagadoras.
`data.payers[].source`	`object`	Objeto que contém informações sobre a fonte pagadora.
`data.payers[].source.name`	`string`	Nome da fonte pagadora.
`data.payers[].source.document`	`object`	Objeto que contém informações do documento da fonte pagadora.
`data.payers[].source.document.value`	`string`	Número de documento da fonte pagadora (CNPJ).
`data.payers[].source.document.type`	`string`	Tipo do documento da fonte pagadora (sempre será CNPJ).
`data.payers[].group`	`string`	Grupo da ficha de bens e direitos a ser informado na declaração.
`data.payers[].currencies`	`dictionary<string, object>`	Dicionário de dados que contém como chave a sigla da moeda.
`data.payers[].currencies.code`	`string`	Código do bem a ser declarado.
`data.payers[].currencies.balances[]`	`array of objects`	Lista de saldos da conta.
`data.payers[].currencies.balances[].year`	`string`	Ano do saldo.
`data.payers[].currencies.balances[].amount`	`object`	Objeto que contém informações sobre o saldo da conta.
`data.payers[].currencies.balances[].amount.value`	`number`	Valor referente ao saldo da conta.
`data.payers[].currencies.balances[].amount.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.
`data.payers[].netIncome`	`dictionary<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.year`	`number`	Ano calendário do rendimento líquido.
`data.payers[].netIncome.amount`	`object`	Objeto que contém os dados de rendimento.
`data.payers[].netIncome.amount.value`	`number`	Valor do rendimento líquido.
`data.payers[].netIncome.amount.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.
`links[]`	`array of objects`	Links de próximos estados válidos da entidade/recurso.
`links[].url`	`string`	URLs que podem ser utilizadas em um próximo estado da entidade. Nesse caso, trata-se da própria requisição realizada.
`links[].rel`	`string`	Descrição de como a URL se relaciona com o recurso atual.
`links[].method`	`string`	Tipo de verbo que deve ser utilizado para acessar a URL. Nesse caso, é o GET.
`metadata`	`dictionary<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 Code	Código	Mensagem	Descrição
400	INCOME_REPORT_NOT_AVAILABLE	Income 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.
400	CALENDAR_NOT_ALLOWED	The 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.

Requisição (Request)

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

Resposta (Response)

👍Dica

Erros

Eventos

👍
Dica