Valores Financeiros do Pedido¶

Cada pedido que a Gubee recebe de um marketplace traz um conjunto de valores financeiros: quanto o comprador pagou, quanto de desconto houve e quem pagou esse desconto, quanto o canal cobrou de comissão e taxas, quanto o vendedor vai receber e, quando o custo do produto está cadastrado, qual foi a margem.

Esta página explica o que é cada campo, como ele é preenchido e quando ele está disponível, para que o seu sistema (ERP, BI, conciliação financeira) consuma o valor certo.

Cada canal informa valores diferentes

A Gubee repassa os valores como o marketplace os entrega, e os marketplaces não informam as mesmas coisas. As tabelas abaixo descrevem o significado de cada campo; a seção Como cada canal preenche mostra o que cada canal envia de fato. Consulte as duas antes de usar um campo em conciliação ou relatório.

Onde esses campos aparecem

Todos os campos desta página vêm no OrderApiDTO, o mesmo objeto devolvido por GET /integration/orders/{orderId}, POST /integration/orders/list/search e pela fila GET /integration/orders/queue/{status} (veja Receber Pedidos). Campos sem valor não são enviados no JSON: trate ausência como "o canal não informou", e não como zero.

Visão geral¶

flowchart LR
    A[Preço do produto<br/>items.salePrice × qty] --> B[Descontos<br/>totalDiscount]
    B --> C[Pago pelo comprador<br/>totalNet]
    A --> D[Comissão<br/>totalCommission]
    A --> E[Taxa de serviço<br/>serviceFee]
    F[Frete real<br/>shippingCost] --> G[Rebate de frete<br/>shippingDiscount]
    D & E & G --> H[Repasse ao vendedor<br/>profitability.escrowAmount]
    H --> I[Margem de contribuição<br/>profitability.contributionMargin]

Há dois grupos de campos:

Valores do canal (raiz do pedido e itens): copiados do marketplace no momento da importação e atualizados a cada nova leitura do pedido no canal.
Lucratividade (bloco profitability): calculados pela Gubee a partir dos valores do canal e do custo do produto cadastrado no catálogo.

Valores do canal¶

Itens¶

Campo	Tipo	O que é
`items[].originalPrice`	número	Preço unitário de tabela do anúncio, antes de promoções.
`items[].salePrice`	número	Preço unitário efetivamente vendido (após promoção do vendedor).
`items[].qty`	inteiro	Quantidade vendida do item.
`items[].discount`	objeto	Desconto do item, quando o canal informa por item: `discount` (valor) e `percentage` (`true` quando `discount` é percentual).

Totais do pedido¶

Campo	Tipo	O que é	Observações
`totalNet`	número	Total do pedido como o canal informa.	Na maioria dos canais é o valor pago pelo comprador. Pode incluir frete pago pelo comprador. Veja a tabela por canal.
`totalGross`	número	Total bruto (antes de descontos), quando o canal informa.	Muitos canais não enviam.
`totalDiscount`	número	Soma dos descontos dados ao comprador, independente de quem pagou.	Inclui desconto do vendedor e subsídios do canal (cupom, moedas). Para saber a parte paga pelo canal, use `marketplaceDiscount`.
`marketplaceDiscount`	número	Parte do desconto bancada pelo marketplace (rebate de produto).	Só tem esse significado onde o canal separa quem pagou o desconto (hoje: Shopee). Em vários canais repete `totalDiscount`. Veja a tabela por canal.
`totalFreight`	número	Frete pago pelo comprador.	`0` em frete grátis para o comprador.
`shippingCost`	número	Custo real do frete cobrado pelo canal/transportadora.	Pode ser maior que `totalFreight` quando há frete grátis.
`shippingDiscount`	número	Parte do frete subsidiada pelo marketplace (rebate de frete).	O frete que pesa para o vendedor é `shippingCost − shippingDiscount`. Hoje informado pela Shopee.
`totalCommission`	número	Comissão de venda cobrada pelo marketplace.	Na Amazon chega depois da sincronização financeira do pedido. Na Temu é uma estimativa do canal.
`serviceFee`	número	Taxas de serviço/transação do marketplace, além da comissão.	Em Magalu, TikTok Shop e Temu este campo traz os impostos informados pelo canal.
`totalInterest`	número	Juros de parcelamento, quando o canal informa.

Rebate = o que o canal pagou por você

"Rebate" é a parte de um desconto que o marketplace paga, e não o vendedor. Na Gubee ele aparece em dois campos: marketplaceDiscount (rebate sobre o produto) e shippingDiscount (rebate sobre o frete). Hoje só a Shopee separa o rebate do desconto do vendedor; nela, se os dois campos vierem 0, o pedido não teve rebate. Nos demais canais, veja a tabela por canal.

Lucratividade (bloco `profitability`)¶

O bloco profitability só aparece quando o pedido já tem custo calculado (costEnrichmentStatus = "ENRICHED"). A Gubee busca o custo dos produtos do pedido periodicamente (a cada ~10 minutos). Enquanto isso não acontece, costEnrichmentStatus vem PENDING e o bloco não é enviado. Se nenhum produto do pedido tiver custo cadastrado, o status fica NO_COST_DATA.

Campo	O que é	Como é calculado
`profitability.totalCost`	Custo dos produtos vendidos.	Σ (custo do produto × quantidade), usando o custo cadastrado no catálogo. Para kits, soma o custo de cada componente. Inclui os custos adicionais do produto (embalagem, frete de entrada etc.), quando cadastrados: valores fixos, ou percentuais aplicados sobre o preço de venda.
`profitability.grossProfit`	Lucro bruto.	`totalNet − totalCost`
`profitability.grossMarginPct`	Margem bruta (%).	`grossProfit ÷ totalNet × 100`
`profitability.totalCommission`	Comissão do canal.	Igual a `totalCommission`.
`profitability.serviceFees`	Taxas de serviço do canal.	Igual a `serviceFee`.
`profitability.netShippingCost`	Frete que pesa para o vendedor.	`shippingCost − shippingDiscount`
`profitability.grossOperatingRevenue`	Receita bruta do vendedor no canal (preço após descontos do vendedor, antes de comissão e taxas).	Informada pelo canal. Hoje: Shopee. Ausente nos demais canais.
`profitability.escrowAmount`	Repasse: valor líquido que o canal vai depositar ao vendedor por esse pedido.	Informado pelo canal. Hoje: Shopee. Ausente nos demais canais.
`profitability.tax`	Impostos retidos pelo canal no repasse.	Informado pelo canal. Hoje: Shopee (normalmente `0` no Brasil).
`profitability.contributionMargin`	Margem de contribuição em R$.	Veja abaixo.
`profitability.contributionMarginPct`	Margem de contribuição (%).	Veja abaixo.
`profitability.trend` / `trendPct`	Margem bruta deste pedido comparada à média do vendedor.	`IMPROVING` (> +2 p.p.), `WORSENING` (< −2 p.p.), `STABLE` ou `INSUFFICIENT_DATA`.
`profitability.hasCostData`	Indica que o custo foi encontrado.	Sempre `true` quando o bloco existe.

Os campos totalCost, grossProfit e grossMargin também aparecem na raiz do pedido, com os mesmos valores do bloco.

Margem de contribuição¶

A margem de contribuição usa a melhor fonte disponível:

Canal informa o repasse (Shopee)Demais canais

Quando o pedido tem escrowAmount, a margem parte do valor que realmente entra na conta do vendedor. Comissão, taxas e rebates de frete já estão descontados pelo próprio canal:

contributionMargin    = escrowAmount − totalCost − tax
contributionMarginPct = contributionMargin ÷ grossOperatingRevenue × 100

Sem o repasse informado pelo canal, a Gubee reconstrói a margem a partir dos componentes:

contributionMargin    = grossProfit − totalCommission − serviceFee
                        − (shippingCost − shippingDiscount)
contributionMarginPct = contributionMargin ÷ totalNet × 100

Valores podem mudar até a liberação do pagamento

O repasse e as taxas informados pelo marketplace são uma prévia enquanto o pedido não foi concluído. Pedidos trazidos por importação manual podem receber o repasse alguns minutos depois dos demais valores. Devoluções, ajustes e cancelamentos alteram esses valores. A Gubee atualiza o pedido a cada nova leitura no canal. Para conciliação financeira, use o valor depois que o pedido chegar a DELIVERED/CONCLUDED.

Exemplo real (Shopee)¶

Pedido com 1 unidade a R$ 22,90, frete grátis para o comprador (com rebate de frete da Shopee) e R$ 0,01 pago com moedas Shopee:

{
  "items": [
    { "qty": 1, "originalPrice": 22.90, "salePrice": 22.90 }
  ],
  "totalNet": 22.89,
  "totalDiscount": 0.01,
  "marketplaceDiscount": 0,
  "totalFreight": 0,
  "shippingCost": 9.62,
  "shippingDiscount": 9.62,
  "totalCommission": 4.26,
  "serviceFee": 4.82,
  "totalCost": 7.83,
  "grossProfit": 15.06,
  "grossMargin": 65.79,
  "costEnrichmentStatus": "ENRICHED",
  "profitability": {
    "totalCost": 7.83,
    "grossProfit": 15.06,
    "grossMarginPct": 65.79,
    "totalCommission": 4.26,
    "serviceFees": 4.82,
    "netShippingCost": 0.0,
    "grossOperatingRevenue": 22.90,
    "escrowAmount": 13.82,
    "tax": 0.0,
    "contributionMargin": 5.99,
    "contributionMarginPct": 26.16,
    "hasCostData": true
  }
}

Como ler esse pedido:

Pergunta	Resposta	Campos
Teve rebate?	Só de frete, R$ 9,62. Não houve rebate no produto.	`shippingDiscount` = 9,62 · `marketplaceDiscount` = 0
Quanto o comprador pagou?	R$ 22,89 (o R$ 0,01 restante foi pago em moedas Shopee).	`totalNet`, `totalDiscount`
Quanto o frete custou ao vendedor?	Nada: o frete real de R$ 9,62 foi coberto pelo rebate.	`shippingCost − shippingDiscount` = 0
Quanto o vendedor recebe?	R$ 13,82 = 22,90 − 4,26 − 4,82.	`escrowAmount`
Qual a margem?	R$ 5,99 = 13,82 − 7,83 (26,16% de 22,90).	`contributionMargin`, `contributionMarginPct`

Por que grossProfit usa 22,89 e a margem usa 22,90?

grossProfit parte de totalNet (o que o comprador pagou). A margem de contribuição parte do repasse, que a Shopee calcula sobre o preço cheio, porque as moedas são bancadas por ela. A diferença de centavos é esperada quando há moedas ou cupom do marketplace.

Como cada canal preenche¶

Resumo do que cada marketplace envia hoje. "—" quer dizer que o canal não informa o valor e o campo vem ausente (ou 0, quando indicado).

Canal	`totalNet`	`marketplaceDiscount`	`shippingDiscount`	`totalCommission`	`serviceFee`	Repasse (`escrowAmount`)
Shopee	Pago pelo comprador, com frete	Rebate de produto da Shopee (cupom/desconto Shopee)	Rebate de frete da Shopee	Comissão	Taxa de serviço	Sim
Mercado Livre	Total do pedido; o frete entra só em parte dos pedidos	Igual a `totalDiscount` (cupons)	—	Tarifa de venda	—	—
Amazon	Pago pelo comprador, com frete, após promoções	—	—	Comissão, após a sincronização financeira	Demais tarifas, após a sincronização financeira	—
Magalu	Total das entregas	Igual a `totalDiscount`	`0`	Comissão	Impostos	—
Via	Total do pedido	—	—	—	—	—
Shein	Só produtos, sem frete	—	—	Comissão	—	—
TikTok Shop	Pago pelo comprador	Todos os descontos, inclusive os do vendedor	`0`	—	Impostos	—
Temu	Pago pelo comprador	Igual a `totalDiscount`	`0`	Dedução estimada pela Temu	Impostos	—
MadeiraMadeira	Total do pedido	—	—	Comissão	—	—
Carrefour, Kabum, Leroy Merlin	Total do pedido (produtos, frete e taxas)	—	—	Comissão	—	—
Americanas	Total do pedido	—	—	Tarifa de venda	—	—
Kwai	Produtos + frete	Todos os descontos, inclusive os do vendedor	`0`	—	—	—
AliExpress	Total do pedido	—	—	—	—	—
Netshoes	Total bruto do pedido	—	—	Comissão	—	—

Particularidades por canal:

Frete (totalFreight × shippingCost). Na maioria dos canais totalFreight é o frete cobrado do comprador e shippingCost o frete real. Exceções:
- Mercado Livre e Americanas: shippingCost é o frete cobrado do vendedor.
- Shein: shippingCost traz a taxa de serviço de performance do canal, não frete. totalFreight não é informado.
- Magalu: shippingCost vem 0.
Preço dos itens. items[].salePrice é o preço unitário na maioria dos canais. Exceções:
- Leroy Merlin, Kabum e Netshoes: salePrice é o total da linha (unitário × quantidade).
- Americanas, Kwai e AliExpress: salePrice é o preço de tabela, igual a originalPrice.
Amazon: comissão e tarifas são preenchidas pela sincronização financeira, que roda depois do envio. Antes disso os campos vêm ausentes.
Shein: pedidos divididos em mais de um pacote repetem os totais do pedido original em cada parte. Não some os totais das partes.

Margem nos canais sem repasse

Como só a Shopee informa o repasse, nos demais canais a margem de contribuição usa a fórmula reconstruída (aba "Demais canais"). A precisão depende do que o canal envia: onde a comissão ou as taxas vêm ausentes, a margem fica maior do que a real.

Boas práticas¶

Ausente ≠ zero. Campo omitido quer dizer que o canal não informa esse valor. Não some ausentes como zero em relatórios de rebate ou taxa.
Para saber quanto vai entrar na conta, use profitability.escrowAmount quando existir. Nos demais canais o valor exato está no extrato do marketplace. Não derive o repasse de totalNet, que tem significado diferente em cada canal.
Para identificar rebate, use marketplaceDiscount e shippingDiscount apenas nos canais em que eles separam quem pagou o desconto (hoje: Shopee).
Para margem, use profitability.contributionMargin, que já escolhe a melhor fonte. Não recalcule a partir de grossProfit, que não desconta comissão nem taxas.
Releia o pedido depois de entregue/concluído antes de fechar a conciliação. Taxas e repasse podem ser ajustados pelo canal.
Custo do produto vem do catálogo da Gubee. Se a margem não aparecer, confira se o produto tem custo cadastrado (costEnrichmentStatus = "NO_COST_DATA").