wilsonfreitas · wilsonfreitas · Jun 14, 2026 · Jun 14, 2026
diff --git a/README.md b/README.md
@@ -40,7 +40,7 @@ Implementado no módulo `currency`, realiza webscraping no site do [Conversor de
 ### OData - APIs Estruturadas
 
 O Banco Central disponibiliza diversas informações em APIs que seguem o padrão [OData](https://odata.org). Inclui:
-- **PTAX**: Boletins diários de taxas de câmbio com dados institucionalmentedetalhados
+- **PTAX**: Boletins diários de taxas de câmbio com dados institucionalmente detalhados
 - **Expectativas**: Expectativas de mercado coletadas do Boletim FOCUS
 - **TaxaJuros**: Diversas taxas de juros (Selic, CDI, Cheque especial, etc.)
 - **MercadoImobiliario**: Dados de financiamento imobiliário
@@ -60,7 +60,7 @@ Use esta tabela para escolher o módulo certo para seu caso de uso:
 | Dados de financiamento imobiliário | `bcb.odata` (MercadoImobiliario) | Originações, taxas médias, volumes |
 | Informações de instituições financeiras | `bcb.odata` (IFDATA) | Dados de balanço, informações regulatórias |
 | Análise de dados avançada com filtros | `bcb.odata` (qualquer serviço) | API encadeável, filtragem tipo SQL, ordenação, seleção |
-| Busca concorrente de dados | Qualquer módulo com `async_get()` | Requisições não-bloqueantes, melhor performance para operações em massa |
+| Busca concorrente de dados | APIs assíncronas (`sgs`, `currency` e OData) | Requisições não-bloqueantes com `async_get()`, `Endpoint.async_get()` e `ODataQuery.async_collect()` |
 
 ## Início Rápido
 
@@ -106,16 +106,20 @@ df = endpoint.query().filter(endpoint.Indicador == "IPCA").limit(100).collect()
 - Serviços OData: Varia; consulte documentação BCB para endpoints específicos
 
 ### P: Posso buscar dados de forma assíncrona?
-**R:** Sim! Todos os módulos têm métodos `async_get()` ou similares. Use-os para requisições concorrentes:
+**R:** Sim. SGS e currency oferecem `async_get()`, e os endpoints OData oferecem `async_get()` e `async_collect()`. Feche o cliente assíncrono ao final de aplicações de longa duração:
 ```python
 import asyncio
-from bcb import sgs
+from bcb import http, sgs
 
 async def main():
-    results = await asyncio.gather(
-        sgs.async_get(1),  # SELIC
-        sgs.async_get(433),  # IPCA
-    )
+    try:
+        results = await asyncio.gather(
+            sgs.async_get(1),  # SELIC
+            sgs.async_get(433),  # IPCA
+        )
+        return results
+    finally:
+        await http.aclose_async_client()
 
 asyncio.run(main())
 ```
@@ -162,7 +166,7 @@ logger.setLevel(logging.DEBUG)
 - Limites de requisições: APIs BCB podem ter limites; implemente backoff se necessário
 - Cache: Cache de moedas persiste em memória; limpe se atualizações de dados importarem
 - Pool de conexões: Usa httpx com connection pooling por padrão
-- API Assíncrona: Use métodos async para comportamento verdadeiramente não-bloqueante
+- API Assíncrona: use métodos async para comportamento verdadeiramente não-bloqueante e chame `await bcb.http.aclose_async_client()` no encerramento de aplicações assíncronas longas
 
 ### P: Como contribuo ou reporto problemas?
 **R:** Visite o [repositório GitHub](https://github.com/wilsonfreitas/python-bcb) para:
@@ -171,6 +175,14 @@ logger.setLevel(logging.DEBUG)
 - Enviar pull requests
 - Ver documentação
 
+### P: Como gero a documentação localmente?
+**R:** As dependências de documentação ficam no grupo `docs` do `uv`:
+```shell
+uv run --group docs sphinx-build -b html docs docs/_build/html
+```
+
+A saída HTML é gerada em `docs/_build/html`. Edite os arquivos fonte em `docs/`; não edite os arquivos gerados em `docs/_build`.
+
 ### P: Onde encontro documentação mais detalhada?
 **R:**
 - [Documentação de API](https://wilsonfreitas.github.io/python-bcb/)

diff --git a/bcb/currency.py b/bcb/currency.py
@@ -660,12 +660,12 @@ def get(
         Códigos das moedas padrão ISO. O código de uma única moeda que
         retorna uma série temporal univariada e uma lista de códigos
         retorna uma série temporal multivariada.
-    start : str, int, date, datetime, Timestamp
-        Data de início da série.
-        Interpreta diferentes tipos e formatos de datas.
-    end : string, int, date, datetime, Timestamp
-        Data de início da série.
-        Interpreta diferentes tipos e formatos de datas.
+    start : str, date, datetime or bcb.utils.Date
+        Data de início da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
+    end : str, date, datetime or bcb.utils.Date
+        Data final da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
     side : {"ask", "bid", "both"}, default "ask"
         Define se a série retornada vem com os ``ask`` prices,
         ``bid`` prices ou ``both`` para ambos.
@@ -899,10 +899,12 @@ async def async_get(
     ----------
     symbols : str, List[str]
         Códigos das moedas padrão ISO
-    start : str, int, date, datetime, Timestamp
-        Data de início da série
-    end : string, int, date, datetime, Timestamp
-        Data final da série
+    start : str, date, datetime or bcb.utils.Date
+        Data de início da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
+    end : str, date, datetime or bcb.utils.Date
+        Data final da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
     side : {"ask", "bid", "both"}
         ``'ask'``, ``'bid'`` ou ``'both'``
     groupby : {"symbol", "side"}

diff --git a/bcb/sgs/__init__.py b/bcb/sgs/__init__.py
@@ -291,12 +291,12 @@ def get(
 
         Com códigos numéricos é interessante utilizar os nomes com os códigos
         para definir os nomes nas colunas das séries temporais.
-    start : str, int, date, datetime, Timestamp
-        Data de início da série.
-        Interpreta diferentes tipos e formatos de datas.
-    end : string, int, date, datetime, Timestamp
-        Data final da série.
-        Interpreta diferentes tipos e formatos de datas.
+    start : str, date, datetime or bcb.utils.Date
+        Data de início da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
+    end : str, date, datetime or bcb.utils.Date
+        Data final da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
     last : int
         Retorna os últimos ``last`` elementos disponíveis da série temporal
         solicitada. Se ``last`` for maior que 0 (zero) os argumentos ``start``
@@ -371,12 +371,12 @@ def get_json(
 
     code : int
         Código da série temporal
-    start : str, int, date, datetime, Timestamp
-        Data de início da série.
-        Interpreta diferentes tipos e formatos de datas.
-    end : string, int, date, datetime, Timestamp
-        Data final da série.
-        Interpreta diferentes tipos e formatos de datas.
+    start : str, date, datetime or bcb.utils.Date
+        Data de início da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
+    end : str, date, datetime or bcb.utils.Date
+        Data final da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
     last : int
         Retorna os últimos ``last`` elementos disponíveis da série temporal
         solicitada. Se ``last`` for maior que 0 (zero) os argumentos ``start``
@@ -420,10 +420,12 @@ async def async_get_json(
     ----------
     code : int
         Código da série temporal
-    start : str, int, date, datetime, Timestamp, optional
-        Data de início da série
-    end : string, int, date, datetime, Timestamp, optional
-        Data final da série
+    start : str, date, datetime or bcb.utils.Date, optional
+        Data de início da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
+    end : str, date, datetime or bcb.utils.Date, optional
+        Data final da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
     last : int
         Retorna os últimos ``last`` elementos disponíveis
 
@@ -480,10 +482,12 @@ async def async_get(
     ----------
     codes : {int, List[int], List[str], Dict[str:int]}
         Código(s) da série temporal
-    start : str, int, date, datetime, Timestamp, optional
-        Data de início da série
-    end : string, int, date, datetime, Timestamp, optional
-        Data final da série
+    start : str, date, datetime or bcb.utils.Date, optional
+        Data de início da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
+    end : str, date, datetime or bcb.utils.Date, optional
+        Data final da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
     last : int
         Retorna os últimos ``last`` elementos disponíveis
     multi : bool

diff --git a/bcb/sgs/regional_economy.py b/bcb/sgs/regional_economy.py
@@ -219,12 +219,12 @@ def get_non_performing_loans(
     mode (str): O tipo de inadimplência. Pode ser "PF" (pessoas físicas),
                 "PJ" (pessoas jurídicas), "total" ou "all"
                 (inadimplência total).
-    start : str, int, date, datetime, Timestamp
-        Data de início da série.
-        Interpreta diferentes tipos e formatos de datas.
-    end : string, int, date, datetime, Timestamp
-        Data final da série.
-        Interpreta diferentes tipos e formatos de datas.
+    start : str, date, datetime or bcb.utils.Date
+        Data de início da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
+    end : str, date, datetime or bcb.utils.Date
+        Data final da série. Strings usam o formato ``YYYY-MM-DD``;
+        ``'today'`` e ``'now'`` também são aceitos.
     last : int
         Retorna os últimos ``last`` elementos disponíveis da série temporal
         solicitada. Se ``last`` for maior que 0 (zero) os argumentos ``start``

diff --git a/docs/async.rst b/docs/async.rst
@@ -77,12 +77,20 @@ Busca taxas de câmbio de forma assíncrona com a mesma interface que a versão
 .. code-block:: python
 
     import asyncio
-    from bcb import currency
+    from bcb import currency, http
 
     async def main():
-        # Buscar taxas de câmbio
-        usd = await currency.async_get('USD', start='2024-01-01', end='2024-12-31')
-        print(usd.head())
+        try:
+            # Buscar múltiplas taxas de câmbio em paralelo
+            rates = await currency.async_get(
+                ['USD', 'EUR'],
+                start='2024-01-01',
+                end='2024-12-31',
+                side='both',
+            )
+            print(rates.head())
+        finally:
+            await http.aclose_async_client()
 
     asyncio.run(main())
 
@@ -259,4 +267,4 @@ Veja Também
 * :ref:`SGS` — Documentação completa do módulo SGS
 * :ref:`Conversor de Moedas` — Documentação do módulo currency
 * :ref:`OData` — Documentação do cliente OData
-* `asyncio — asyncpython <https://docs.python.org/3/library/asyncio.html>`_
+* `asyncio — documentação Python <https://docs.python.org/3/library/asyncio.html>`_
diff --git a/docs/currency.rst b/docs/currency.rst
@@ -15,7 +15,7 @@ API OData de Moedas
 
 __ documentacao_
 
-A classe :py:class:`bcb.PTAX` retorna cotações de moedas os obtidas a partir da `API de Moedas`__ do BCB.
+A classe :py:class:`bcb.PTAX` retorna cotações de moedas obtidas a partir da `API de Moedas`__ do BCB.
 Esta implementação é mais estável que a do :ref:`Conversor de Moedas`.
 
 .. ipython:: python
@@ -47,7 +47,7 @@ são preenchidos com 0 para ter 2 dígitos.
 .. ipython:: python
 
     ptax.describe('CotacaoMoedaPeriodo')
-    
+
     ep = ptax.get_endpoint('CotacaoMoedaPeriodo')
     (ep.query()
        .parameters(moeda='AUD',
@@ -58,7 +58,7 @@ são preenchidos com 0 para ter 2 dígitos.
 Conversor de Moedas
 -------------------
 
-O módulo :py:mod:`bcb.currency` obtem dados de moedas do conversor de moedas do Banco Central através de webscraping.
+O módulo :py:mod:`bcb.currency` obtém dados de moedas do conversor de moedas do Banco Central através de webscraping. Os parâmetros ``start`` e ``end`` aceitam strings ``YYYY-MM-DD``, ``datetime.date``, ``datetime.datetime`` ou :py:class:`bcb.utils.Date`.
 
 .. ipython:: python
 
@@ -103,6 +103,6 @@ retornado um ``dict`` mapeando símbolo ISO → CSV string.
         f.write(raw)
 
 O CSV retornado usa ponto-e-vírgula como separador, datas no formato ``DDMMYYYY`` e vírgula
-como separador decimal — exatamente como devolvido pela API PTAX do BCB.
+como separador decimal — exatamente como devolvido pelo serviço de câmbio do BCB.
 O comportamento padrão (retorno de DataFrame) é mantido quando o parâmetro não é informado.
 
diff --git a/docs/expectativas.rst b/docs/expectativas.rst
@@ -91,9 +91,11 @@ ordenando colunas e selecionando as colunas na saída.
 
 .. ipython:: python
 
+    from datetime import date
+
     (ep.query()
      .filter(ep.Indicador == 'IPCA', ep.DataReferencia == 2023)
-     .filter(ep.Data >= '2022-01-01')
+     .filter(ep.Data >= date(2022, 1, 1))
      .filter(ep.tipoCalculo == 'C')
      .select(ep.Data, ep.Media, ep.Mediana)
      .orderby(ep.Data.desc())

diff --git a/docs/odata.rst b/docs/odata.rst
@@ -118,18 +118,18 @@ Quero obter os 10 dias em 2023 que apresentam as maiores médias transacionadas
 
 Para executar essa query utilizo o método ``select`` passando as propriedades Data e Media,
 encadeio o método ``filter`` filtrando a propriedade Data maiores que 2023-01-01, e note
-que aqui utilizo um objeto ``datetime``, pois na descrição do *endpoint* ``PixLiquidadosAtual``
-a propriedade Data é do tipo ``datetime``.
+que aqui utilizo um objeto ``date``; objetos ``datetime`` também são aceitos. Na descrição do *endpoint* ``PixLiquidadosAtual``,
+a propriedade Data aparece como ``datetime`` porque representa um campo OData ``Edm.Date``.
 Sigo com o método ``orderby`` passando a propriedade média e indicando que a ordenação é decrescente e concluo com
 o método ``limit`` para obter os 10 primeiros registros.
 Na última linha executo o método ``collect`` que executa a consulta e retorna um DataFrame com os resultados.
 
 .. ipython:: python
 
-    from datetime import datetime
+    from datetime import date
     (ep.query()
         .select(ep.Data, ep.Media)
-        .filter(ep.Data >= datetime(2023, 1, 1))
+        .filter(ep.Data >= date(2023, 1, 1))
         .orderby(ep.Media.desc())
         .limit(5)
         .collect())
@@ -145,7 +145,7 @@ mas não a executa.
 
     (ep.query()
         .select(ep.Data, ep.Media)
-        .filter(ep.Data >= datetime(2023, 1, 1))
+        .filter(ep.Data >= date(2023, 1, 1))
         .orderby(ep.Media.desc())
         .limit(5)
         .show())
@@ -189,7 +189,7 @@ Mais filtros podem ser adicionados ao método ``filter``, e também podemos anin
 
     query = (ep.query()
                .filter(ep.Indicador == 'IPCA', ep.DataReferencia == 2023)
-               .filter(ep.Data >= '2022-01-01')
+               .filter(ep.Data >= date(2022, 1, 1))
                .filter(ep.tipoCalculo == 'C')
                .limit(5))
     query.show()
@@ -199,18 +199,17 @@ Todos os filtros estão no atributo ``$filter`` da consulta e são concatenados
 
 É necessário conhecer o tipo da propriedade para saber como passar o objeto para a consulta.
 Os tipos de propriedade podem ser: str, float, int e datetime.
-Por exemplo, na API do PIX, a propriedade ``Data`` é do tipo ``datetime`` e por isso é necessário passar um
-objeto ``datetime`` para o método ``filter``.
+Para propriedades OData ``Edm.Date``, passe um objeto ``datetime.date`` ou ``datetime.datetime`` para o método ``filter``; strings de data não são convertidas automaticamente pelo construtor de filtros.
 
 .. ipython:: python
 
     ep = pix.get_endpoint("PixLiquidadosAtual")
     (ep.query()
-       .filter(ep.Data >= datetime(2023, 1, 1))
+       .filter(ep.Data >= date(2023, 1, 1))
        .limit(5)
        .show())
 
-O objeto ``datetime`` é formatado como data na consulta, note que não há aspas na definição da data no filtro.
+O objeto ``date`` ou ``datetime`` é formatado como data na consulta; note que não há aspas na definição da data no filtro.
 
 Ordenando os Dados
 ^^^^^^^^^^^^^^^^^^
@@ -284,7 +283,7 @@ Esse método é importante para investigar as consultas na API de forma rápida.
 
     ep = pix.get_endpoint("PixLiquidadosAtual")
     (ep.query()
-       .filter(ep.Data >= datetime(2023, 1, 1))
+       .filter(ep.Data >= date(2023, 1, 1))
        .limit(5)
        .collect())
 
@@ -419,10 +418,10 @@ O comportamento padrão (retorno de DataFrame) é mantido quando o parâmetro n
 Classe ODataAPI
 ---------------
 
-O portal de Dados Abertos to Banco Central apresenta diversas APIs OData, são
+O portal de Dados Abertos do Banco Central apresenta diversas APIs OData, são
 dezenas de APIs disponíveis.
 A URL com metadados de cada API pode ser obtida no `portal <https://dadosabertos.bcb.gov.br>`_.
-A classe :py:class:`bcb.odata.api.ODataAPI` permite acessar qualquer API Odata de posse da sua URL.
+A classe :py:class:`bcb.odata.api.ODataAPI` permite acessar qualquer API OData de posse da sua URL.
 
 Por exemplo, a API de estatísticas de operações registradas no Selic tem a seguinte URL::
 

diff --git a/docs/sgs.rst b/docs/sgs.rst
@@ -1,10 +1,12 @@
 SGS
 ===
 
-A função :py:func:`bcb.sgs.get` obtem os dados do webservice do Banco Central ,
-interface json do serviço BCData/SGS - 
+A função :py:func:`bcb.sgs.get` obtém os dados do webservice do Banco Central,
+interface JSON do serviço BCData/SGS -
 `Sistema Gerenciador de Séries Temporais (SGS) <https://www3.bcb.gov.br/sgspub/localizarseries/localizarSeries.do?method=prepararTelaLocalizarSeries>`_.
 
+Os parâmetros ``start`` e ``end`` aceitam strings ``YYYY-MM-DD``, ``datetime.date``, ``datetime.datetime`` ou :py:class:`bcb.utils.Date`. Também é possível usar ``last`` para buscar os últimos ``n`` pontos disponíveis.
+
 Exemplos
 --------
 
@@ -70,6 +72,8 @@ O comportamento padrão (retorno de DataFrame) é mantido quando o parâmetro n
 Dados de Inadimplência de Operações de Crédito
 ==============================================
 
+Os modos aceitos são ``PF`` (pessoas físicas), ``PJ`` (pessoas jurídicas) e ``total``; ``all`` é aceito como alias de ``total``. Os locais devem ser todos estados ou todos regiões, sem misturar os dois tipos na mesma chamada.
+
 .. ipython:: python
 
     from bcb.sgs.regional_economy import get_non_performing_loans