API Investimentos - Títulos do Tesouro Direto

GET /baas/v1/open/dat/treasure-titles/investments

Obtém a lista de operações de Títulos do Tesouro Direto mantidas pelo cliente na instituição transmissora e para as quais ele tenha fornecido consentimento.

Permission necessária: treasure-titles

Parâmetros de query

Exemplo de resposta (200 OK)

{
  "data": [
    {
      "brandName": "Organização A",
      "companyCnpj": "21128159000166",
      "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 Tesouro Direto do cliente na instituição transmissora.
• 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/treasure-titles/investments/{investmentId}

Obtém os dados da operação de Títulos do Tesouro Direto identificada por investmentId.

Permission necessária: treasure-titles

Parâmetros de path

Exemplo de resposta (200 OK)

{
  "data": {
    "isinCode": "BRCST4CTF001",
    "productName": "Tesouro Selic 2025",
    "remuneration": {
      "indexer": "SELIC",
      "indexerAdditionalInfo": "Dólar",
      "preFixedRate": "0.300000",
      "postFixedIndexerPercentage": "1.100000",
      "ratePeriodicity": "DIARIO",
      "calculation": "DIAS_UTEIS"
    },
    "dueDate": "2018-02-15",
    "purchaseDate": "2018-02-15",
    "voucherPaymentIndicator": "SIM",
    "voucherPaymentPeriodicity": "SEMESTRAL",
    "voucherPaymentPeriodicityAdditionalInfo": "Diária"
  },
  "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.isinCode: Código ISIN do título — identificador universal conforme ISO 6166. 12 caracteres alfanuméricos (ex: BRCST4CTF001).
• data.productName: Nome do título conforme listado no site do Tesouro Direto (ex: Tesouro Selic 2025). Máximo 70 caracteres.
• data.remuneration.indexer: Índice de referência para correção da rentabilidade. Enum: CDI, DI, TR, IPCA, IGP_M, IGP_DI, INPC, BCP, TLC, SELIC, PRE_FIXADO, OUTROS.
• data.remuneration.indexerAdditionalInfo: Informações adicionais do indexador. Obrigatório quando indexer for OUTROS.
• data.remuneration.preFixedRate: Taxa pré-fixada da aquisição do contrato (6 casas decimais, ex: 0.300000 = 30%). Obrigatório quando indexer for PRE_FIXADO ou para produtos com remuneração híbrida.
• data.remuneration.postFixedIndexerPercentage: Percentual do indexador da aquisição do contrato (6 a 8 casas decimais, ex: 1.100000 = 110%). Obrigatório quando indexer for diferente de PRE_FIXADO ou para produtos híbridos.
• data.remuneration.ratePeriodicity: Periodicidade da taxa de remuneração. Enum: MENSAL, ANUAL, DIARIO, SEMESTRAL.
• data.remuneration.calculation: Base de cálculo. Enum: DIAS_UTEIS, DIAS_CORRIDOS.
• data.dueDate: Data de vencimento do título (YYYY-MM-DD).
• data.purchaseDate: Data de aquisição pelo cliente (YYYY-MM-DD).
• data.voucherPaymentIndicator: Indica se há pagamento de cupom. Enum: SIM, NAO.
• data.voucherPaymentPeriodicity: Periodicidade do pagamento de cupom. Obrigatório quando voucherPaymentIndicator for SIM. Enum: MENSAL, TRIMESTRAL, SEMESTRAL, ANUAL, IRREGULAR, OUTROS.
• data.voucherPaymentPeriodicityAdditionalInfo: Informações adicionais da periodicidade. Obrigatório quando voucherPaymentPeriodicity for OUTROS.
• 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/treasure-titles/investments/{investmentId}/balances

Obtém a posição (saldo) da operação de Títulos do Tesouro Direto 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 e referenceDateTime igual ao requestDateTime. Campos não obrigatórios não devem ser retornados.

Permission necessária: treasure-titles

Parâmetros de path

Exemplo de resposta (200 OK)

{
  "data": {
    "referenceDateTime": "2022-07-21T17:32:00Z",
    "updatedUnitPrice": {
      "amount": "1000.000004",
      "currency": "BRL"
    },
    "grossAmount": {
      "amount": "1000.04",
      "currency": "BRL"
    },
    "netAmount": {
      "amount": "1000.04",
      "currency": "BRL"
    },
    "incomeTax": {
      "amount": "1000.04",
      "currency": "BRL"
    },
    "financialTransactionTax": {
      "amount": "1000.04",
      "currency": "BRL"
    },
    "blockedBalance": {
      "amount": "1000.04",
      "currency": "BRL"
    },
    "purchaseUnitPrice": {
      "amount": "1000.000004",
      "currency": "BRL"
    },
    "quantity": "1000.015"
  },
  "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.referenceDateTime: Data da última posição consolidada disponível nos canais eletrônicos, no formato RFC-3339 UTC. Quando a posição for zerada, deve ser igual ao requestDateTime.
• data.updatedUnitPrice.amount: Valor bruto unitário atualizado a mercado na data de referência. Com 2 a 8 casas decimais.
• data.updatedUnitPrice.currency: Moeda no padrão ISO-4217 (ex: BRL).
• data.grossAmount.amount: Valor do investimento antes da dedução de impostos, taxas e tarifas, atualizado a mercado na data de referência. Apenas IR e IOF são compartilhados na versão atual, mas outras taxas podem compor o cálculo. Com 2 a 4 casas decimais.
• data.grossAmount.currency: Moeda no padrão ISO-4217.
• data.netAmount.amount: Valor do investimento após dedução de impostos, taxas e tarifas, atualizado a mercado na data de referência. Apenas IR e IOF são compartilhados na versão atual, mas outras taxas podem compor o cálculo. Com 2 a 4 casas decimais.
• data.netAmount.currency: Moeda no padrão ISO-4217.
• data.incomeTax.amount: Valor do IR provisionado com a alíquota vigente na data de referência. Com 2 a 4 casas decimais.
• data.incomeTax.currency: Moeda no padrão ISO-4217.
• data.financialTransactionTax.amount: IOF provisionado. Para produtos com alíquota zero, este objeto pode ser enviado vazio. Com 2 a 4 casas decimais.
• data.financialTransactionTax.currency: Moeda no padrão ISO-4217.
• 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.purchaseUnitPrice.amount: Valor unitário negociado com o cliente na data de aquisição. Com 2 a 8 casas decimais.
• data.purchaseUnitPrice.currency: Moeda no padrão ISO-4217.
• data.quantity: Quantidade de títulos detidos na data de posição do cliente. Com 2 a 8 casas decimais.
• links: Links de navegação entre páginas (ver descrição em GET /baas/v1/open/dat/treasure-titles/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/treasure-titles/investments/{investmentId}/transactions

Obtém as movimentações dos últimos 12 meses da operação de Títulos do Tesouro Direto identificada por investmentId.

Permission necessária: treasure-titles

Parâmetros de path

Parâmetros de query

Exemplo de resposta (200 OK)

{
  "data": [
    {
      "type": "ENTRADA",
      "transactionType": "COMPRA",
      "transactionTypeAdditionalInfo": "",
      "transactionDate": "2018-02-15",
      "transactionUnitPrice": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "transactionQuantity": "42.25",
      "transactionGrossValue": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "incomeTax": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "financialTransactionTax": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "transactionNetValue": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "remunerationTransactionRate": "0.300000",
      "transactionId": "ABCD2126019929279212650822221989319253344"
    }
  ],
  "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 pagamento de juros e amortização, considera-se SAIDA. Enum: ENTRADA, SAIDA.
• data[].transactionType: Natureza da movimentação. Enum: COMPRA, VENDA, CANCELAMENTO, VENCIMENTO, PAGAMENTO_JUROS, AMORTIZACAO, TRANSFERENCIA_TITULARIDADE, TRANSFERENCIA_CUSTODIA, OUTROS.
• data[].transactionTypeAdditionalInfo: Informação adicional do tipo de movimentação. Obrigatório quando transactionType for OUTROS.
• data[].transactionDate: Data da movimentação (YYYY-MM-DD).
• data[].transactionUnitPrice.amount: Preço unitário bruto negociado na transação. Com 2 a 8 casas decimais.
• data[].transactionUnitPrice.currency: Moeda no padrão ISO-4217 (ex: BRL).
• data[].transactionQuantity: Quantidade de títulos envolvidos na movimentação. Com 2 a 8 casas decimais.
• data[].transactionGrossValue.amount: Valor bruto da movimentação (preço unitário × quantidade). Nos casos de saída em que a instituição não tiver o IR retido na fonte, o valor bruto e o líquido devem ser iguais. Com 2 a 4 casas decimais.
• data[].transactionGrossValue.currency: Moeda no padrão ISO-4217.
• data[].incomeTax.amount: Valor do IR recolhido na transação. Com 2 a 4 casas decimais. Obrigatório quando type for SAIDA.
• data[].incomeTax.currency: Moeda no padrão ISO-4217.
• data[].financialTransactionTax.amount: Valor do IOF recolhido na transação. Com 2 a 4 casas decimais. Obrigatório quando type for SAIDA.
• data[].financialTransactionTax.currency: Moeda no padrão ISO-4217.
• data[].transactionNetValue.amount: Valor líquido da transação. Nos casos de saída em que a instituição não tiver o IR retido na fonte, o valor bruto e o líquido devem ser iguais. Com 2 a 4 casas decimais.
• data[].transactionNetValue.currency: Moeda no padrão ISO-4217.
• data[].remunerationTransactionRate: Taxa de remuneração da movimentação (6 casas decimais, ex: 0.300000 = 30%). Obrigatório quando type for ENTRADA.
• data[].transactionId: Código ou identificador único da movimentação individual prestado pela instituição.
• 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/treasure-titles/investments/{investmentId}/transactions-current

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

Permission necessária: treasure-titles

Parâmetros de path

Parâmetros de query

Exemplo de resposta (200 OK)

{
  "data": [
    {
      "type": "ENTRADA",
      "transactionType": "COMPRA",
      "transactionTypeAdditionalInfo": "",
      "transactionDate": "2018-02-15",
      "transactionUnitPrice": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "transactionQuantity": "42.25",
      "transactionGrossValue": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "incomeTax": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "financialTransactionTax": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "transactionNetValue": {
        "amount": "1000.04",
        "currency": "BRL"
      },
      "remunerationTransactionRate": "0.300000",
      "transactionId": "ABCD2126019929279212650822221989319253344"
    }
  ],
  "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 /baas/v1/open/dat/treasure-titles/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.