Inteligência de preços por EAN: como funciona e quando usar

Você tem o código de barras (EAN) de um produto. Pergunta: por quanto ele está sendo vendido agora em supermercados, farmácias e marketplaces espalhados pelo Brasil? E quanto ele custava há 30 dias?

Essa é uma pergunta cara de responder bem. Cada varejista tem seu próprio site, suas próprias unidades de embalagem (kg, g, ml, unidade, fardo de 6), suas promoções relâmpago e seus erros de cadastro. Cruzar tudo isso à mão é inviável.

A API de Inteligência de Preços por EAN do Falcon Data Hub resolve esse problema entregando, em uma única chamada, o panorama completo de preços daquele produto no mercado brasileiro — com normalização, ranking por loja e preço sugerido calculado por média ponderada de recência.

O problema real que essa API resolve

Quem precisa de preços de varejo agregados quase sempre cai em um dos cenários a seguir:

• E-commerce / repricing: você vende um produto e quer saber se está acima ou abaixo da média do mercado, em tempo quase-real, para ajustar margem.
• Comparador de preços: você está montando um app/site que mostra "onde comprar mais barato" para o consumidor final.
• Fabricante / indústria: você produz o item e quer auditar se as redes parceiras estão respeitando o preço sugerido (MAP / RPM).
• Procurement / B2B: sua empresa compra em volume e precisa saber o preço justo de uma SKU antes de fechar contrato.
• BI / dashboard interno: você quer monitorar uma cesta de SKUs ao longo do tempo, com alertas quando algo varia além de X%.

Construir do zero significa: rodar scrapers em dezenas de varejistas, lidar com mudança de layout, captcha, IP block, agendar coletas, normalizar unidades, agregar e expor uma API consistente. É um produto inteiro só pra resolver o insumo do seu produto real.

O que a API retorna

Uma chamada simples ao endpoint:

curl https://datahub.falcon-server.com.br/private/v1/products/ean/7891000100103 \
  -H "Authorization: Bearer SEU_TOKEN"

Devolve algo como (resposta resumida):

{
  "data": {
    "product": {
      "id": 12345,
      "ean": "7891000100103",
      "name": "Leite Condensado MOÇA 395g",
      "brand": "Nestlé",
      "category": "Mercearia / Doces",
      "image_url": "https://..."
    },
    "suggested_price": 678,
    "price_range": {
      "min": 599,
      "max": 829,
      "avg": 712
    },
    "by_store": [
      {
        "store": "Supermercado A",
        "slug": "supermercado-a",
        "logo_url": "https://...",
        "region": "SP",
        "min": 599,
        "max": 689,
        "avg": 632,
        "latest": 619,
        "pack_quantity": 1,
        "normalized_price": 1568,
        "normalization_unit": "kg",
        "observations": 14,
        "last_seen": "2026-05-28T11:42:00Z"
      },
      {
        "store": "Supermercado B",
        "region": "RJ",
        "min": 649,
        "max": 749,
        "avg": 697,
        "latest": 689,
        "observations": 9,
        "last_seen": "2026-05-27T22:08:00Z"
      }
    ],
    "observations_count": 47
  }
}

Valores em centavos (suggested_price: 678 = R$ 6,78). Isso evita arredondamento em float, padrão em fintechs e pagamentos.

O que cada campo significa

• suggested_price — média ponderada por recência. Coletas mais novas pesam mais (decaimento exponencial); coletas com mais de 90 dias são descartadas. É o melhor "chute" de preço atual.
• price_range — min / max / avg simples nos últimos 90 dias. Útil para detectar outliers e exibir faixa pro usuário final.
• by_store — agrupamento por varejista (com região quando aplicável). Cada item traz min/max/avg/latest, quantidade observada e timestamp da última coleta.
• normalized_price — preço por unidade base (kg, litro, unidade unitária). Permite comparar produtos vendidos em embalagens diferentes (ex.: leite 395g vs 990g).
• observations_count — quantas coletas de preço você está vendo. Acima de 30 já é estatisticamente confortável; abaixo de 5, trate com cautela.

Histórico completo de preços

Se você precisa do raw — todas as observações dos últimos 90 dias para análises, gráficos ou ML — basta uma segunda chamada:

curl https://datahub.falcon-server.com.br/private/v1/products/12345/prices \
  -H "Authorization: Bearer SEU_TOKEN"

Devolve até 500 observações ordenadas por data, prontas para alimentar gráfico de linha. Cada uma com loja, preço observado, embalagem, região e o observed_at exato.

Quem coleta e como

Os preços vêm de coleta direta nos sites dos varejistas, com normalização e validação automática. Cada observação passa por um pipeline que:

1. Normaliza unidade (kg, g, ml, L, un, fardo) para unidade base.
2. Calcula unit_price_cents real (por kg/litro/unidade), permitindo comparação justa entre embalagens diferentes.
3. Marca o status (approved, pending, etc.). A API pública só devolve approved.
4. Agrega por loja + região para evitar viés geográfico (preço em SP é diferente de preço no Norte).

Se um varejista mudar de layout e a coleta quebrar, você não fica vendo dado velho — a observação para de chegar e o last_seen fica antigo. Você decide se ainda confia.

Casos de uso com código

Caso 1: Repricing em e-commerce

Você tem 800 SKUs no seu marketplace. Quer rodar todo dia de manhã um check de "estou competitivo?".

use Falcon\DataHub\Client;

$client = new Client(env('FALCON_TOKEN'));

foreach ($meusProdutos as $sku) {
    $mercado = $client->productByEan($sku->ean);

    if (!$mercado || $mercado->observations_count < 10) {
        continue; // sem dado suficiente, pula
    }

    $meuPreco = $sku->price_cents;
    $mediaMercado = $mercado->suggested_price;
    $diff = (($meuPreco - $mediaMercado) / $mediaMercado) * 100;

    if ($diff > 5) {
        // Estou >5% acima da média — log para revisão
        Log::warning("SKU {$sku->ean} está {$diff}% acima do mercado");
    } elseif ($diff < -10) {
        // >10% abaixo — pode estar perdendo margem
        Log::info("SKU {$sku->ean} está {$diff}% abaixo, oportunidade de subir preço");
    }
}

Caso 2: Comparador para o consumidor final

import { FalconDataHub } from '@falcon/datahub';

const client = new FalconDataHub({ token: process.env.FALCON_TOKEN! });

async function ondeComprar(ean: string, regiao?: string) {
  const data = await client.productByEan(ean, { region: regiao });

  // Ordena por preço mais recente, asc
  const ranking = data.by_store
    .map((s) => ({
      loja: s.store,
      regiao: s.region,
      preco: s.latest / 100,
      coletado: s.last_seen,
    }))
    .sort((a, b) => a.preco - b.preco);

  return {
    produto: data.product.name,
    preco_sugerido: data.suggested_price / 100,
    onde_comprar: ranking.slice(0, 5),
  };
}

Caso 3: Histórico para gráfico

const historico = await client.productPrices(12345);

// Agrupa por dia e calcula média
const porDia = historico.prices.reduce((acc, p) => {
  const dia = p.observed_at.slice(0, 10);
  if (!acc[dia]) acc[dia] = [];
  acc[dia].push(p.unit_price_cents);
  return acc;
}, {} as Record<string, number[]>);

const serie = Object.entries(porDia).map(([dia, precos]) => ({
  dia,
  media: precos.reduce((a, b) => a + b, 0) / precos.length / 100,
}));

// serie agora alimenta seu gráfico de linha

Limites e dicas de produção

• Cobertura: SKUs de mercearia, bebidas, limpeza, higiene, perecíveis básicos têm boa cobertura. Itens muito de cauda (importados, exclusivos de uma loja) podem ter observations_count baixo — combine com seu próprio dado interno.
• Frescor: o last_seen por loja é o melhor indicador. Se está mais antigo que 48h, trate com peso menor.
• Plano grátis: 10 requests/hora. Suficiente para validação ou consultas pontuais; para repricing de catálogo grande, plano Premium (1.000 req/hora) ou Enterprise.
• Cache local: respostas têm valor estável por algumas horas. Cachear em Redis com TTL de 4–6h é prática comum e reduz consumo de quota.
• Filtragem por região: passar ?region=SP retorna apenas observações daquela UF e nacionais (lojas com presença em todo o país). Útil para precificar por mercado regional.

Por que isso é diferente das alternativas

Procurar "API de preços supermercado Brasil" devolve poucas opções:

• Scrapers caseiros — funcionam até quebrarem, sem SLA, sem suporte.
• Soluções enterprise de monitoramento (Boomerank, Precifica, Sieve) — robustas, mas com preço dimensionado para indústria, mensalidade alta e contrato anual.
• DIY com Selenium / Playwright — você vira responsável por infra, captcha, rotação de IP e manutenção contínua dos seletores.

A API do Falcon entra como caminho do meio: plano grátis para validar, planos pagos sem contrato e API REST consistente. Não é a solução certa para quem precisa de 50 mil SKUs monitorados em tempo real (aí Boomerank ganha), mas cobre confortavelmente o caso de até alguns milhares de SKUs com checagem diária ou de hora em hora.

Onde começar

Crie conta grátis, gere um token e teste com um EAN seu — ou um popular para sentir a profundidade do dado:

# Leite condensado Moça 395g
curl https://datahub.falcon-server.com.br/private/v1/products/ean/7891000100103 \
  -H "Authorization: Bearer SEU_TOKEN"

# Coca-Cola 2L
curl https://datahub.falcon-server.com.br/private/v1/products/ean/7894900011517 \
  -H "Authorization: Bearer SEU_TOKEN"

Se a resposta vier com observations_count confortável e by_store listando lojas reais, você tem o que precisa para começar a montar repricing, comparador ou dashboard interno sem virar engenheiro de scraping.