Consulta de wallet

Este endpoint permite realizar consultas básicas e detalhadas de uma carteira de investimento específica (wallet). Na consulta básica, você pode visualizar informações como o valor-alvo (target) que se deseja alcançar e o status da carteira. Já na consulta detalhada, além das informações básicas, é possível obter dados sobre os investimentos realizados.

Pré-requisito

Para que seja possível utilizar este endpoint, é necessário que:

Uma carteira de investimento (wallet) tenha sido previamente criada, e o parceiro possua o walletNumber correspondente para inseri-lo no caminho (path) desta requisição.

Requisição (Request)

Requisição HTTP

GET https://api-mtls.sandbox.bankly.com.br/investments/wallets/{{walletNumber}}?resultLevel={{resultLevel}}

--request GET \ 
--url 'https://api-mtls.sandbox.bankly.com.br//investments/wallets/{{walletNumber}}?resultLevel={{resultLevel}}' \  
--header 'x-bkly-correlation-id: c3ed401d-b4a3-44e5-9b09-78fdc4aee85e'
--header 'Content-Type: application/json'
--header 'api-version: 1.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
`investment.wallet.read`	Concede acesso para consultar informações de uma carteira de investimento.

Cabeçalhos (Headers)

Nome	Descrição	Especificação
`api-version`	Obrigatório. Versão da API. Atualmente estamos na versão 1.0.	—
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.	—
`x-bkly-correlation-id`	Id de correlação da requisição, usado para rastrear uma sequência de chamadas de APIs.	Informe um GUID v4, que deverá ser gerado a cada nova requisição.

Parâmetros da rota (Path)

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

Nome	Tipo	Descrição
`walletNumber`	`path`	Obrigatório. Identificador único gerado pela criação da wallet.
`resultLevel`	`query`	Nível de consulta das informações da wallet, podendo ser “BASIC”, que retornará uma consulta básica, ou “DETAILED”, que fornecerá uma consulta mais detalhada.

🚧
Importante
Caso o campo resultLevel não seja enviado, a consulta retornará o modelo básico, assumindo o valor BASIC como padrão.

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 aceita e retornará os dados da wallet informada (modelo básico ou detalhado).

Sendo bem-sucedido na consulta BÁSICA, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Número máximo de caracteres
`number`	`string`	Número exclusivo atribuído a cada wallet para identificação e rastreamento.	—
`externalId`	`string`	Um identificador único gerado pelo parceiro.	36
`programId`	`string`	Código de identificação do programa de investimentos.	—
`target`	`object`	Objeto que contém informações sobre o objetivo financeiro da wallet.	—
`target.name`	`string`	Etiqueta identificadora do objetivo, como por exemplo "Viagem para Acapulco".	128
`target.amount`	`object`	Objeto que contém informações sobre o valor definido para se alcançar na wallet.	—
`target.amount.value`	`number`	Valor que o cliente deseja alcançar para atingir o objetivo.	—
`target.amount.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.	—
`holder`	`object`	Objeto que contém informações sobre o titular da wallet.	—
`holder.document`	`object`	Objeto que contém informações sobre o documento do titular.	—
`holder.document.value`	`string`	Número do documento.	11
`holder.document.type`	`string`	Tipo do documento, que sempre será “CPF”.	—
`status`	`string`	Situação da wallet, que pode ser “CREATED” (criada), “EARNING” (em rendimento), “BLOCKED” (bloqueada) ou “CLOSED” (encerrada).	—
`createdAt`	`string`	Data e hora da criação da wallet, no formato ISO 8601 - UTC.	—
`updatedAt`	`string`	Data e hora da atualização da wallet, no formato ISO 8601 - UTC. Importante: este campo somente será retornado caso a wallet tenha sido atualizada.	10

{
    "number": "7D09A5452ACA4E618D5C74B747FCEA76",
    "externalId": "720798f8-5905-4df9-b967-ecf568f53823",
    "programId": "720798f8-5905-4df9-b967-ecf568f5386d",
    "target": {
        "name": "Viagem para Acapulco",
        "amount": {
            "value": 2300.00,
            "currency": "BRL"
        }
    },
    "holder": {
        "document": {
            "value": "47742663023",
            "type": "CPF"
        }
    },
    "status": "EARNING",
    "createdAt": "2004-12-15T23:18:38.989Z",
    "updatedAt": "1973-07-12T22:34:26.643Z"
}

Sendo bem-sucedido na consulta DETALHADA, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Número máximo de caracteres
`number`	`string`	Número exclusivo atribuído a cada wallet para identificação e rastreamento.	—
`externalId`	`string`	Um identificador único gerado pelo parceiro.	36
`programId`	`string`	Código de identificação do programa de investimentos.	—
`target`	`object`	Objeto que contém informações sobre o objetivo financeiro da wallet.	—
`target.name`	`string`	Etiqueta identificadora do objetivo, como por exemplo "Viagem para Acapulco".	128
`target.amount`	`object`	Objeto que contém informações sobre o valor definido para se alcançar na wallet.	—
`target.amount.value`	`number`	Valor que o cliente deseja alcançar para atingir o objetivo.	—
`target.amount.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.	—
`holder`	`object`	Objeto que contém informações sobre o titular da wallet.	—
`holder.document`	`object`	Objeto que contém informações sobre o documento do titular.	—
`holder.document.value`	`string`	Número do documento.	11
`holder.document.type`	`string`	Tipo do documento, que sempre será “CPF”.	—
`status`	`string`	Status da wallet, que pode ser “CREATED” (criada), “EARNING” (em rendimento), “BLOCKED” (bloqueada) ou “CLOSED” (encerrada).	—
`createdAt`	`string`	Data e hora da criação da wallet, no formato ISO 8601 - UTC.	—
`updatedAt`	`string`	Data e hora da atualização da wallet, no formato ISO 8601 - UTC. Importante: este campo somente será retornado caso a wallet tenha sido atualizada.	10
`balance`	`object`	Objeto que contém informações sobre o saldo da wallet e o seu rendimento correspondente. Importante: se a wallet possuir mais de um CDB, será apresentada a soma de todos os rendimentos.	—
`balance.invested`	`object`	Objeto que contém informações sobre os investimentos realizados.	—
`balance.invested.value`	`number`	Saldo total investido pelo cliente, sem os rendimentos.	—
`balance.invested.value.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.	—
`balance.gross`	`object`	Objeto que contém informações sobre a soma do saldo total investido e o rendimento bruto acumulado.	—
`balance.gross.value`	`number`	Valor total.	—
`balance.gross.value.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.	—
`balance.net`	`object`	Objeto que contém informações sobre a soma do saldo total investido e o rendimento líquido acumulado.	—
`balance.net.value`	`number`	Valor total.	—
`balance.net.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.	—
`yield`	`object`	Objeto que contém informações sobre o total de rendimento da wallet. Importante: se a wallet possuir mais de um CDB, será apresentada a soma de todos os rendimentos.	—
`yield.createdAt`	`string`	Data e hora do começo do rendimento, no formato ISO 8601 - UTC.	—
`yield.updatedAt`	`string`	Data e hora da atualização do rendimento, no formato ISO 8601 - UTC. Importante: este campo somente será retornado caso o rendimento tenha sido atualizado.	10
`yield.gross`	`object`	Objeto que contém informações sobre o rendimento bruto.	—
`yield.gross.value`	`number`	Valor do rendimento bruto.	—
`yield.gross.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.	—
`yield.net`	`object`	Objeto que contém informações sobre o rendimento líquido, descontando impostos.	—
`yield.net.value`	`number`	Valor do rendimento líquido.	—
`yield.net.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.	—
`taxes`	`object`	Objeto que contém informações sobre os impostos a serem pagos. Importante: se a wallet possuir mais de um CDB, será apresentada a soma de todos os impostos.	—
`taxes.createdAt`	`string`	Data e hora do começo da aplicação das taxas, no formato ISO 8601 - UTC.	—
`taxes.updatedAt`	`string`	Data e hora da atualização das taxas, no formato ISO 8601 - UTC. Importante: este campo somente será retornado caso as taxas tenham sido atualizadas.	10
`taxes.ir`	`object`	Objeto que contém informações sobre o valor do IR (imposto de renda) aplicado na wallet.	—
`taxes.ir.value`	`number`	Valor a ser descontado dos rendimentos em caso de resgate.	—
`taxes.ir.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.	—
`taxes.iof`	`object`	Objeto que contém informações sobre o valor do IOF (Imposto sobre operações financeiras) aplicado na wallet.	—
`taxes.iof.value`	`number`	Valor a ser descontado dos rendimentos em caso de resgate.	—
`taxes.iof.currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: “BRL”.	—

{
    "number": "7D09A5452ACA4E618D5C74B747FCEA76",
    "externalId": "720798f8-5905-4df9-b967-ecf568f53823",
    "programId": "720798f8-5905-4df9-b967-ecf568f5386d",
    "target": {
        "name": "Viagem para Acapulco",
        "amount": {
            "value": 2300.00,
            "currency": "BRL"
        }
    },
    "holder": {
        "document": {
            "value": "47742663023",
            "type": "CPF"
        }
    },
    "status": "EARNING",
    "createdAt": "2004-12-15T23:18:38.989Z",
    "updatedAt": "1973-07-12T22:34:26.643Z",
    "balance": {
        "invested": {
            "value": 1.00,
            "currency": "BRL"
        },
        "gross": { 
            "value": 0.30,
            "currency": "BRL"
        },
        "net": {
            "value": 2301.00,
            "currency": "BRL"
        }
    },
    "yield": {
        "updatedAt": "1973-07-12T22:34:26.643Z",
        "createdAt": "2024-06-06T00:00:00",
        "gross": {
            "value": 1.00,
            "currency": "BRL"
        },
        "net": {
            "value": 0.30,
            "currency": "BRL"
        }
    },
    "taxes": {
	    "createdAt": "2024-06-06T00:00:00",
      "updatedAt": "2024-06-12T02:02:54.703",
      "ir": {
          "value": 2.30,
          "currency": "BRL"
      },
      "iof": {
          "value": 0.23,
          "currency": "BRL"
      }
    }
}

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

Erros

Este endpoint não retorna erros específicos. Porém, ele poderá retornar alguns erros comuns entre todos os endpoints.

Eventos

Este endpoint não possui eventos relacionados a ele.