Escolha o conjunto de dados antes do endpoint
O portal de Dados Abertos do Banco Central publica conjuntos com formatos e interfaces próprios. Para séries temporais macroeconômicas, a API do Sistema Gerenciador de Séries Temporais (SGS) oferece consulta por código de série e intervalo. Confirme no catálogo a série, unidade, periodicidade, defasagem, política de atualização e limites vigentes; códigos diferentes podem representar conceitos e escalas diferentes.
Não assuma que um dado está disponível em tempo real nem que todos os conjuntos usam a mesma interface. Registre a fonte e o momento da coleta junto aos dados armazenados para permitir auditoria e reprocessamento.
Consuma HTTP por meio de um cliente tipado
Registre um HttpClient tipado com IHttpClientFactory, mantenha a URL de serviço controlada pela aplicação e passe somente identificadores e intervalos validados. O exemplo representa a API SGS clássica; confirme os parâmetros e limites para o conjunto selecionado antes de publicar:
builder.Services.AddHttpClient<BacenSgsClient>(client =>
{
client.BaseAddress = new Uri("https://api.bcb.gov.br/dados/serie/");
client.Timeout = TimeSpan.FromSeconds(10);
});
public sealed record DadoSerie(string Data, string Valor);
public async Task<IReadOnlyList<DadoSerie>> ConsultarAsync(
int codigo, DateOnly inicio, DateOnly fim, CancellationToken cancellationToken)
{
if (codigo <= 0)
throw new ArgumentOutOfRangeException(nameof(codigo));
if (fim < inicio)
throw new ArgumentOutOfRangeException(nameof(fim));
var inicial = Uri.EscapeDataString(inicio.ToString("dd/MM/yyyy"));
var final = Uri.EscapeDataString(fim.ToString("dd/MM/yyyy"));
var caminho = $"bcdata.sgs.{codigo}/dados?formato=json&dataInicial={inicial}&dataFinal={final}";
return await _http.GetFromJsonAsync<List<DadoSerie>>(caminho, cancellationToken)
?? throw new InvalidOperationException("A resposta do BACEN não continha uma lista.");
}O trecho omite construtor e declaração do campo _http. Trate separadamente respostas HTTP não exitosas, JSON inválido, timeout e cancelamento. Não transforme erros de integração em lista vazia: isso mascara uma falha como se não houvesse observações.
Interprete datas e valores com o contrato da fonte
Na interface SGS, respostas tradicionais trazem data e valor como texto. Faça parsing explícito e valide a cultura e o formato observados no contrato: por exemplo, datas no formato dia/mês/ano e valores decimais numéricos. Converta para tipos de domínio, rejeite linhas inválidas de forma visível e teste casos de separador decimal, vazio e ausência de observações. Preserve a data efetiva da observação, não apenas a hora de consulta.
Confirme também se a taxa vem em percentual, pontos percentuais, índice ou outra unidade. Uma conversão equivocada pode produzir resultados formalmente válidos e financeiramente errados.
Cache, limites e resiliência
Não consulte a fonte a cada requisição do usuário se a série não muda nessa frequência. Cacheie por código, intervalo, formato e versão do contrato; defina TTL conforme a periodicidade e o atraso de publicação. Para séries recentes, use uma janela de atualização controlada e evite tratar cache antigo como informação atual sem indicar a data.
Limite timeouts e repita apenas leituras idempotentes em erros transitórios, com poucas tentativas, backoff e jitter. Não repita erro de validação ou resposta permanente, e evite retries em várias camadas. Veja princípios de resiliência e políticas com Polly no .NET.
Operação, observabilidade e testes
Registre duração, status HTTP, série consultada e intervalo, evitando logar payloads completos sem necessidade. Métricas úteis incluem falhas, latência, idade da observação mais recente e quantidade de linhas retornadas. Não inclua dados pessoais nem transforme códigos de série arbitrários em labels de alta cardinalidade.
Teste parsing e validações sem rede, e use servidor HTTP falso em testes para validar URL, cancelamento e cenários de erro. Mantenha uma verificação de contrato e acompanhe avisos oficiais do catálogo: dependências externas também evoluem.