# Mercado Livre → n8n → Postgres → Power BI

Starter kit de monitoramento de preços concorrentes, versão 2026-10-21.
Comece pelo artigo: https://geckoapi.com.br/api-dados-publicos-para-bi/

## Arquivos

- `workflow.json`: importe no n8n. Não contém credenciais. Agendamento desativado.
- `schema.sql`: tabelas, ingestão atômica e views para PostgreSQL.
- `normalize.js`: código incorporado no node “Validar e normalizar”.
- `sample-data.csv`, `.json`, `.sql`: seis registros inteiramente fictícios, para demonstração. As URLs DEMO não são anúncios reais e não devem ser consultadas.
- `power-query-sample.pq`: carregar CSV no Power BI sem API ou Postgres.
- `power-query-postgres.pq`: carregar histórico do Postgres.
- `workflow-screenshot.jpg`: captura do workflow importado no n8n.
- `preview-screenshot.jpg`: captura da prévia HTML do dataset.
- `preview.html`: prévia local dos dados e do fluxo; não é um relatório Power BI nem um arquivo PBIX.

## 1. Valide o caso sem gastar créditos

No Power BI Desktop: Transformar dados → Gerenciar parâmetros → Novo parâmetro.
Crie `SampleFilePath` (Texto) com o caminho absoluto de `sample-data.csv`.
Crie uma consulta em branco, abra o Editor Avançado e cole `power-query-sample.pq`.
O CSV usa UTF-8, ponto decimal e datas ISO em UTC. O código usa cultura en-US apenas
para ler números, preservando a apresentação em português no relatório.

Use um gráfico de linhas com captured_at no eixo, product_id na legenda e price
como valor. Na tabela, adicione seller_name, currency, price e price_change_pct.
Para o produto fictício 1, os valores esperados são 100 → 95 → 90 BRL; a última
variação é aproximadamente -5,26% em relação a 95. O último preço do produto 2
é nulo: ele deve aparecer como ausência, nunca como zero. Não some preços entre
produtos e não preencha valores desconhecidos automaticamente.

## 2. Prepare seu Postgres

Use um banco seu, PostgreSQL 17 ou compatível. Execute:

    psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f schema.sql

Opcional, somente em banco de teste: execute `sample-data.sql`. Não misture as
linhas fictícias com dados de produção. A ingestão recebe JSON parametrizado,
insere a execução e seus snapshots na mesma transação e ignora duplicatas pela
chave (run_id, source_url, seller_key). Reexecutar o mesmo JSON não duplica dados;
uma nova consulta à API tem outro executionId e cria outro snapshot.

Use credenciais distintas: ingestão no n8n e leitura no Power BI. Ao criar seu
usuário leitor, conceda USAGE no schema gecko_monitor e SELECT nas views
price_history e latest_prices. Armazene credenciais nas ferramentas, não nos arquivos.

## 3. Importe e configure o n8n

No menu do editor, use Import from File e selecione `workflow.json`.

1. Em “Configuração”, troque `keyword` por uma busca relevante.
2. Crie uma credencial Header Auth: nome `Authorization`, valor `Bearer SUA_CHAVE`.
3. Selecione essa mesma credencial nos dois nodes HTTP: “Consultar Mercado Livre” e “Repetir uma vez”.
4. Em “Salvar no Postgres”, selecione sua credencial Postgres. Ajuste host, banco,
   usuário, senha e TLS conforme o ambiente. No Docker, localhost aponta para o
   próprio container: use o nome do serviço ou o host acessível na sua rede.
5. Execute manualmente. Verifique `inserted` no último node e consulte:

    SELECT * FROM gecko_monitor.latest_prices ORDER BY captured_at DESC;

O kit consulta apenas a primeira página PLP. Não consulta todos os PDPs nem percorre
o catálogo inteiro. Para uma oferta fixa, escolha a URL e o vendedor, confira
atributos/variante com PDP e adapte a coleta conforme o contrato:
https://geckoapi.com.br/docs/mercadolivre-com-br-pdp/
Uma busca pode incluir produtos, marcas e volumes distintos: não são comparáveis
só porque apareceram para a mesma keyword. A URL de catálogo pode alternar vendedor.

## 4. Conecte o Power BI ao Postgres

Crie parâmetros Texto `Server` (host:porta) e `Database` (nome do banco).
Em uma consulta em branco, cole `power-query-postgres.pq` no Editor Avançado.
Selecione autenticação de banco com o usuário leitor. A consulta lê price_history,
com datas UTC, IDs em texto, moeda explícita e preços decimais. Se preferir uma
foto mais recente por oferta, conecte a view latest_prices separadamente.

Não coloque a chave GeckoAPI no Power Query: só o n8n chama a API. O conector
PostgreSQL do Power BI lê os snapshots persistidos.

## 5. Atualização agendada

Depois de um teste manual válido, habilite o node “Todo dia às 08h” e publique/ative
o workflow. Fuso do workflow: America/Sao_Paulo. A agenda vem desativada para que
importar o arquivo não inicie consumo. Dimensione: buscas × páginas × frequência ×
custo vigente, mais os PDPs selecionados. O kit usa uma keyword e uma página.

No Power BI Service, publique seu relatório e configure as credenciais e a conexão
do modelo semântico. Se o Postgres estiver em rede privada/local, instale/configure
um gateway que alcance esse host. Configure refresh após a coleta (por exemplo,
08h30 para coleta às 08h), considerando a duração real. Confira o histórico de
refresh e mostre MAX(captured_at) no relatório: refresh do Power BI não dispara
uma coleta GeckoAPI. Limites de frequência dependem da licença/capacidade.

## Erros e retentativas

- 400/401/403: execução falha; corrija payload, chave ou acesso antes de repetir.
- 429 e 500/502/503/504: uma única retentativa, com espera mínima de 10 segundos e
  respeito a Retry-After (segundos ou data HTTP). Depois disso, falha visível.
- Timeout/rede: o node HTTP para. Inspecione antes de repetir para evitar chamadas
  pagas duplicadas; não há repetição ilimitada de erro de transporte.
- Lista vazia: registra execução `empty`, sem inventar preço ou ruptura.
- notFound/data:null: registra `not_found`, sem snapshots.
- Preço ausente: mantém null. Moeda diferente de BRL, URL inválida ou contrato
  inesperado: falha antes do banco.
- Falha no Postgres: a transação não grava parte do lote. Corrija a conexão e
  reexecute com os dados preservados no n8n; não é necessário refazer a coleta.
- Cadastre um workflow de erro no n8n (Error Trigger) se precisar de avisos.
  O kit não envia emails ou mensagens automaticamente. Revise execuções com erro.

Uma resposta de sucesso não promete que o preço permanecerá disponível. Preserve
source_url, captured_at e execução para auditar. Não use zero como estado de falha.

## Validação e limites

Workflow importado e executado em n8n 2.44.5 e PostgreSQL 17, tanto com uma chamada real à API quanto com replay de resposta
real de Mercado Livre capturada em 21/10/2026. Testes cobrem sucesso, replay sem
duplicata, 429 seguido de sucesso, 401, busca vazia, notFound, moeda inesperada,
preço nulo e contrato inválido. A chamada real PLP e o PDP selecionado também foram
verificados. Testes de falhas usam um servidor local; não provocam erros em produção.

Os dois arquivos Power Query passaram no parser M oficial da Microsoft. O código usa o conector oficial PostgreSQL. Power BI Desktop
não está disponível no ambiente Linux usado nesta validação: a abertura do relatório
e o refresh no Service precisam ser validados no seu ambiente. Não inclui PBIX,
credenciais, dados privados de clientes ou execução automática em produção.

Referências:
- https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/
- https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.postgres/
- https://learn.microsoft.com/en-us/power-query/connectors/postgresql
- https://learn.microsoft.com/en-us/power-bi/connect-data/refresh-scheduled-refresh