API Investimentos - Renda Variável

GET /baas/v1/open/dat/variable-incomes/investments

Obtém a lista de operações de Renda Variável mantidas pelo cliente na instituição transmissora e para as quais ele tenha fornecido consentimento.

Permission necessária: variable-incomes

Parâmetros de query

Exemplo de resposta (200 OK)

{
  "data": [
    {
      "brandName": "Organização A",
      "companyCnpj": "21281590001660",
      "investmentId": "92792126019929200000000000000000000000000"
    }
  ],
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource",
    "last": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Descrição dos campos

• data[].brandName: Nome da marca reportada pelo participante no Open Finance. Preferencialmente o mesmo nome atribuído no diretório Customer Friendly Server Name.
• data[].companyCnpj: CNPJ completo da instituição responsável pelo cadastro (sem máscara).
• data[].investmentId: Identificador único e imutável da operação de renda variável do cliente na instituição transmissora. Nos casos em que o cliente recompra um ativo após 12 meses sem movimentação e com quantidade zerada, o mesmo investmentId anterior deve ser reutilizado.
• links.self: URI completa que gerou a resposta atual.
• links.first: URI da primeira página. Obrigatório quando não for a primeira página.
• links.prev: URI da página anterior. Obrigatório quando não for a primeira página.
• links.next: URI da próxima página. Obrigatório quando não for a última página.
• links.last: URI da última página. Obrigatório quando não for a última página.
• meta.totalRecords: Número total de registros no resultado.
• meta.totalPages: Número total de páginas no resultado.
• meta.requestDateTime: Data e hora da consulta no formato RFC-3339 UTC.

GET /baas/v1/open/dat/variable-incomes/investments/{investmentId}

Obtém os dados da operação de Renda Variável identificada por investmentId.

Permission necessária: variable-incomes

Parâmetros de path

Exemplo de resposta (200 OK)

{
  "data": {
    "issuerInstitutionCnpjNumber": "11225860000140",
    "isinCode": "BRCST4CTF001",
    "ticker": "PETR4"
  },
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource",
    "last": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Descrição dos campos

• data.issuerInstitutionCnpjNumber: CNPJ da instituição emissora (sem máscara). Obrigatório quando a transmissora possuir a informação.
• data.isinCode: Código ISIN do ativo — identificador universal conforme ISO 6166. 12 caracteres alfanuméricos (ex: BRCST4CTF001).
• data.ticker: Código de negociação para identificação do ativo em bolsa (ex: PETR4). Máximo 35 caracteres.
• links: Links de navegação entre páginas (ver descrição em GET /investments).
• meta.totalRecords: Número total de registros no resultado.
• meta.totalPages: Número total de páginas no resultado.
• meta.requestDateTime: Data e hora da consulta no formato RFC-3339 UTC.

GET /baas/v1/open/dat/variable-incomes/investments/{investmentId}/balances

Obtém a posição (saldo) da operação de Renda Variável identificada por investmentId.

Quando não houver posição (quantidade e valores zerados), mas o investimento ainda estiver no prazo de exposição (até 12 meses após a última movimentação), deve-se retornar HTTP 200 com: valores monetários 0.00, quantidade 0.00, data da última posição igual ao requestDateTime (sem o horário) e fator de preço 0.00. Campos não obrigatórios não devem ser retornados.

Permission necessária: variable-incomes

Parâmetros de path

Exemplo de resposta (200 OK)

{
  "data": {
    "referenceDate": "2023-01-07",
    "priceFactor": "100.0005",
    "grossAmount": {
      "amount": "1000.04",
      "currency": "BRL"
    },
    "blockedBalance": {
      "amount": "1000.04",
      "currency": "BRL"
    },
    "quantity": "1000.00000004",
    "closingPrice": {
      "amount": "1000.04",
      "currency": "BRL"
    }
  },
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource",
    "last": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Descrição dos campos

• data.referenceDate: Data da posição fechada para o ativo, referente ao fechamento do dia anterior (YYYY-MM-DD).
• data.priceFactor: Fator que indica o número de ações utilizadas para formação do preço (lote padrão). Valor deve ser maior que zero. Com 2 a 8 casas decimais.
• data.grossAmount.amount: Valor do investimento antes de impostos, taxas e tarifas, atualizado na data de referência. Calculado como: (quantidade ÷ fator de cotação) × preço de fechamento. Com 2 a 4 casas decimais.
• data.grossAmount.currency: Moeda no padrão ISO-4217 (ex: BRL).
• data.blockedBalance.amount: Valor não disponível para movimentação (bloqueio judicial, bloqueio em garantia etc.). Prazo de carência não é considerado bloqueio. Com 2 a 4 casas decimais.
• data.blockedBalance.currency: Moeda no padrão ISO-4217.
• data.quantity: Quantidade total do ativo na data de referência. Pode ser negativo. Com 2 a 8 casas decimais.
• data.closingPrice.amount: Preço de fechamento do ativo na data de referência. Com 2 a 4 casas decimais.
• data.closingPrice.currency: Moeda no padrão ISO-4217.
• links: Links de navegação entre páginas (ver descrição em GET /investments).
• meta.totalRecords: Número total de registros no resultado.
• meta.totalPages: Número total de páginas no resultado.
• meta.requestDateTime: Data e hora da consulta no formato RFC-3339 UTC.

GET /baas/v1/open/dat/variable-incomes/investments/{investmentId}/transactions

Obtém as movimentações históricas (últimos 12 meses) da operação de Renda Variável identificada por investmentId. São compartilhados movimentos até a data da posição (D-1 do pregão).

Permission necessária: variable-incomes

Parâmetros de path

Parâmetros de query

Exemplo de resposta (200 OK)

{
  "data": [
    {
      "type": "ENTRADA",
      "transactionType": "COMPRA",
      "transactionTypeAdditionalInfo": "string",
      "transactionDate": "2018-02-15",
      "priceFactor": "100.0005",
      "transactionUnitPrice": {
        "amount": "1000.0004",
        "currency": "BRL"
      },
      "transactionQuantity": "42.00000025",
      "transactionValue": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "transactionId": "ABCD2126019929279212650822221989319253344",
      "brokerNoteId": "XWYZ555019929279212650822221989319252233"
    }
  ],
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Descrição dos campos

• data[].type: Tipo de movimentação na visão do investimento. Para dividendos, JCP e aluguéis, considera-se SAIDA. Enum: ENTRADA, SAIDA.
• data[].transactionType: Natureza da movimentação. Enum: COMPRA, VENDA, DIVIDENDOS, JCP (Juros sobre Capital Próprio), ALUGUEIS (juros/remuneração pagos ou recebidos de contratos de ações alugadas), TRANSFERENCIA_CUSTODIA, TRANSFERENCIA_TITULARIDADE, OUTROS. A opção OUTROS deve ser usada apenas quando a movimentação não se enquadra em nenhum dos demais itens.
• data[].transactionTypeAdditionalInfo: Informação adicional do tipo de movimentação. Obrigatório quando transactionType for OUTROS.
• data[].transactionDate: Data da movimentação conforme visualizada pelo cliente nos canais da instituição (YYYY-MM-DD). Compartilhar movimentos até a data da posição (D-1 do pregão).
• data[].priceFactor: Fator que indica o número de ações utilizadas para formação do preço. Valor deve ser maior que zero. Com 2 a 8 casas decimais.
• data[].transactionUnitPrice.amount: Preço unitário da movimentação. Em transferências de custódia, quando o PU original não estiver disponível, informar o PU marcado pela instituição na data de transferência. Com 2 a 4 casas decimais. Obrigatório quando transactionType for COMPRA ou VENDA.
• data[].transactionUnitPrice.currency: Moeda no padrão ISO-4217 (ex: BRL).
• data[].transactionQuantity: Quantidade de ativos movimentados. Com 2 a 8 casas decimais. Obrigatório quando transactionType for COMPRA ou VENDA.
• data[].transactionValue.amount: Valor da operação realizada pelo cliente. Com 2 a 4 casas decimais.
• data[].transactionValue.currency: Moeda no padrão ISO-4217.
• data[].transactionId: Código ou identificador único da movimentação individual prestado pela instituição.
• data[].brokerNoteId: Identificador único e imutável da nota de negociação associada à movimentação. A relação entre investmentId e brokerNoteId é N para N (uma nota pode contemplar múltiplos investimentos e vice-versa). A relação entre brokerNoteId e brokerNoteNumber é 1 para 1. Deve ser usado como parâmetro em GET /broker-notes/{brokerNoteId}. Obrigatório quando transactionType for COMPRA ou VENDA.
• links.self: URI completa que gerou a resposta atual.
• links.first: URI da primeira página. Obrigatório quando não for a primeira página.
• links.prev: URI da página anterior. Obrigatório quando não for a primeira página.
• links.next: URI da próxima página. Obrigatório quando não for a última página.
• meta.requestDateTime: Data e hora da consulta no formato RFC-3339 UTC.

GET /baas/v1/open/dat/variable-incomes/investments/{investmentId}/transactions-current

Obtém as movimentações recentes da operação de Renda Variável identificada por investmentId. O período considerado é de até 7 dias anteriores à consulta, incluindo o dia da consulta (D-6).

Permission necessária: variable-incomes

Parâmetros de path

Parâmetros de query

Exemplo de resposta (200 OK)

{
  "data": [
    {
      "type": "ENTRADA",
      "transactionType": "COMPRA",
      "transactionTypeAdditionalInfo": "string",
      "transactionDate": "2018-02-15",
      "priceFactor": "100.0005",
      "transactionUnitPrice": {
        "amount": "1000.0004",
        "currency": "BRL"
      },
      "transactionQuantity": "42.00000025",
      "transactionValue": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "transactionId": "ABCD2126019929279212650822221989319253344",
      "brokerNoteId": "XWYZ555019929279212650822221989319252233"
    }
  ],
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Descrição dos campos

Este endpoint retorna a mesma estrutura de resposta que GET /investments/{investmentId}/transactions. A diferença está no limite de período de consulta: máximo de 7 dias anteriores à data de consulta, inclusive (D-6), em vez dos 12 meses do endpoint histórico.

O objeto meta contém apenas requestDateTime (sem totalRecords e totalPages), e o objeto links não possui o campo last. Consulte a descrição completa dos campos na seção anterior.

GET /baas/v1/open/dat/variable-incomes/investments/{investmentId}/broker-notes/{brokerNoteId}

Obtém as informações da nota de negociação identificada pelo brokerNoteId, gerado nas movimentações de compra e venda de ativos em bolsa. O brokerNoteId é retornado nos campos de transações de compra ou venda e deve ser utilizado como parâmetro de entrada neste endpoint.

A relação entre brokerNoteId e o número natural da nota (brokerNoteNumber) é de 1 para 1 — cada nota de negociação possui um identificador único e imutável.

Permission necessária: variable-incomes

Parâmetros de path

Exemplo de resposta (200 OK)

{
  "data": {
    "brokerNoteNumber": "1854009930314350",
    "grossValue": {
      "amount": "5000.0024",
      "currency": "BRL"
    },
    "brokerageFee": {
      "amount": "13.8751",
      "currency": "BRL"
    },
    "clearingSettlementFee": {
      "amount": "13.8751",
      "currency": "BRL"
    },
    "clearingRegistrationFee": {
      "amount": "13.8751",
      "currency": "BRL"
    },
    "stockExchangeAssetTradeNoticeFee": {
      "amount": "13.8751",
      "currency": "BRL"
    },
    "stockExchangeFee": {
      "amount": "13.8751",
      "currency": "BRL"
    },
    "clearingCustodyFee": {
      "amount": "13.8751",
      "currency": "BRL"
    },
    "taxes": {
      "amount": "13.8751",
      "currency": "BRL"
    },
    "incomeTax": {
      "amount": "13.8751",
      "currency": "BRL"
    },
    "netValue": {
      "amount": "4889.0012",
      "currency": "BRL"
    }
  },
  "links": {
    "self": "https://api.banco.com.br/open-banking/api/v1/resource",
    "first": "https://api.banco.com.br/open-banking/api/v1/resource",
    "prev": "https://api.banco.com.br/open-banking/api/v1/resource",
    "next": "https://api.banco.com.br/open-banking/api/v1/resource",
    "last": "https://api.banco.com.br/open-banking/api/v1/resource"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Descrição dos campos

• data.brokerNoteNumber: Número natural da nota de negociação. Não deve ser utilizado como chave na API — usar brokerNoteId para esse fim. Máximo 16 dígitos.
• data.grossValue.amount: Valor bruto da nota de negociação, correspondente ao somatório de todas as operações de compra e venda do dia. Com 2 a 4 casas decimais.
• data.grossValue.currency: Moeda no padrão ISO-4217 (ex: BRL).
• data.brokerageFee.amount: Taxa de corretagem incidente sobre o valor bruto da nota. Livremente pactuada entre investidor e intermediário — pode ser cobrada como valor fixo, percentual sobre o valor negociado ou de forma mista. Com 2 a 4 casas decimais.
• data.brokerageFee.currency: Moeda no padrão ISO-4217.
• data.clearingSettlementFee.amount: Valor cobrado para liquidação na custódia. Com 2 a 4 casas decimais.
• data.clearingSettlementFee.currency: Moeda no padrão ISO-4217.
• data.clearingRegistrationFee.amount: Valor cobrado para registro na custódia. Com 2 a 4 casas decimais.
• data.clearingRegistrationFee.currency: Moeda no padrão ISO-4217.
• data.stockExchangeAssetTradeNoticeFee.amount: Valor cobrado pela bolsa pelo Aviso de Negociação de Ativos (A.N.A). Com 2 a 4 casas decimais.
• data.stockExchangeAssetTradeNoticeFee.currency: Moeda no padrão ISO-4217.
• data.stockExchangeFee.amount: Emolumentos — valor cobrado pela bolsa para remunerar os serviços de registro prestados. Com 2 a 4 casas decimais.
• data.stockExchangeFee.currency: Moeda no padrão ISO-4217.
• data.clearingCustodyFee.amount: Taxa de custódia cobrada pela instituição financeira. Com 2 a 4 casas decimais.
• data.clearingCustodyFee.currency: Moeda no padrão ISO-4217.
• data.taxes.amount: Impostos cobrados na operação, inclusive IR day-trade, exceto IRRF. Com 2 a 4 casas decimais.
• data.taxes.currency: Moeda no padrão ISO-4217.
• data.incomeTax.amount: Imposto de Renda retido na fonte (IRRF). Com 2 a 4 casas decimais.
• data.incomeTax.currency: Moeda no padrão ISO-4217.
• data.netValue.amount: Valor líquido da nota após dedução de todas as despesas: corretagem, liquidação, registro, A.N.A., emolumentos, custódia, impostos e IRRF. Com 2 a 4 casas decimais.
• data.netValue.currency: Moeda no padrão ISO-4217.
• links: Links de navegação entre páginas (ver descrição em GET /investments).
• meta.totalRecords: Número total de registros no resultado.
• meta.totalPages: Número total de páginas no resultado.
• meta.requestDateTime: Data e hora da consulta no formato RFC-3339 UTC.