bcb_deflacionar
Convert nominal Brazilian Central Bank series into real (inflation-adjusted) values using IPCA, INPC, or IGP-M. Ideal for comparing monetary amounts across different periods; returns both nominal and real values with deflation factors.
Instructions
Converte uma série NOMINAL do BCB em valores REAIS (moeda constante), descontando a inflação do período — a diferença entre 'o salário mínimo subiu 46% desde 2020' e 'o salário mínimo subiu 5% em poder de compra'. Quando usar: sempre que valores em reais de épocas diferentes forem comparados. Quando NÃO usar: para séries que já são percentuais, índices ou taxas (deflacionar uma taxa de juros não significa nada); para a série nominal crua use bcb_serie_valores. Índice: ipca (padrão), inpc ou igpm. Base: mesBase no formato yyyy-MM define em reais de que mês os valores são expressos; sem ele, usa o último mês publicado do índice ('em reais de hoje'). Retorna: serie, deflator (índice, código, cobertura), base, periodo, dados (cada ponto com valorNominal, valorReal e fator), variacao (a percentual nominal ao lado da real no mesmo período), derivacao e avisos. Limite da fonte: o SGS não publica número-índice, então o índice é reconstruído compondo as variações mensais — reconstrução conferida contra a própria fonte (diferença máxima de 0,0052 ponto percentual contra o acumulado oficial em 12 meses). Observação fora da cobertura do índice recebe valorReal: null, nunca um valor inventado; como o índice sai com defasagem, o mês corrente costuma cair nesse caso. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna isError: true com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em structuredContent (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| codigo | Yes | Código da série NOMINAL a deflacionar (ex.: 1619 para salário mínimo) | |
| indice | No | Índice de preços usado como deflator: IPCA (433), INPC (188) ou IGP-M (189) | ipca |
| mesBase | No | Mês em cujos preços os valores serão expressos, no formato yyyy-MM. Sem ele, usa o último mês publicado do índice — isto é, 'em reais de hoje'. | |
| agregacao | No | Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano. | ultimo |
| dataFinal | Yes | Data final (yyyy-MM-dd ou dd/MM/yyyy) | |
| frequencia | No | Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes. | |
| dataInicial | Yes | Data inicial (yyyy-MM-dd ou dd/MM/yyyy) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base | Yes | Mês em cujos preços os valores reais estão expressos | |
| dados | Yes | Observações com o valor publicado e o valor em moeda constante | |
| serie | Yes | Identificação da série nominal | |
| avisos | No | Ressalvas sobre cobertura do índice ou mês base substituído | |
| periodo | Yes | ||
| chunking | No | Presente quando a consulta foi fatiada em várias requisições à origem, por causa do limite de 10 anos por janela em séries diárias. As fatias são fundidas e ordenadas antes de responder. | |
| deflator | Yes | Índice de preços usado e o intervalo que ele cobre | |
| variacao | Yes | Variação percentual do período em moeda corrente ao lado da variação em moeda constante — é a comparação que a tool existe para entregar. `null` quando há menos de duas observações deflacionadas. | |
| derivacao | Yes | Origem dos números calculados: o que é derivado, por qual motor e com quais convenções | |
| provenance | Yes | Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença | |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) | |
| harmonizacao | No | Presente quando `frequencia` foi informada: descreve a reamostragem aplicada. Valor DERIVADO — calculado por este servidor, não publicado pelo Banco Central. | |
| janelaAplicada | No | Presente quando o período pedido estava aberto numa série diária e o servidor aplicou uma janela própria (a origem recusa janela aberta em série diária com HTTP 406). |