Pedidos

Pedidos são a fonte comercial usada para reconciliar conversões de analytics e mídia. A primeira decisão do onboarding é semântica: o que a sua operação chama de receita capturada, aprovada, cancelada, devolvida, reembolsada e líquida.

Os campos formam uma referência para o onboarding. A origem não precisa renomear sua estrutura de dados. A Audt confirma o mapeamento com o cliente e preserva os identificadores e significados originais.

Dois conjuntos complementares

Conjunto	Grain	Chave esperada
Pedidos	Um registro por pedido no estado atual ou por versão temporal	`order_id`
Itens de pedido	Um registro por linha comercial do pedido	`order_item_id` ou composição estável de pedido e linha

Separe cabeçalho e itens mesmo quando a origem entrega um único payload. Isso evita repetir valores do pedido em cada produto e permite conciliar quantidades e totais.

Campos de pedido

Conceito lógico	Obrigatório	Descrição
`order_id`	Sim	Identificador estável na plataforma comercial
`order_sequence`	Recomendado	Sequência do pedido informada pela plataforma comercial
`captured_at`	Sim	Momento de criação ou captura comercial
`approved_at`	Recomendado	Momento de aprovação financeira
`updated_at`	Sim	Marcador para correções e incrementais
`order_status`	Sim	Estado comercial normalizado e valor original preservado
`payment_status`	Sim	Estado financeiro independente do fulfillment
`payment_id`	Sim	Identificador do meio de pagamento informado pela plataforma
`payment_name`	Sim	Nome do meio de pagamento no instante da venda
`installment_count`	Sim	Quantidade de parcelas da condição de pagamento
`installment_value`	Sim	Valor de cada parcela na moeda do pedido
`interest_rate`	Recomendado	Taxa de juros aplicada ao parcelamento, quando houver
`trade_policy_id`	Recomendado	Política comercial aplicada; em VTEX, corresponde ao campo `salesChannel`
`price_table_id`	Recomendado	Tabela de preços selecionada quando exposta separadamente
`order_origin`	Sim	Origem da venda, como site, app, marketplace ou loja
`affiliate_id`	Recomendado	Afiliado ou integração que originou o pedido
`store_id`	Recomendado	Loja, operação ou contexto comercial de origem
`marketplace_name`	Recomendado	Marketplace de origem quando houver intermediação
`seller_id`	Recomendado	Seller responsável pela venda
`currency`	Sim	Código de moeda aplicável aos valores
`items_gross_amount`	Sim	Soma bruta dos itens antes dos descontos
`discount_amount`	Sim	Desconto total conforme regra documentada
`shipping_amount`	Sim	Frete cobrado do cliente ou regra equivalente
`order_total_amount`	Sim	Total na definição da fonte de autoridade
`item_quantity`	Sim	Quantidade total de unidades ou linhas, conforme definição
`cancelled_at`	Recomendado	Momento do cancelamento quando disponível
`delivered_at`	Recomendado	Momento da entrega quando disponível
`refund_amount`	Recomendado	Valor acumulado ou evento associado, com regra declarada
`utm_source`	Opcional	Origem externa registrada no contexto promocional
`utm_medium`	Opcional	Meio externo registrado no contexto promocional
`utm_campaign`	Opcional	Campanha externa registrada no contexto promocional
`coupon_code`	Opcional	Código de cupom aplicado ao pedido
`marketing_tags`	Opcional	Marcadores promocionais preservados como lista
`utmi_campaign`	Opcional	Campanha interna registrada pela plataforma
`utmi_part`	Opcional	Parte interna da campanha registrada pela plataforma
`utmi_page`	Opcional	Página interna associada à campanha
`order_attributes`	Opcional	Pares de chave e valor, como versão do app, sistema operacional e plataforma

Campos de item

Conceito lógico	Obrigatório	Descrição
`order_item_id`	Sim	Identificador estável da linha comercial
`order_id`	Sim	Relação com o cabeçalho do pedido
`product_id`	Sim	Identificador do produto agrupador no instante da venda
`product_ref_id`	Recomendado	Código de referência comercial do produto
`sku_id`	Sim	Identificador da variante vendida
`sku_ref_id`	Recomendado	Código de referência comercial do SKU
`sku_name`	Sim	Nome da variante no instante da venda
`quantity`	Sim	Quantidade vendida na linha
`list_unit_price`	Sim	Preço DE unitário no instante do pedido
`selling_unit_price`	Sim	Preço unitário efetivamente vendido após os descontos aplicáveis
`discount_amount`	Sim	Desconto total alocado ao item
`net_item_amount`	Recomendado	Valor líquido do item após descontos e acréscimo de frete
`allocated_shipping_amount`	Recomendado	Parcela de frete atribuída ao item
`seller_id`	Recomendado	Seller responsável quando houver marketplace
`brand_id`	Sim	Identificador da marca no instante da venda
`brand_name`	Sim	Nome da marca no instante da venda
`primary_category_id`	Sim	Identificador da categoria principal no instante da venda
`primary_category_name`	Sim	Nome da categoria principal no instante da venda
`category_path_ids`	Sim	Caminho hierárquico por identificadores no instante da venda
`category_path_names`	Sim	Caminho hierárquico por nomes no instante da venda
`item_attributes`	Recomendado	Atributos comerciais preservados como pares de chave e valor

Preserve marca, categoria, nomes e atributos no contexto da venda. Se a origem não enviar esses dados no pedido, enriqueça o item com o snapshot de catálogo correspondente a captured_at. Não relacione pedidos históricos apenas com o catálogo atual.

Ciclo de vida e correções

Pedidos mudam depois da venda. A integração deve conseguir reaplicar o estado mais recente sem criar duplicatas.

Preserve o status original e forneça um mapeamento para o status normalizado.
Informe se a origem envia estado atual, histórico de versões ou eventos.
Use updated_at ou cursor equivalente para capturar mudanças tardias.
Não apague cancelamentos, devoluções e reembolsos: represente o efeito e a data de competência.
Para cancelamento ou devolução parcial, identifique item, quantidade e valor afetados.
Documente quando um valor é acumulado no pedido e quando representa um evento individual.

Reconciliação

Antes de usar a fonte em indicadores, compare por dia e canal:

contagem de pedidos capturados e aprovados;
quantidade de itens;
valor bruto, desconto, frete e total;
cancelamentos, devoluções e reembolsos;
pedidos ou itens sem chave de catálogo;
duplicidades e mudanças recebidas fora da janela esperada.

As tolerâncias são acordadas com o dono funcional. Diferenças conhecidas ficam registradas; não ajustamos valores silenciosamente para forçar igualdade.

Relação com analytics e mídia

order_id, sku_id, campos UTM e identificadores de clique aprovados ajudam a relacionar fontes. A qualidade dessas chaves determina a cobertura possível.

Conversão atribuída por Google Ads, Meta Ads ou GA4 não é receita financeira. A Audt preserva as definições de cada plataforma e usa pedidos como referência comercial para reconciliação. Atribuição avançada depende de histórico, eventos em granularidade suficiente e metodologia aprovada.