Matriz e sublojas

Uma empresa pode operar mais de uma loja na plataforma. Quando a loja secundária opera em modo espelho, ela vende com o catálogo e o estoque da matriz — e, por dividir a mesma empresa (mesmo CNPJ), quem fatura é a matriz.

Este guia é o conceito e o cadastro: quem é quem, o que cada loja pode fazer e como descobrir as lojas do grupo pela API. Para operar os pedidos dessas lojas numa integração só, veja Pedidos de sublojas.

Quem é quem

Termo	O que é
Matriz	A loja principal da empresa. É dela o catálogo, o estoque e a logística compartilhados.
Subloja espelho	Loja da mesma empresa que vende usando o catálogo/estoque da matriz. Não gerencia SKU, preço nem estoque próprios.
Grupo de faturamento	A matriz + suas sublojas espelho. É o conjunto que um token da matriz pode alcançar.
Emitente	O CNPJ que emite a nota do pedido — a empresa (ou a filial vinculada), nunca "a loja" em si.

Uma loja da mesma empresa que não está em modo espelho (catálogo próprio) não faz parte do grupo: ela precisa do seu próprio token.

O modo espelho é configurado no Portal do Vendedor — não há endpoint público para ligá-lo ou desligá-lo.

O que muda na integração

	Matriz	Subloja espelho
Catálogo (produtos, preços, estoque)	Gerencia	Somente leitura — escrever retorna 422 `SUBSTORE_CATALOG_READ_ONLY`
Anúncios	Próprios	Anuncia os SKUs da matriz associados a ela
Pedidos	Os seus + os das sublojas (com o acesso certo)	Só os seus
Emissão de nota	Emite pelo CNPJ da empresa	Faturada pela matriz

Na prática: um token de integração da matriz cuida do catálogo do grupo inteiro e — se você marcar o acesso a sublojas — também dos pedidos de todas elas. O token da subloja serve para operar só o que é dela.

Habilite o alcance no token

O alcance é opt-in. No Portal do Vendedor, ao criar ou editar a credencial de integração da matriz, marque o acesso:

store_orders_substores — Pedidos - Incluir Sublojas

Esse escopo não concede nenhuma ação nova: ele amplia às sublojas os acessos de pedido que o token já tem (store_orders_read, store_orders_manage, store_orders_create_shipment). Sem ele nada muda — inclusive para um token com abilities: ["*"], que passa em qualquer rota mas não ganha o alcance: ele precisa ser declarado.

Um token de subloja nunca alcança a matriz nem lojas irmãs, mesmo com o acesso marcado.

Descubra as lojas do grupo

GET/api/stores/linked

{
  "matriz": { "id": "01K8PB0KMM36AY2P0NKSZBP2NA", "name": "Minha Loja Premium" },
  "stores": [
    {
      "id": "01K8PB0KMM36AY2P0NKSZBP2NA",
      "name": "Minha Loja Premium",
      "is_primary": true,
      "relationship": "matriz",
      "shares": { "products": false, "stock_locations": false, "logistics": false },
      "orders_visible": true,
      "emitente": { "cnpj": "12345678000190", "razao_social": "Empresa de Comércio Eletrônico LTDA", "nome_fantasia": "Minha Loja Premium" }
    },
    {
      "id": "01K9QX4T7N8B3C2D1E0F5G6H7J",
      "name": "Minha Loja Express",
      "is_primary": false,
      "relationship": "mirror",              // ← subloja espelho
      "shares": { "products": true, "stock_locations": true, "logistics": true },
      "orders_visible": true,
      "emitente": { "cnpj": "12345678000190", "razao_social": "Empresa de Comércio Eletrônico LTDA", "nome_fantasia": "Minha Loja Premium" }
    }
  ]
}

Campo a campo:

id — ULID da loja. É o valor aceito em store_uid na API de Pedidos.
relationship — matriz, mirror (subloja espelho) ou standalone (loja da empresa fora do grupo).
shares — o que a loja herda da matriz: catálogo, locais de estoque, logística.
orders_visible — se o alcance em pedidos está de fato ativo para aquela loja com este token.
emitente — CNPJ e razão social que emitem a nota daquela loja (a filial vinculada quando existe, senão a empresa).

Repare que o emitente das duas lojas é o mesmo CNPJ — é exatamente isso que significa "a matriz fatura pela subloja".

Esta rota exige store_orders_substores; sem o acesso ela responde 403. Uma subloja autenticada recebe só a si mesma em stores[], mas com o bloco matriz preenchido — é assim que ela sabe quem a fatura.

Cuidados

O acesso é por token, não por loja. Se você mantém integrações separadas por loja, simplesmente não marque store_orders_substores — o comportamento atual continua idêntico.
Subloja não gerencia catálogo. Escrever SKU, preço ou estoque pelo token da subloja retorna 422 SUBSTORE_CATALOG_READ_ONLY; essas operações vão pelo token da matriz.
Webhooks continuam por loja. O alcance vale para a API; os eventos não são consolidados na matriz — pedido de subloja dispara no webhook daquela subloja. Para receber tudo num endpoint só, cadastre um webhook em cada loja apontando para a mesma URL e separe por data.store_id. Ver Webhooks.
O Portal do Vendedor não junta as lojas. Lá cada loja continua com sua própria sessão e sua própria fila de trabalho — a visão consolidada existe só na API, para o integrador.