E-commerce Summary

Visão geral

Agregação de pedidos server-side para VTEX, Shopify e Tray

A API de Resumo de E-commerce retorna totais agregados de pedidos de uma loja em uma única chamada — sem paginação. As métricas são calculadas a partir dos pedidos no momento da consulta, então refletem os dados mais recentes e aceitam qualquer recorte de período.

Endpoints disponíveis

Resposta

Cada endpoint retorna:

  • totalOrders – número de pedidos no período
  • totalRevenue – soma do valor dos pedidos
  • avgTicket – totalRevenue / totalOrders (0 quando não há pedidos)
  • totalCustomers – pedidos com cliente identificável
  • uniqueCustomers – clientes distintos
  • period, platform, integrationName
  • groupBy / groups – presentes apenas quando groupBy foi enviado: top-20 grupos por receita, cada um com key, totalOrders, totalRevenue, avgTicket, uniqueCustomers. Quando há restante, uma linha (outros) aparece com os mesmos campos; valores nulos/vazios da dimensão caem no balde (sem valor). O grupo (sem valor), quando tem registros, é sempre retornado como um grupo explícito próprio — mesmo fora do top-20 — e seus números são excluídos do (outros). Para groupBy=product, a linha (outros) traz apenas key e totalRevenue — totalOrders, avgTicket e uniqueCustomers vêm null (um pedido pode conter vários produtos, então essas contagens não são deriváveis para o restante); o próprio grupo (sem valor) continua com métricas completas.

GTM motions

O gtmMotionId é opcional em todos os endpoints deste módulo. Sem ele, a resposta cobre só a GTM motion padrão da organização. Liste as motions, e veja qual é a padrão, com GET /v1/gtm-motions.

Por enquanto só a GTM motion padrão tem dados

Estes endpoints ainda não são recortados por GTM motion. A motion padrão (ou nenhum gtmMotionId) responde com os dados da organização, os mesmos números de antes; qualquer outra motion da organização recebe 422 com o código GTM_MOTION_DATA_NOT_AVAILABLE. Um gtmMotionId que não é UUID recebe 400, e um que não é motion da organização recebe 403 com o código GTM_MOTION_NOT_IN_ORGANIZATION, no mesmo formato de corpo do 422, para você distingui-lo de um 403 de falta de acesso.

Parâmetros comuns

  • organizationId (obrigatório)
  • dateStart / dateEnd (obrigatórios, YYYY-MM-DD)
  • integrationName – restringe a uma única loja
  • status – filtro por status do pedido
  • groupBy – dimensão opcional de quebra. VTEX: payment_method, utm_source, utm_campaign, product; Shopify: utm_source, utm_campaign, product, source_name; Tray: payment_method, product. Uma dimensão não suportada retorna 400 listando as válidas da plataforma.

Filtro de status

As três plataformas (VTEX, Shopify, Tray) filtram a coluna status nativa diretamente — passe o valor de status da própria plataforma (ex: VTEX invoiced).

Resultado do pagamento

GET /v1/orders/payment-outcomes?platform=vtex|tray|shopify&startDate=&endDate= responde o que aconteceu com os pedidos criados no período, por forma de pagamento: quantos foram pagos (paidOrders, paymentRate) e, dos não pagos, quantos foram cancelados sem pagamento (canceledOrders) e quantos seguem em aberto (pendingOrders), com o valor real de cada um. Cada pedido cai em uma situação só, e pedido pago e cancelado depois conta como pago. A Shopify não extrai a forma de pagamento e responde supported: false.

Autenticação

Todos os endpoints exigem autenticação via os headers padrão da API V4MOS.AI.

Nesta página