IBGE (SIDRA) — conector

Estado: Preview — comportamento pode mudar; sem SLA. Métricas de nuvem (custo faturado, latência): NÃO MEDIDO.

Leia antes: ../conectores.md (mapa de estados) e fichas.md (índice das fichas).

O que é#

Lê um agregado do SIDRA (IPCA, PNAD, PIB…) por variável, período e localidade e a lista de municípios do IBGE, e carrega na camada Bronze.

Modos de ingestão suportados:

• Nós buscamos — Nós buscamos os dados na sua fonte.

Para que serve#

Trazer os dados de IBGE (SIDRA) para o seu datalake e disponibilizá-los às camadas Bronze/Silver/Gold, aos modelos de BI e ao wizard de perguntas em linguagem natural.

Quando usar / quando não usar#

Use quando você precisa consolidar esta fonte no datalake de forma agendada, com isolamento por workspace.

Lembre-se de que, em Preview, a liberação geral depende de credencial real e de uma execução controlada, validada manualmente pela nossa equipe.

Plano e permissões#

• Plano: núcleo do produto (conectores fazem parte de todos os planos; o limite é o número de fontes do plano).
• Acesso: exige workspace ativo — com a assinatura em atraso, suspensa ou cancelada, a execução fica bloqueada.
• Desligamento: a execução de ingestão pode ser desligada temporariamente (manutenção ou incidente). Quando isso acontece, a tela informa que o recurso está indisponível no momento.

Pré-requisitos#

• Nenhuma credencial: os dados são públicos.
• Não precisa de credencial: as APIs de agregados (SIDRA) e de localidades do IBGE são públicas. Informe o agregado (número da tabela no SIDRA, ex.: 1419 IPCA), a variável (ex.: 63 variação mensal), os períodos (ex.: -12 = últimos 12) e as localidades (ex.: N1[all] = Brasil, N3[all] = todas as UFs). A lista de municípios não depende desses campos.

Credenciais#

Forma de autenticação: Sem credencial — dados públicos.

Este conector não exige segredos próprios (modo de upload / sem credencial na plataforma).

Segredos nunca são reexibidos e passam pela redação em todo erro/log (token cru, URL-encoded e em JSON).

Campos do formulário#

Passo a passo#

1. No menu Dados → Conexões, use Nova conexão.
2. Escolha IBGE (SIDRA) no catálogo.
3. Preencha os campos do formulário (veja a tabela acima).
4. Use Testar conexão. O resultado vem separado em Conectividade, Autenticação e Listagem/leitura — cada um com OK, Falhou, Não se aplica ou Não testado. Capacidade sem teste próprio para este conector aparece como Não se aplica, e Não se aplica nunca conta como sucesso.
5. Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
6. No cartão da conexão, use Montar extração (ou vá em Orquestração → Pipelines e use Conectar fonte). O pipeline aponta para a conexão salva — a credencial não é copiada.
7. Na revisão, Publicar (agenda desligada) cria a versão 1 sem executar nada. Depois, Ativar agenda e Executar agora são ações separadas.

Exemplo — teste de conexão#

Configuração de exemplo (todos os valores são fictícios; segredos aparecem mascarados):

# Exemplo sintético (valores fictícios — não são credenciais reais)
agregado = 1419
variavel = 63
periodos = -12
localidades = N1[all]

Resultado esperado#

O Testar conexão retorna a lista de tabelas/recursos descobertos. Após a primeira carga, as linhas aparecem na camada Bronze do seu workspace, prontas para o pipeline.

Limites e custos#

• Paginação: teto duro por execução (default 10.000 páginas / 5.000.000 linhas); guarda anti-loop.
• Carga SaaS: default batchSize 5.000, maxRows 200.000 por recurso.
• Volume estimado: ~0.02 GB/mês (estimativa de catálogo, não medição).
• Custo: a extração em si não é cobrada pela plataforma; a carga Bronze consome processamento do datalake (cobrável). Custo faturado real de nuvem = NÃO MEDIDO.

Segurança#

• Escopo por workspace: cada cliente lê e escreve só no seu próprio datalake (<prefixo>_bronze / _silver / _gold); nunca há vazamento entre workspaces.
• Segredos cifrados: material sensível é cifrado com AES-256-GCM antes de ser gravado. O cofre externo de credenciais é opcional e ligado por conexão; sem ele, o valor cifrado fica no banco. Trocar o valor aqui NÃO revoga a credencial na origem.
• Redaction: todo erro/log passa pela redação de segredos (cru, URL-encoded e em JSON).
• Produção não finge: um caminho que cairia em mock aciona a guarda de produção (falha explícita em vez de simular sucesso).

Erros comuns#

• Credencial recusada (401/403) — o provedor não aceitou a credencial: expirada, revogada ou sem a permissão necessária. Reconecte a fonte (a fonte e o histórico são preservados; não recrie a fonte).
• Limite de requisições (429) — o provedor pediu para esperar. A extração respeita Retry-After e retenta; se repetir, aguarde e reduza a frequência da agenda.
• Recurso não encontrado — confira o identificador do recurso (conta, objeto, relatório) e as permissões concedidas.
• Cursor de paginação travado — a extração encerra quando o cursor da API não avança (guarda anti-loop). Se acontecer em execuções seguidas, abra um chamado com o suporte informando o conector e o recurso.
• Caminho de registros vazio — a resposta chegou sem registros no lugar esperado. Confira o recurso selecionado e os filtros (período, conta, status) antes de assumir que não há dados.

Diagnóstico#

• Use Testar conexão para isolar problemas de credencial/rede antes de agendar.
• Acompanhe as execuções na observabilidade por conector (taxa de erro, p50/p95, freshness).
• Uma mudança de esquema na origem é sinalizada pelo schema drift (coluna nova = info; coluna removida/tipo mudado = atenção).

Relacionados#

• ../conectores.md — catálogo de conectores por estado
• ../ingestao-incremental-backfill.md — full, incremental por watermark, backfill e checkpoint
• ../pipeline-medalhao.md — camadas Bronze/Silver/Gold e qualidade
• ../agendamento-retry-dlq.md — agendamento, retry/backoff e DLQ
• ../custo-limites-seguranca.md — custo, tetos e segurança por workspace

Última revisão: 2026-10-04. Ficha gerada automaticamente do catálogo de conectores do produto.