bcb_deflacionar
Convert nominal BCB series to real values in constant currency by discounting inflation. Compare amounts from different periods in today's purchasing power.
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 | |
| 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). |