Pedidos de sublojas

Se a sua operação tem sublojas em modo espelho, os pedidos delas podem ser lidos e operados pela integração da matriz — que é quem fatura. Este guia cobre só a parte de pedidos: como filtrar por loja, como saber quem vendeu e quem emite a nota.

O conceito (o que é subloja espelho, como habilitar o acesso no token e como descobrir as lojas do grupo) está em Matriz e sublojas. Comece por lá — sem o acesso store_orders_substores marcado na credencial, nada neste guia tem efeito.

O que o token alcança

Sem store_orders_substores, o token continua vendo apenas a própria loja e tudo que segue é inerte.

Listar

Com o acesso ativo, GET/api/v1/sellers/orders já retorna o grupo inteiro. Dois parâmetros recortam:

GET /api/v1/sellers/orders?store_scope=substores&status=paid
GET /api/v1/sellers/orders?store_uid=01K9QX4T7N8B3C2D1E0F5G6H7J

Os ULIDs vêm de GET /api/stores/linked (Matriz e sublojas).

store_uid fora do grupo e store_scope com valor desconhecido respondem 422 STORE_OUT_OF_SCOPE — em vez de lista vazia, para você notar o erro de integração na hora. Já store_scope=substores numa matriz sem sublojas devolve 200 com lista vazia, que é o resultado correto. Num token sem o alcance, os dois parâmetros são simplesmente ignorados: nada quebra em quem já usa a API.

Os mesmos parâmetros valem em /orders/summary, /orders/dashboard e na listagem de devoluções /orders/returns, então os contadores batem com a lista. Rotas de um pedido específico (detalhe, fiscal, eventos, XML, envios) não recortam — elas aceitam qualquer pedido do grupo, independentemente do store_scope.

Cada pedido traz quem vendeu:

"sold_by": { "id": "01K9QX4T7N8B3C2D1E0F5G6H7J", "name": "Minha Loja Express", "is_substore": true }

Abrir e identificar o emitente

GET/api/v1/sellers/orders/{id} devolve, além de sold_by, o bloco emitente:

{
  "order_number": "STD-A1B2C3-100045",
  "store":    { "id": "01K9QX4T7N8B3C2D1E0F5G6H7J", "name": "Minha Loja Express" },
  "sold_by":  { "id": "01K9QX4T7N8B3C2D1E0F5G6H7J", "name": "Minha Loja Express", "is_substore": true },
  "emitente": {
    "cnpj": "12345678000190",
    "ie": "123456789",
    "razao_social": "Empresa de Comércio Eletrônico LTDA",
    "nome_fantasia": "Minha Loja Premium",
    "tax_regime": "simples",
    "address": { "zip_code": "01310000", "street": "Avenida Central", "number": "1000", "city": "São Paulo", "state": "SP" },
    "source": "live_matrix",
    "store": { "id": "01K8PB0KMM36AY2P0NKSZBP2NA", "name": "Minha Loja Premium" }   // ← quem fatura
  },
  "multiple_emitentes": false
}

Leia assim: sold_by = quem vendeu, emitente = quem emite a nota, emitente.store = a loja do grupo que responde por esse CNPJ. Em pedido de loja comum os três apontam para a mesma loja. A fonte da verdade fiscal é sempre emitente.cnpj: quando o pedido sai de uma filial vinculada à loja vendedora, o CNPJ é o dessa filial e emitente.store aponta a própria loja que vendeu, não a matriz.

O campo source diz de onde veio o dado fiscal:

O bloco emitentesó existe no detalhe. Na listagem, use sold_by e busque o emitente ao abrir o pedido.

Pedido com mais de um emitente

Um pedido pode ter itens atendidos por filiais de CNPJs diferentes. Nesse caso:

"emitente": null,
"multiple_emitentes": true

Resolva item a item por items[].stock_origin — o snapshot congelado na reserva de estoque, que tem forma própria (o emitente é um bloco irmão do address, e não existem source nem store):

"stock_origin": {
  "location": { "id": "…", "name": "CD Central" },
  "branch":   { "id": "…", "name": "Matriz", "is_headquarters": true },
  "emitente": { "cnpj": "…", "ie": "…", "razao_social": "…", "nome_fantasia": "…", "tax_regime": "simples" },
  "address":  { "zip_code": "…", "street": "…", "city": "…", "state": "…" }
}

stock_origin pode vir null quando o item não passou por reserva de estoque com origem carimbada (pedido legado, venda sem estoque). Nesse caso não há emitente item a item: trate o pedido manualmente — é a exceção, não a regra.

Operar

Com store_orders_manage + store_orders_substores, todo o fluxo operacional aceita o pedido da subloja exatamente como aceita o da matriz — mesmos endpoints, mesmo order_number:

• POST /orders/{id}/status — avanço de status (Visão geral).
• GET|POST /orders/{id}/fiscal, /invoice/upload-xml — documento fiscal (Fiscal).
• POST /orders/{id}/shipment-labels/generate e as rotas de envio (Logística).
• GET /orders/{id}/events, PUT /orders/{id}/notes, devoluções em /orders/returns.

Emita a nota pelo CNPJ que veio em emitente. Ao registrar o XML a plataforma compara os dois e recusa a divergência com a mensagem "CNPJ do emitente na NF-e (X) não corresponde ao CNPJ da loja (Y)" — o "CNPJ da loja" da mensagem é justamente o emitente.cnpj resolvido. (Lojas com emissão por CNPJ de terceiro autorizado têm essa validação dispensada pela plataforma; se é o seu caso, você já sabe.)

Cuidados

• store_id no pedido continua sendo o da subloja. Não troque por matriz na sua base: é ele que identifica onde a venda aconteceu (comissão, relatórios, atendimento).
• Webhooks de pedido continuam por loja — o pedido da subloja dispara no webhook dela, não no da matriz. Ver Matriz e sublojas e Webhooks.