@fc/cliente-sgs

Cliente HTTP tipado para a API SGS (Sistema Gerenciador de Séries Temporais) do Banco Central do Brasil (BACEN). Fornece séries de índices de correção monetária e taxas de juros direto da fonte oficial; consumido pelo job de atualização automática de índices do backoffice.

Endpoint

A URL base da API SGS é fixa no pacote — https://api.bcb.gov.br/dados/serie/bcdata.sgs.{codigo}/dados — e não depende de variáveis de ambiente.

Principais séries consultadas

Código SGS	Série
190	IGP-DI mensal (FGV)
189	IGP-M mensal (FGV)
7478	IPCA-E (IBGE)
204	Juros da poupança
4390	SELIC acumulada no mês
29541	Fator da Taxa Selic (Lei 14.905/2024)
29543	Taxa Legal (Lei 14.905/2024)
7811	TR mensal

API

import { CodigoSgs } from '@fc/cliente-sgs/CodigoSgs'
import { consultarSgs } from '@fc/cliente-sgs/consultarSgs'

const controlador = new AbortController()

// Sem `consultas`, busca a lista padrão de séries.
const { dados, erros } = await consultarSgs({
  consultas: [CodigoSgs.Selic, CodigoSgs.FatorSelic],
  dataInicial: '01/2020',
  dataFinal: '12/2024',
  signal: controlador.signal, // opcional
})

// dados[CodigoSgs.Selic] -> Array<{ competencia: string, valor: number, fonte: string }>
// erros -> Array<{ consulta, tipo, mensagem, competencia? }>

A função recusa datas não reconhecidas e intervalos invertidos. Valores ou linhas inválidos da resposta oficial são omitidos de dados e registrados em erros; eles nunca são convertidos em zero. Falhas transitórias usam até três tentativas dentro de um orçamento total de 30 segundos, respeitando Retry-After. O corpo de resposta é limitado a 2 MiB e a chamada pode ser cancelada com AbortSignal.

Erros de uma série não descartam as demais séries concluídas. A função retorna Promise e é consumida pelo job de atualização automática de índices do backoffice.

Como consumir

O pacote não tem barrel raiz: @fc/cliente-sgs não resolve. Cada módulo é publicado por subpath, e o consumidor importa o arquivo que declara o símbolo.

Subpath	O que exporta
@fc/cliente-sgs/consultarSgs	consultarSgs
@fc/cliente-sgs/CodigoSgs	CodigoSgs
@fc/cliente-sgs/tipos	DadoSerieSgs, ErroConsultaSgs, ParametrosConsultaSgs, ResultadoConsultaSgs, TipoErroConsulta

constantes, consultar, formatarData e gerarUrl são detalhe de implementação e não são publicados.

Desenvolvimento

pnpm test:run
pnpm test:cov

Os testes usam respostas locais controladas e não acessam a internet.

Instalação (monorepo)

// package.json
{ "dependencies": { "@fc/cliente-sgs": "workspace:*" } }