API do TesouroInfo (Experimental)

Atenção:
          
• Esta API está em fase experimental e pode apresentar inconsistências.
• São possíveis 50 requisições mensais devido a limitação atual do servidor.

A API do TesouroInfo fornece dados de taxas e preços atuais ou de datas específicas de dados coletados do Tesouro Direto usando diferentes formatos. Essa API tem alguns endpoints (url específico), onde cada um deles serve a um propósito diferente e caso de uso. Os endpoints incluem funcionalidades como receber um conjunto específico de filtros e responder com os valores mais recentes para um ou para todos os títulos.

Neste documento, você descobrirá sobre a estrutura da API, os métodos e os possíveis erros e exemplos de código.

Chave da API

A API tem um identificador exclusivo como uma chave de API que é passada para a API como um parâmetro de URL access_key. Esse parâmetro serve como uma autenticação de identificação exclusiva com a API TesouroInfo, para obter uma chave o usuário deve criar uma conta no site e gerar a chave de acesso no menu dentro da conta de usuário.

URL base:

https://tesouroinfo.com/api/v1/

Após obter sua chave de API, anexe à url. Veja abaixo um exemplo de como utilizar a API TesouroInfo:

https://tesouroinfo.com/api/v1/bonds?access_key=API_KEY

Resposta da API

Os dados são retornados em um formato JSON padrão e podem ser facilmente lidos em qualquer linguagem de programação.

Exemplo de resposta: Veja abaixo um exemplo de uma resposta de API que fornece informações sobre todos os títulos existentes no Tesouro Direto, cada título contém o nome (name), a data de vencimento (due_date) e o tipo (type) que diz se está disponível para investir, resgatar ou não negociável.

[
  {
    "success": true,
    "info": "todos títulos",
    "request_date": "01/ago./2023 21:55",
    "content": [
        {
          "name": "Tesouro renda+ aposentadoria extra 2030",
          "due_date": "15/dez./2049",
          "type": "investir e resgatar"
        },
        {
          "name": "Tesouro renda+ aposentadoria extra 2035",
          "due_date": "15/dez./2054",
          "type": "investir e resgatar"
        },
        ...
    ]
  }
]

Como podemos ver no exemplo acima, a resposta da API sempre contém algumas informações como data/hora (request_date) da leitura que indica quando as informações fornecidas foram coletadas. Além disso, o campo success indica que a leitura dos dados foi realizada com sucesso, o campo info indica o tipo de título que foi pesquisado e pode ser passado como parâmetro para filtragem na url, por fim o campo content fornece todos os títulos encontrados.

Abaixo, na seção Endpoints, discutiremos a estrutura de resposta da API com mais detalhes.

Endpoints disponíveis

A API possui alguns endpoints onde cada um deles fornece uma funcionalidade diferente.

• Endpoints para os títulos existentes:

Esse endpoint retorna os títulos do Tesouro Direto disponíveis, pode ser filtrado através dos campos info e type.

• Endpoints para obter valores históricos de algum título:

Esse endpoint retorna todas as taxas para um determinado título do Tesouro Direto disponível, necessário utilizar os filtros através dos campos info e type. Se mais de um título for encontrado, retornará o primeiro encontrado.

• Endpoints para obter histórico de taxas selics:

Esse endpoint retorna todas as taxas selic registradas para o período especificado.

Possíveis erros

Quando enviamos solicitações de API, mas os dados solicitados não estão disponíveis ou a chamada de API falha por algum motivo, um código de erro em formato JSON será retornado. Os erros sempre vêm junto com um código de erro e uma descrição.

Exemplo de erro:

O erro a seguir será retornado se nenhuma chave de acesso for específicada.

{
  "success": false,
  "error": {
      "code": 101,
      "info": "No API Key was specified."
  }
}

Conexão SSL

Todos as conexões da API do TesouroInfo utilizam criptografia SSL de 256 bits. Basta usar o protocolo https para se conectar à API através de SSL.

Códigos de erro e descrições

Código de erro	Descrição
101	No API Key was specified.
102	This API Key is inactive.
103	The account this API request is coming from is inactive.
104	Invalid API Key was specified.
105	The maximum allowed API amount of monthly API requests has been reached.
106	The current request did not return any results.
107	The requested API endpoint does not exist.
108	An invalid date has been specified.

https://tesouroinfo.com/api/v1/bonds
          ? access_key = API_KEY
          & name = prefixado
          & type = investir

[
  {
      "success": true,
      "type": "investir e resgatar",
      "name": "prefixado",
      "date": "02/ago./2023 19:34",
      "content": [
          {
              "name": "Tesouro prefixado 2026",
              "due_date": "01/jan./2026",
              "type": "investir e resgatar"
          },
          {
              "name": "Tesouro prefixado 2029",
              "due_date": "01/jan./2029",
              "type": "investir e resgatar"
          },
          {
              "name": "Tesouro prefixado com juros semestrais 2033",
              "due_date": "01/jan./2032",
              "type": "investir e resgatar"
          }
      ]
  }
]

https://tesouroinfo.com/api/v1/fees
          ? access_key = API_KEY
          & name = ipca 2045
          & type = investir
          & fields = date,fee
          & start_date = 10-5-2022
          & end_date = 25-12-2022

[
  {
      "success": true,
      "request_date": "02/ago./2023 21:37",
      "name": "Tesouro ipca+ 2045",
      "type": "investir e resgatar",     
      "content_for": "investir",
      "content": [
          {
            "date": "10/mai./2022 12:20",
            "fee": "5.7300%"
          },
          {
            "date": "10/mai./2022 15:04",
            "fee": "5.8000%"
          },
          ...
          {
            "date": "23/dez./2022 16:02",
            "fee": "6.3400%"
          },
          {
            "date": "23/dez./2022 18:25",
            "fee": "6.3600%"
          }
      ]
  }
]

https://tesouroinfo.com/api/v1/selics
          ? access_key = API_KEY
          & start_date = 10-5-2022
          & end_date = 25-12-2022

[
  {
    "success": true,
    "período": "10-5-2022 até 25-12-2022",
    "request_date": "07/ago./2023 22:06",
    "content": [
        {
          "date": "10/mai./2022 03:00",
          "fee": "12.6500%"
        },
        {
          "date": "11/mai./2022 03:00",
          "fee": "12.6500%"
        },
        ...
        {
          "date": "22/dez./2022 03:00",
          "fee": "13.6500%"
        },
        {
          "date": "23/dez./2022 03:00",
          "fee": "13.6500%"
        }
    ]
  }
]