---
id: varejo/marketplaces-consolidados
industria: Varejo e e-commerce
uso: comum
esforco: médio
grao: Pedido por canal (e item de pedido para abrir por SKU)
---

# Marketplaces consolidados

Mercado Livre, Amazon, Shopee e os demais canais numa tabela só, conciliados com o ERP ou o hub, sem contar o mesmo pedido duas vezes e com a data certa.

## Resumo executivo

**Para quem:** Varejistas e indústrias que vendem em mais de um marketplace e também registram as vendas num hub ou ERP.

**O que resolve**

- Cada venda de marketplace aparece uma vez, mesmo existindo no marketplace, no hub e no ERP.
- Fica claro quanto vendeu cada marketplace, cada conta e cada loja, no consolidado e separado.
- Pedidos do canal sem par no ERP (e vice-versa) aparecem numa lista, com nível de confiança.

**Por que importa:** O mesmo pedido nasce no marketplace, desce para o hub e vira nota no ERP. Quem soma as três fontes triplica a venda; quem usa só o ERP perde as vendas que o canal passou a faturar direto em nota. Sem uma base consolidada, participação por canal, meta por marketplace e margem por SKU saem de números que não fecham entre si.

**Perguntas de negócio que responde**

- Quanto vendemos em cada marketplace e em cada conta neste mês?
- Qual a participação de cada marketplace no faturamento e como mudou contra o mês passado?
- Quais pedidos do Mercado Livre não aparecem no ERP, e quais notas do ERP não têm pedido no canal?
- Qual a taxa de cancelamento por marketplace?
- Quanto foi faturado no mês e quanto disso já foi liberado para recebimento?
- Quais SKUs explicam a queda de um marketplace contra a meta?

**O que você precisa**

- Os marketplaces e o hub ou ERP conectados na Nekt
- A lista de lojas ou canais do hub que correspondem a cada marketplace e conta
- As datas em que algum canal mudou de sistema ou passou a faturar sem pedido

**O que você recebe**

- Uma tabela por pedido e canal com valor, status, data e fonte de origem
- Uma tabela de conciliação marketplace x hub ou ERP com nível de confiança
- Dashboard por marketplace, conta e loja, com filtro individual e visão consolidada
- Indicador de cobertura por fonte, que separa dia sem venda de dia sem dado

## Detalhado

### O problema

O pedido do marketplace é copiado para o hub, que gera o pedido no ERP, que emite a nota. Cada camada tem seu identificador: o id do pedido e o pack no Mercado Livre, o número da loja no hub, o número do pedido e a nota no ERP. Canais mudam de operação no meio do ano (passam a faturar sem pedido, trocam de conta no hub) e cada fonte tem sua data: compra, confirmação, faturamento, liberação do saldo. Somar tudo duplica; escolher uma fonte só perde venda.

### Regras de negócio

1. **Uma fonte de verdade por canal e período.** Para cada marketplace, declare qual fonte define a venda (o próprio marketplace via API, o hub ou o ERP) e a partir de quando. As outras fontes servem para conciliar, nunca para somar. Guarde essa escolha numa tabela de canais com data de início e fim, para a regra ser lida pelo dashboard e pelo agente. (Evite: UNION do pedido do marketplace, do pedido do hub e da nota do ERP.)
2. **O canal sai do identificador da loja no hub.** No hub, cada marketplace e cada conta é uma loja com id próprio. Classifique o canal pelo id da loja numa tabela de mapeamento (loja → marketplace → conta), e não por texto livre. No ERP, quando não há loja, o canal sai de uma combinação documentada: origem do pedido, vendedor de integração, projeto ou observação que cita o marketplace. Escreva os critérios no context document. (Evite: Procurar "MERCADO" na descrição do pedido e chamar o resto de loja própria.)
3. **Pedido, pack e envio são coisas diferentes.** No Mercado Livre, o carrinho com vários itens gera vários pedidos agrupados por pack_id, e um envio pode cobrir o pack inteiro. O hub pode guardar no número da loja o id do pedido ou o pack_id. Conte pedidos pelo id do pedido do canal, use o pack para casar com o hub e com o envio. A tabela de pedidos do canal vem com versões repetidas: fique com a última versão de cada id. (Evite: Contar cada pack como um pedido ou somar todas as versões do mesmo id.)
4. **Conciliação com nível de confiança, nunca certeza inventada.** Case o pedido do hub com o do marketplace em ordem de força: número da loja igual ao id do pedido (alta), número da loja igual ao pack_id (alta), mesmo valor e data próxima na mesma conta (média), sem par (pendente). Grave a regra que casou e a evidência em colunas. Relatórios dizem quanto está conciliado; a IA nunca afirma que um par é confirmado quando a confiança é média. (Evite: JOIN por valor e data e tratar todo par como a mesma venda.)
5. **Venda faturada sem pedido também é venda.** Há canais que, a partir de uma data, passam a ser faturados direto em NF-e (em geral numa série própria) sem pedido de venda no ERP. A base do canal é a união dos pedidos identificados com as notas de saída dessa série emitidas sem pedido. Nota que já tem pedido não entra de novo. Uma flag de CFOP de venda separa venda de remessa, transferência ou envio para armazém do marketplace: filtre só venda. (Evite: Relatório do canal só a partir de pedidos do ERP, que zera o canal na data da mudança.)
6. **Troca de sistema é corte por data.** Quando o canal migra de uma conta do hub para outra, ou do hub para a API do marketplace, cada fonte contribui só com o seu período. Declare a data de corte (último dia na fonte antiga, primeiro na nova) e garanta que nenhum dia aparece nas duas nem fica sem nenhuma. (Evite: Juntar as duas contas do hub no mesmo período e dobrar a semana da migração.)
7. **Faturamento e recebimento têm datas diferentes.** A data de referência do faturamento é a data de confirmação do pedido. O recebimento segue a regra de liberação de saldo de cada marketplace, que pode cair semanas depois. Mantenha as duas linhas do tempo em colunas separadas e nunca compare faturamento de um mês com repasse do mesmo mês como se fossem o mesmo dinheiro. (Evite: Usar a data do repasse como data da venda, ou o contrário.)
8. **Contagem de pedido declarada por canal.** Relatórios de alguns canais contam uma linha por item como um pedido (o relatório de pedidos da Amazon replica o "Quantity Ordered" de ferramentas de BI de e-commerce). Defina por canal se "pedidos" é pedido distinto ou linha de item e escreva na descrição da coluna. Receita na Amazon é itemPrice sem imposto; imposto vem separado. SKU sem mapeamento para produto vai para "Sem categoria" com flag, nunca some. (Evite: Comparar "pedidos" da Amazon com pedidos distintos do Mercado Livre.)
9. **Status do pedido separa válido de cancelado.** Conte pedidos válidos e cancelados em colunas separadas, por data do pedido. Cancelado não entra no faturamento, mas entra na taxa de cancelamento. Carregue de forma incremental pela data de atualização do pedido (no hub, o campo de alteração), não pela data de criação: pedidos antigos mudam de status e só assim a mudança chega. (Evite: Carga incremental por data de criação, com pedidos cancelados semanas depois ainda como venda.)
10. **Ausência de dado nunca vira zero.** Para cada fonte e conta, registre período coberto, dias com dado, dias sem registro e a última carga. Um dia sem linhas numa conta que vende todo dia é falha de carga até prova em contrário. O dashboard mostra o canal como "sem dado" e não como zero, e a IA avisa quando a fonte está atrasada. (Evite: LEFT JOIN no calendário com COALESCE para zero em todo canal.)

### Como casar cada canal com o hub ou ERP

Chave de conciliação e cuidado de cada fonte.

- **Mercado Livre · pedido** → Última versão de cada id (`orders.id, pack_id`)
- **Hub · pedido de marketplace** → Número da loja = id do pedido ou pack (`numeroLoja, loja.id`)
- **Hub · canal** → Loja do hub mapeada para marketplace e conta (`loja.id → marketplace`)
- **ERP · venda sem pedido** → NF-e de saída da série do canal, sem pedido (`série + CFOP de venda`)
- **ERP · remessa para armazém do canal** → Fora do faturamento (`CFOP fora da lista de venda`)
- **Amazon · pedidos** → Linha por item; receita sem imposto (`itemPrice, SKU → ASIN → produto`)
- **Todos · faturamento** → Data de confirmação do pedido
- **Todos · recebimento** → Data de liberação do saldo no canal

### Definições

| Métrica | Definição |
|---|---|
| Faturamento do marketplace | soma do valor dos pedidos válidos, pela data de confirmação do pedido, por marketplace, conta e dia, a partir da fonte de verdade do canal no período |
| Pedidos válidos | contagem distinta de ids de pedido do canal não cancelados, por marketplace e dia (na Amazon, conforme a definição de pedido declarada) |
| Taxa de cancelamento | pedidos cancelados / (válidos + cancelados), por marketplace e mês, pela data do pedido |
| Participação por marketplace | faturamento do marketplace / faturamento de todos os marketplaces no mesmo período |
| Ticket médio do canal | faturamento / pedidos válidos, recalculado em cada recorte |
| % conciliado | pedidos do canal com par de confiança alta no hub ou ERP / pedidos válidos do canal, por mês |
| Recebimento | valor liberado pelo marketplace, pela data de liberação do saldo, por conta e dia |
| Cobertura da fonte | dias com dado / dias esperados, por fonte, conta e mês |

### Armadilhas

- **Canal zerado do dia para a noite.** O marketplace passou a ser faturado só por nota, sem pedido no ERP. O relatório baseado em pedidos mostrou queda total do canal a partir daquela data, sem que a venda tivesse caído. Como evitar: Unir pedidos do canal com as notas da série do canal emitidas sem pedido.
- **Semana dobrada na migração.** O canal trocou de conta no hub e as duas contas ficaram ativas por alguns dias. Somar as duas duplicou a venda da semana da troca. Como evitar: Data de corte declarada por fonte, com teste de sobreposição.
- **Par por valor tratado como certo.** Pedidos de mesmo valor no mesmo dia foram casados com o pedido errado do hub, e a conversão confirmada no relatório não existia. Como evitar: Conciliar por id ou pack primeiro; par por valor fica com confiança média e aparece como tal.
- **Remessa contada como venda.** Notas de envio de estoque para o armazém do marketplace entraram como venda do canal e inflaram o mês em que o estoque foi abastecido. Como evitar: Flag de CFOP de venda; remessa e transferência fora do faturamento.
- **Falha de carga lida como queda.** Uma conta ficou dias sem sincronizar e o dashboard mostrou zero venda. A diretoria cobrou o time do canal antes de alguém olhar a carga. Como evitar: Tabela de cobertura por fonte e estado "sem dado" no dashboard e nas respostas da IA.

### Teste de aceitação

- [ ] Para um marketplace, uma conta e um mês fechado, pedidos válidos e faturamento batem com o relatório de vendas do próprio marketplace (diferença abaixo de 1%).
- [ ] Cada id de pedido do canal aparece exatamente uma vez na tabela consolidada.
- [ ] A soma por marketplace é igual ao total consolidado no mesmo período, e o filtro por loja individual soma o consolidado.
- [ ] Nos dias em volta de cada data de corte de sistema, nenhum pedido aparece em duas fontes e nenhum dia fica sem fonte.
- [ ] O % conciliado do mês é reportado e todo pedido pendente aparece na lista de pendências com a regra tentada.

### Context document

```text
Marketplaces consolidados
- Grão: uma linha por pedido do canal (id do pedido no marketplace). Itens na tabela de item de pedido.
- Fonte de verdade por canal e período está na tabela de canais. Não some pedido do marketplace, do hub e do ERP: as demais fontes só conciliam.
- Canal = loja do hub mapeada para marketplace e conta. No ERP, canal pelos critérios documentados (origem, vendedor de integração, projeto, observação).
- Mercado Livre: pedido = id, última versão; pack_id agrupa pedidos e serve para casar com o hub.
- Conciliação com o hub por número da loja = id ou pack_id (confiança alta); por valor e data (confiança média). Nunca afirme conversão confirmada com confiança média.
- Canais faturados sem pedido: some as notas de saída da série do canal emitidas sem pedido. Só CFOP de venda.
- Faturamento pela data de confirmação do pedido. Recebimento pela data de liberação do saldo. Não trate como a mesma data.
- Amazon: "pedidos" segue a definição declarada na coluna; receita = itemPrice sem imposto.
- Cancelados fora do faturamento, mas contados na taxa de cancelamento.
- Dia sem dado não é dia sem venda: consulte a tabela de cobertura antes de responder zero e diga quando a fonte está atrasada.
- Comissões e taxas por canal seguem as regras do caso de margem de contribuição.
Exceções por cliente:
- <cliente>: canal <marketplace> faturado sem pedido desde <data>, série <série>.
- <cliente>: contas do hub <conta A> até <data>, <conta B> a partir de <data>.
- <cliente>: lojas do hub <lista de ids> = <marketplace> conta <conta>.
```

### Variações

- **Desempenho por anúncio:** Grão anúncio x dia com visitas, pedidos válidos e cancelados, unidades e Ads, agregável por conta, família e SKU sem dupla contagem.
- **Histórico de anúncios:** Snapshot que grava uma linha nova só quando título, preço, tipo de anúncio ou logística mudou, para ligar mudanças a resultado.
- **Proposta até pedido:** Pares candidatos proposta comercial → pedido do mesmo contato numa janela de 90 dias, com nível de confiança.