Produtos

O que esta análise respondeCopiar link da seção

A API de Produtos mostra o desempenho de cada produto da loja no período que você escolher: quanto vendeu, com que margem, quanto estoque ainda resta e se os clientes que chegaram por ele voltam a comprar. Os números vêm consolidados, com os mesmos critérios usados na plataforma V4MOS.AI, então você pode levá-los direto para o seu BI sem refazer cálculos.

Perguntas que você consegue responder:

• Quais produtos vendem mais e com que margem?
• Quanto estoque eu tenho, em unidades e em dias de venda?
• Quais produtos têm muita devolução?
• Clientes que entram na loja por este produto voltam a comprar? Quanto eles valem em 180 dias?
• Como uma categoria inteira está performando?
• O que costuma ser comprado junto com este produto, e o que o cliente compra depois?
• Quais cupons e canais de aquisição trazem vendas deste produto?

Como começarCopiar link da seção

Base URL: https://data.v4mos.ai. Todas as chamadas exigem as credenciais da API e o organizationId — veja Autenticação.

1. Descubra o identificador da lojaCopiar link da seção

Chame GET /v1/products/integrations?organizationId=…. Cada loja da organização vem com um sourceIntegrationId: é esse valor que você envia como integrationId em todos os outros endpoints de Produtos.

2. Liste os produtosCopiar link da seção

GET /v1/products traz uma linha por produto, com as métricas do período, paginada e ordenável.

3. Veja os totais por categoriaCopiar link da seção

GET /v1/products/categories traz os totais de cada categoria para a mesma seleção da listagem.

4. Aprofunde em um produtoCopiar link da seção

GET /v1/products/{productId} traz o detalhe completo de um produto e GET /v1/products/{productId}/series traz a evolução diária ou semanal das vendas.

curl "https://data.v4mos.ai/v1/products?organizationId=SEU_ORGANIZATION_ID&integrationId=SEU_SOURCE_INTEGRATION_ID&dateFrom=2026-09-01&dateTo=2026-09-30&sortBy=netSales&pageSize=50" \
  -H "x-client-id: seu_client_id" \
  -H "x-client-secret: seu_client_secret"

MétricasCopiar link da seção

Valores monetários estão na moeda da loja e não incluem frete, impostos, serviços, mídia, taxas nem logística reversa. Taxas e proporções vêm como decimal: 0.3 significa 30%.

Período e atualizaçãoCopiar link da seção

• Vendas, clientes e margem seguem o período dateFrom–dateTo.
• Catálogo, status e estoque mostram a foto mais recente, qualquer que seja o período.
• asOf é a data/hora da última atualização dos dados de origem. Mostre-o ao lado dos números para indicar o quão recentes eles são.
• inventoryFreshness indica se o estoque está atualizado (fresh), desatualizado há mais de 24 horas (stale) ou sem leitura (missing). inventoryUpdatedAt traz a data da última leitura.

LTV e recompra: o grupo de entrada de 180 diasCopiar link da seção

Um cliente "entra" por um produto quando a primeira compra dele na loja contém esse produto. Para medir LTV e recompra de forma justa, cada cliente precisa de 180 dias desde a primeira compra — até lá, ele ainda está "amadurecendo".

• ltv180 e repurchaseRate180 usam apenas os clientes que já completaram 180 dias. Leia-os junto com matureEntryCustomers / entryCustomers para saber quantos clientes estão por trás do número.
• cohortState resume a situação: mature (todos maduros), partial (parte madura), maturing (ninguém maduro ainda) ou no_base (nenhum cliente de entrada no período).
• Para grupos recentes, use ltvToDate e repurchaseRateToDate, que consideram todos os clientes. Eles crescem com o tempo, então compare-os sempre olhando cohortElapsedDaysAverage.

Quando um valor vem como N/DCopiar link da seção

null significa N/D (não disponível) — nunca zero. O objeto ndReasons explica o motivo e coverage mostra quanto dos dados de origem estava completo (de 0 a 1):

Filtros e ordenaçãoCopiar link da seção

GET /v1/products e GET /v1/products/categories aceitam os mesmos filtros:

• Busca: search encontra produtos cujo nome contém o texto (sem diferenciar maiúsculas e minúsculas, até 120 caracteres).
• Status: status=active, inactive ou all (padrão).
• Categorias: categoryIds aceita até 50 categorias, separadas por vírgula (categoryIds=1,12) ou repetidas (categoryIds=1&categoryIds=12). Um produto entra se pertencer a qualquer uma delas, inclusive por uma subcategoria. categoryId (uma só categoria) ainda funciona, mas prefira categoryIds.
• Faixas de métricas (limites inclusivos): minNetSales/maxNetSales, minMarginTotal/maxMarginTotal, minMarginAverage/maxMarginAverage e minAvailableStock/maxAvailableStock. A margem % é decimal: minMarginAverage=0.3 significa "margem de pelo menos 30%". O min não pode ser maior que o max.
• Paginação (só na listagem): page (padrão 1) e pageSize (padrão 25, máximo 100). A resposta traz pagination.total e pagination.totalPages.
• Ordenação (só na listagem): sortBy com um destes campos — productName, grossSales, netSales (padrão), netUnits, averageTicket, marginAverage, marginTotal, newCustomers, recurringCustomers, ltv180, repurchaseRate180, ltvToDate, repurchaseRateToDate, entryCustomers, matureEntryCustomers, availableStock, daysOfStock, returnRate, updatedAt — e sortOrder=asc|desc (padrão desc). Valores N/D ficam sempre no fim.
• Colunas: columns recebe uma lista de métricas separadas por vírgula (por exemplo columns=netSales,marginTotal,daysOfStock) e devolve só elas. Identificação, status, cobertura e motivos de N/D sempre vêm.
• Categorias na listagem: a listagem traz também os totais por categoria em categories. Se você já usa GET /v1/products/categories, envie includeCategories=false para receber a listagem mais rápido.

Regras importantesCopiar link da seção

Quando a margem não apareceCopiar link da seção

A margem (marginTotal, marginAverage) e o CMV (cogs) só aparecem quando todas as unidades do produto no período têm valor de venda e custo cadastrados. Se faltar o custo de algumas unidades, o custo somado ficaria menor que o real e a margem pareceria maior do que é — por isso o valor fica N/D, com o motivo em ndReasons.margin. Para liberar a margem, complete o cadastro de custo dos produtos na plataforma de e-commerce.

Totais de categoria x soma da páginaCopiar link da seção

Os totais de categories consideram todos os produtos filtrados, não só os da página atual, e continuam corretos em qualquer página ou ordenação. Pedidos e clientes são recontados (um pedido com vários produtos da categoria conta uma vez) e as taxas são recalculadas a partir dos totais. Com faixas de métricas, cada categoria soma apenas os produtos que estão dentro das faixas; categorias sem nenhum produto na faixa não aparecem.

O detalhe do produto funciona por blocosCopiar link da seção

GET /v1/products/{productId} é formado por blocos independentes — resumo, funil, grupo de entrada (coorte), comprados juntos, retenção, frequência de compra, comprado depois, cupons e canais de aquisição. Cada bloco traz seu próprio state e reason:

• A resposta é 200 sempre que o produto existe para a organização e a loja. Um bloco pode vir com state: "error" ou sem dados enquanto os outros funcionam normalmente — trate cada bloco separadamente.
• 404 significa que o produto não existe nessa loja; 400, que algum parâmetro é inválido.
• Nem todo bloco usa o período pedido. periodApplied informa se o bloco seguiu dateFrom/dateTo e window informa o intervalo realmente medido. Comprados juntos e comprado depois usam os últimos 12 meses; o grupo de entrada usa os últimos cohortWindowMonths meses de entrada do produto.
• Use o asOf de cada bloco ao lado dos números dele. O asOf da raiz é o mais antigo entre os blocos.

Grupos de entrada se sobrepõem entre produtosCopiar link da seção

Um cliente cuja primeira compra teve vários produtos entra no grupo de cada um deles. Por isso, as linhas de coorte (e também entryCustomers, newCustomers, ltv180 e afins) não podem ser somadas entre produtos — o mesmo cliente seria contado mais de uma vez. O campo overlappingRows: true no bloco de coorte lembra essa regra. O mesmo vale para comprados juntos e comprado depois: um pedido alimenta várias linhas.

Devoluções são um pisoCopiar link da seção

Devoluções registradas depois que o pedido é finalizado podem não ser capturadas. Por isso returnRate é um valor mínimo (a devolução real pode ser maior) e faturamento e margem podem estar levemente acima do real. O bloco de resumo do detalhe declara isso em summary.returnMeasurement.

Parâmetros comunsCopiar link da seção

Endpoints disponíveisCopiar link da seção

• getLojas VTEX disponíveis no dashboard de produtos/v1/products/integrationsLista as lojas da organização com o identificador que os demais endpoints de Produtos esperam em integrationId.
• getCategorias de produtos consolidadas/v1/products/categoriesRetorna os totais de cada categoria (departamentos e subcategorias) para a mesma seleção de GET /v1/products: loja, período, busca,…
• getProdutos consolidados/v1/productsRetorna uma linha por produto com vendas, margem, estoque, devoluções e métricas de recompra do período, além dos totais por categoria em…
• getSérie diária ou semanal de vendas de um produto/v1/products/{productId}/seriesRetorna a evolução de faturamento, unidades, pedidos, custo e margem de um produto, dia a dia (granularity=day) ou em blocos de 7 dias…
• getDetalhe do produto com blocos independentes/v1/products/{productId}Retorna tudo sobre um produto em blocos independentes: resumo de métricas com comparação ao período anterior, funil do GA4, coorte de…