Visão geral

Um local de estoque é onde os seus produtos ficam guardados: um depósito, uma loja física ou um centro de distribuição. Todo saldo de estoque é contado por local, e é o local que define a origem do frete e o endereço fiscal de um envio.

Este guia cobre o ciclo de vida do local (criar, editar, ativar/desativar), as filiais que ele pode representar e como listar os produtos com saldo em cada local. A movimentação de saldo (entrada e saída de estoque) fica em Produtos: estoque.

Leitura exige o escopo store_stock_locations_read; criar, editar e mudar status exigem store_stock_locations_write.

Conceitos

Tipo de local (location_type):seller_location (depósito ou loja própria, que você gerencia) ou fulfillment (centro de distribuição da plataforma). Locais fulfillment são geridos por um sistema externo (WMS) e são somente leitura pela API: qualquer tentativa de criar, editar ou mudar o status é recusada. Na criação, só seller_location é aceito.

Status (status):available (operacional, entra no cálculo de venda e frete) ou unavailable (desativado, some da conta de disponibilidade, mas preserva o histórico). Não existe DELETE de local — para tirar um local de operação, mude o status para unavailable.

Filial (branch): um local pode estar vinculado a uma filial da empresa (CNPJ próprio) ou à matriz. O vínculo é feito pelo company_branch_id; branch: null na resposta significa matriz. A lista de filiais válidas vem de Filiais disponíveis.

Retirada e produção:allows_pickup marca o local como ponto de retirada pelo cliente; allows_production marca o local como apto a industrialização/produção sob encomenda.

Endereço de logística: para operar (cotar frete, emitir nota), um local precisa de pelo menos um endereço do tipo logistics. Esse cadastro é feito no Portal do Vendedor — hoje não há rota de integração para endereços de local.

O objeto que a API devolve para um local:

{
  "location_id": "01K9T…",         // ID do local, usado como {locationId} nas rotas
  "store_id": 42,                   // referência interna da loja (não é o store_id da sessão)
  "name": "Depósito Central",
  "status": "available",            // available | unavailable
  "location_type": "seller_location", // seller_location | fulfillment (WMS, somente leitura)
  "allows_pickup": true,            // aceita retirada no local
  "allows_production": false,       // apto a industrialização
  "branch": {                       // filial vinculada (null = matriz)
    "id": "01K9B…",                 // ID da filial
    "name": "Filial Campinas",
    "document": "12345678000199"    // CNPJ da filial
  }
}

Locais

A listagem devolve todos os locais da loja — inclusive os desativados e os de fulfillment — e não é paginada. O {locationId} das outras rotas é o location_id retornado aqui.

Não há endpoint de exclusão. Para tirar um local de operação, use PUT /api/locations-stock/{locationId}/status com status: "unavailable".

Locais fulfillment são geridos pela plataforma. Criar, editar ou mudar o status de um local fulfillment é recusado — eles só aparecem na listagem para leitura.

Limite de locais

Cada loja tem um teto de locais. O valor vigente vem em max_locations, na resposta de GET /api/stores/auth/session — leia de lá em vez de fixar um número na integração.

A contagem inclui todos os locais já cadastrados, inclusive os unavailable e os de fulfillment. Desativar um local não libera vaga. Ao atingir o teto, o POST responde 403 orientando a contatar o suporte.

Criar

Envie name, status e location_type — os três são obrigatórios. Repetir o par nome + tipo devolve 409.

{
  "name": "Novo Depósito Zona Norte",
  "status": "available",
  "location_type": "seller_location",
  "allows_pickup": false,
  "allows_production": false,
  "company_branch_id": "01K9B..."
}

Editar

O PUT /api/locations-stock/{locationId} aplica só os campos enviados (name, allows_pickup, allows_production, company_branch_id). Para mudar o status, use a rota dedicada de status — o PUT de edição não muda status.

A resposta da rota de status não traz o campo branch. Se precisar do vínculo atualizado depois de ativar ou desativar, consulte o local.

Filiais disponíveis

Lista a matriz e as filiais ativas da empresa, para você escolher o company_branch_id na criação/edição de um local. A matriz vem com uid: null — ou seja, para deixar o local na matriz, omita o campo ou envie null.

{
  "headquarters": { "id": null, "name": "Matriz", "document": "12345678000190" },
  "branches": [
    { "id": "01K9B...", "name": "Filial Campinas", "document": "12345678000199" }
  ],
  "default_branch": { "id": "01K9B...", "name": "Filial Campinas" }
}

Enviar uma filial inativa, de outra empresa ou inexistente devolve 422 no campo company_branch_id.

Endereços do local

O local precisa de um endereço do tipo logistics para cotar frete e emitir nota. Esse cadastro é feito hoje no Portal do Vendedor: as rotas de endereço de local existem na plataforma, mas aceitam apenas a sessão do portal — não funcionam com token de integração. Por isso não estão documentadas aqui.

Se a sua integração cria locais, cadastre o endereço logistics pelo portal antes de considerar o local pronto para operar.

Produtos por local

Lista paginada dos produtos com o saldo daquele local (quantity, reserved_quantity, available_quantity são escopados ao local). Aceita filter[name], filter[sku], filter[search], ordenação por name, sku, created_at, updated_at e per_page (padrão 15). Segue o envelope paginado padrão (data.data + data.meta.pagination).

Para dar entrada ou baixa de saldo em um local, use a movimentação de estoque em Produtos: estoque.

Dados auxiliares

Devolve os valores válidos de location_types, location_statuses e address_types (com rótulos em pt-BR). Use para popular selects no seu sistema. A lista address_types traz todos os tipos de endereço da plataforma; em locais de estoque valem apenas logistics, local_real e local_devolucao.

Fluxo: novo local pronto para operar

O que pode dar errado

Para onde ir agora