> For the complete documentation index, see [llms.txt](https://changelog.maino.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://changelog.maino.com.br/api-reference-maino/08.-controle-de-estoque.md).

# 08. 📊 Controle De Estoque

**Consulta de produtos e posições de estoque** Consulta de produtos cadastrados e histórico de posições de estoque. **Funcionalidades:**

* Listagem de produtos cadastrados
* Consulta de posição histórica de estoque
* Geração de relatórios em Excel
* Filtros por código, descrição, NCM e status

## Consulta posição histórica de estoques por produto

> \*\*Consulta posição histórica de estoques por produto\*\*\
> \
> Retorna a evolução da posição de estoque de produtos em um período específico.\
> Os dados são agrupados por produto e apresentam a quantidade disponível\
> para cada dia do período informado.\
> \
> \*\*Funcionalidades:\*\*\
> \- Histórico diário de posições de estoque\
> \- Agrupamento por produto (código e descrição)\
> \- Filtro por período de datas\
> \- Rastreamento de movimentações ao longo do tempo\
> \
> \*\*Estrutura dos dados:\*\*\
> \- Cada produto contém seu código e descrição\
> \- Array de posições diárias com data e quantidade\
> \- Quantidade representa o estoque disponível no final do dia\
> \
> \*\*Uso típico:\*\*\
> \- Análise de evolução de estoque\
> \- Relatórios gerenciais de movimentação\
> \- Auditoria de posições históricas\
> \- Gráficos de tendência de estoque

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"08. 📊 Controle de Estoque","description":"**Consulta de produtos e posições de estoque**\nConsulta de produtos cadastrados e histórico de posições de estoque.\n**Funcionalidades:**\n- Listagem de produtos cadastrados\n- Consulta de posição histórica de estoque\n- Geração de relatórios em Excel\n- Filtros por código, descrição, NCM e status"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/posicao_estoques":{"get":{"summary":"Consulta posição histórica de estoques por produto","tags":["08. 📊 Controle de Estoque"],"description":"**Consulta posição histórica de estoques por produto**\n\nRetorna a evolução da posição de estoque de produtos em um período específico.\nOs dados são agrupados por produto e apresentam a quantidade disponível\npara cada dia do período informado.\n\n**Funcionalidades:**\n- Histórico diário de posições de estoque\n- Agrupamento por produto (código e descrição)\n- Filtro por período de datas\n- Rastreamento de movimentações ao longo do tempo\n\n**Estrutura dos dados:**\n- Cada produto contém seu código e descrição\n- Array de posições diárias com data e quantidade\n- Quantidade representa o estoque disponível no final do dia\n\n**Uso típico:**\n- Análise de evolução de estoque\n- Relatórios gerenciais de movimentação\n- Auditoria de posições históricas\n- Gráficos de tendência de estoque","parameters":[{"name":"data_inicio","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Data inicial do período para consulta (formato YYYY-MM-DD)"},{"name":"data_fim","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Data final do período para consulta (formato YYYY-MM-DD)"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1},"description":"Número da página para paginação (padrão: 1)","required":false}],"responses":{"200":{"description":"Posições históricas de estoque","content":{"Histórico com dados":{},"Período sem dados":{},"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"Lista dos produtos com suas posições históricas","items":{"type":"object","properties":{"codigo_produto":{"type":"string","description":"Código do produto"},"codigo_descricao":{"type":"string","description":"Descrição do produto"},"posicao_estoques":{"type":"array","description":"Posições diárias de estoque no período","items":{"type":"object","properties":{"data_posicao_estoque":{"type":"string","format":"date","description":"Data da posição de estoque"},"quantidade_produto":{"type":"number","format":"float","description":"Quantidade disponível no final do dia","nullable":true}},"required":["data_posicao_estoque","quantidade_produto"]}}},"required":["codigo_produto","codigo_descricao","posicao_estoques"]}}},"required":["data"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Erro de autenticação"}}}}}}}}}}}
```

## Lista produtos

> \*\*Lista completa de produtos com informações de estoque e preços\*\*\
> \
> Retorna todos os produtos cadastrados para o usuário autenticado, incluindo:\
> \- Informações básicas (código, descrição, categoria)\
> \- Dados de estoque atual e movimentações\
> \- Preços de custo e venda configurados\
> \- Classificação fiscal (NCM) e unidades de medida\
> \- Informações de e-commerce\
> \- Imagens e tags\
> \
> \*\*Recursos de filtragem:\*\*\
> \- Status (ativo/inativo)\
> \- Produtos zerados ou com estoque\
> \- Busca por código ou descrição\
> \- Filtragem por NCM ou unidade de medida\
> \- Paginação (padrão: 100 itens por página)

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"08. 📊 Controle de Estoque","description":"**Consulta de produtos e posições de estoque**\nConsulta de produtos cadastrados e histórico de posições de estoque.\n**Funcionalidades:**\n- Listagem de produtos cadastrados\n- Consulta de posição histórica de estoque\n- Geração de relatórios em Excel\n- Filtros por código, descrição, NCM e status"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/produtos":{"get":{"summary":"Lista produtos","tags":["08. 📊 Controle de Estoque"],"description":"**Lista completa de produtos com informações de estoque e preços**\n\nRetorna todos os produtos cadastrados para o usuário autenticado, incluindo:\n- Informações básicas (código, descrição, categoria)\n- Dados de estoque atual e movimentações\n- Preços de custo e venda configurados\n- Classificação fiscal (NCM) e unidades de medida\n- Informações de e-commerce\n- Imagens e tags\n\n**Recursos de filtragem:**\n- Status (ativo/inativo)\n- Produtos zerados ou com estoque\n- Busca por código ou descrição\n- Filtragem por NCM ou unidade de medida\n- Paginação (padrão: 100 itens por página)","parameters":[{"name":"ativos","in":"query","description":"Filtrar apenas produtos ativos (true) ou incluir inativos (false)","required":false,"schema":{"type":"boolean"}},{"name":"zerados","in":"query","description":"Incluir produtos com estoque zerado na listagem","required":false,"schema":{"type":"boolean"}},{"name":"codigo","in":"query","description":"Busca parcial por código do produto (case-insensitive)","required":false,"schema":{"type":"string"}},{"name":"descricao","in":"query","description":"Busca parcial por descrição do produto (case-insensitive)","required":false,"schema":{"type":"string"}},{"name":"unidade_de_medida","in":"query","description":"Filtrar por sigla da unidade de medida","required":false,"schema":{"type":"string"}},{"name":"ncm","in":"query","description":"Filtrar por código NCM (classificação fiscal)","required":false,"schema":{"type":"string"}},{"name":"ultima_modificacao","in":"query","schema":{"type":"string","format":"datetime"},"description":"Filtrar produtos modificados a partir desta data/hora","required":false},{"name":"page","in":"query","schema":{"type":"integer","minimum":1},"description":"Número da página para paginação (padrão: 1)","required":false}],"responses":{"200":{"description":"Lista de produtos retornada com sucesso","content":{"Lista de produtos":{},"application/json":{"schema":{"type":"object","properties":{"produtos":{"type":"array","description":"Array de produtos com informações completas","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID do produto"},"codigo":{"type":"string","description":"Código do produto"},"descricao":{"type":"string","description":"Descrição do produto"},"informacoes_complementares":{"type":"string","nullable":true,"description":"Informações complementares"},"principal_modelo_ecommerce":{"type":"boolean","description":"Se é modelo principal no e-commerce"},"codigo_ecommerce":{"type":"string","nullable":true,"description":"Código no e-commerce"},"titulo_ecommerce":{"type":"string","nullable":true,"description":"Título no e-commerce"},"descricao_ecommerce":{"type":"string","nullable":true,"description":"Descrição no e-commerce"},"marca":{"type":"string","nullable":true,"description":"Marca do produto"},"modelo":{"type":"string","nullable":true,"description":"Modelo do produto"},"nome_fabricante":{"type":"string","nullable":true,"description":"Nome do fabricante"},"observacao_interna":{"type":"string","nullable":true,"description":"Observação interna"},"peso_liquido":{"type":"number","format":"float","nullable":true,"description":"Peso líquido total"},"peso_liquido_unitario":{"type":"number","format":"float","nullable":true,"description":"Peso líquido unitário"},"peso_bruto":{"type":"number","format":"float","nullable":true,"description":"Peso bruto total"},"peso_bruto_unitario":{"type":"number","format":"float","nullable":true,"description":"Peso bruto unitário"},"pu":{"type":"number","format":"float","description":"Preço unitário de entrada"},"pu_saida":{"type":"number","format":"float","description":"Preço unitário de saída"},"pu_saida_com_ipi":{"type":"number","format":"float","description":"Preço de saída com IPI"},"valor_ipi":{"type":"number","format":"float","description":"Valor do IPI"},"aliquota_ipi":{"type":"number","format":"float","description":"Alíquota do IPI (%)"},"composicao_de_preco_de_venda":{"type":"boolean","description":"Se usa composição de preço de venda"},"qtde":{"type":"number","format":"float","description":"Quantidade em estoque"},"qtde_comprometida":{"type":"number","format":"float","description":"Quantidade comprometida"},"qtde_armazenada":{"type":"number","format":"float","description":"Quantidade armazenada"},"gtin":{"type":"string","nullable":true,"description":"Código de barras GTIN"},"codigo_de_barras_interno":{"type":"string","nullable":true,"description":"Código de barras interno"},"ncm":{"type":"string","nullable":true,"description":"Código NCM"},"unidade_de_medida":{"type":"string","nullable":true,"description":"Sigla da unidade de medida"},"ativo":{"type":"boolean","description":"Se o produto está ativo"},"ultima_modificacao":{"type":"string","format":"datetime","description":"Data/hora da última modificação"},"tags":{"type":"array","items":{"type":"string"},"description":"Lista de tags do produto"},"altura":{"type":"number","format":"float","nullable":true,"description":"Altura"},"comprimento":{"type":"number","format":"float","nullable":true,"description":"Comprimento"},"largura":{"type":"number","format":"float","nullable":true,"description":"Largura"},"imagem_principal":{"type":"string","nullable":true,"description":"URL da imagem principal"},"imagens":{"type":"array","description":"Lista de imagens do produto","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID da imagem"},"url":{"type":"string","description":"URL da imagem"},"principal":{"type":"boolean","description":"Se é a imagem principal"}}}},"categoria":{"type":"object","nullable":true,"description":"Categoria do produto","properties":{"id":{"type":"integer","description":"ID da categoria"},"nome":{"type":"string","description":"Nome da categoria"}}},"subcategoria":{"type":"object","nullable":true,"description":"Subcategoria do produto","properties":{"id":{"type":"integer","description":"ID da subcategoria"},"nome":{"type":"string","description":"Nome da subcategoria"},"nome_com_categoria":{"type":"string","description":"Nome completo com categoria"}}},"propriedades":{"type":"array","description":"Propriedades customizadas do produto","items":{"type":"object","properties":{"propriedade":{"type":"string","description":"Nome da propriedade"},"valor":{"type":"string","description":"Valor da propriedade"}}}},"tabelas_de_vendas":{"type":"array","description":"Tabelas de vendas com preços calculados","items":{"type":"object","properties":{"codigo":{"type":"string","description":"Código da tabela"},"descricao":{"type":"string","description":"Descrição da tabela"},"pu_calculado":{"type":"number","format":"float","description":"Preço calculado"}}}}},"required":["id","codigo","descricao"]}},"pagination":{"type":"object","description":"Informações de paginação","properties":{"total":{"type":"integer","description":"Total de registros"},"previous_page":{"type":"string","nullable":true,"description":"URL da página anterior"},"next_page":{"type":"string","nullable":true,"description":"URL da próxima página"}}}},"required":["produtos","pagination"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Mensagem de erro"}}}}}}}}}}}
```

## Cria um produto

> \*\*Cadastra um produto no estoque do emitente autenticado\*\*\
> \
> Reaproveita o mesmo caminho de criação da tela, inclusive a movimentação de\
> abertura: quando \`qtde\` é maior que zero, o saldo inicial é lançado e confirmado.\
> \
> \*\*Campos traduzidos pela API (não são ids):\*\*\
> \- \`unidade\_de\_medida\_codigo\` — criada no cadastro se ainda não existir\
> \- \`classificacao\_fiscal\_codigo\` — NCM que \*\*deve existir\*\*; desconhecida devolve 422\
> \- \`top\_category\_description\` + \`category\_description\` — criadas se não existirem,\
> &#x20; e exigidas em par\
> \
> \*\*Travas deliberadas (ambas devolvem 422):\*\*\
> \- NCM desconhecida é recusada em vez de criada, para não gerar classificação\
> &#x20; fiscal incompleta que contaminaria o cálculo de imposto de uma NF-e futura\
> \- Código já usado por outro produto (ativo ou inativo) ou por um combo\
> \
> \`user\` e a pessoa que age vêm sempre do token — nunca do payload. Ids de\
> tabela de venda, armazém, fabricante e proprietário que não pertençam ao\
> emitente autenticado devolvem 422.\
> \
> O produto nasce sempre \*\*ativo\*\*: \`status\` não é aceito no payload, porque\
> inativar e reativar produto está fora do escopo deste endpoint.\
> \
> A resposta de sucesso é o mesmo cadastro completo devolvido pelo GET do produto.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"08. 📊 Controle de Estoque","description":"**Consulta de produtos e posições de estoque**\nConsulta de produtos cadastrados e histórico de posições de estoque.\n**Funcionalidades:**\n- Listagem de produtos cadastrados\n- Consulta de posição histórica de estoque\n- Geração de relatórios em Excel\n- Filtros por código, descrição, NCM e status"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/produtos":{"post":{"summary":"Cria um produto","tags":["08. 📊 Controle de Estoque"],"description":"**Cadastra um produto no estoque do emitente autenticado**\n\nReaproveita o mesmo caminho de criação da tela, inclusive a movimentação de\nabertura: quando `qtde` é maior que zero, o saldo inicial é lançado e confirmado.\n\n**Campos traduzidos pela API (não são ids):**\n- `unidade_de_medida_codigo` — criada no cadastro se ainda não existir\n- `classificacao_fiscal_codigo` — NCM que **deve existir**; desconhecida devolve 422\n- `top_category_description` + `category_description` — criadas se não existirem,\n  e exigidas em par\n\n**Travas deliberadas (ambas devolvem 422):**\n- NCM desconhecida é recusada em vez de criada, para não gerar classificação\n  fiscal incompleta que contaminaria o cálculo de imposto de uma NF-e futura\n- Código já usado por outro produto (ativo ou inativo) ou por um combo\n\n`user` e a pessoa que age vêm sempre do token — nunca do payload. Ids de\ntabela de venda, armazém, fabricante e proprietário que não pertençam ao\nemitente autenticado devolvem 422.\n\nO produto nasce sempre **ativo**: `status` não é aceito no payload, porque\ninativar e reativar produto está fora do escopo deste endpoint.\n\nA resposta de sucesso é o mesmo cadastro completo devolvido pelo GET do produto.","parameters":[],"responses":{"201":{"description":"Produto criado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"ID do produto criado"},"codigo":{"type":"string","description":"Código do produto"},"descricao":{"type":"string","description":"Descrição do produto"},"ncm":{"type":"string","nullable":true,"description":"NCM da classificação fiscal"},"qtde":{"type":"number","format":"float","description":"Quantidade em estoque"}},"required":["id","codigo","descricao"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Mensagem de erro"}}}}}},"422":{"description":"Payload recusado","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"fields":{"type":"object","description":"Campos recusados e seus motivos"},"message":{"type":"string","description":"Mensagem de erro geral"}}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"produto":{"type":"object","properties":{"descricao":{"type":"string","description":"Descrição do produto (máx. 120 caracteres)"},"codigo":{"type":"string","description":"Código do produto, único no emitente"},"qtde":{"type":"number","format":"float","description":"Quantidade inicial em estoque"},"pu":{"type":"number","format":"float","description":"Preço unitário de custo"},"pu_saida":{"type":"number","format":"float","description":"Preço unitário de venda"},"p_ipi":{"type":"number","format":"float","description":"Percentual de IPI"},"unidade_de_medida_codigo":{"type":"string","description":"Sigla da unidade de medida"},"classificacao_fiscal_codigo":{"type":"string","description":"NCM já cadastrado"},"top_category_description":{"type":"string","description":"Categoria principal"},"category_description":{"type":"string","description":"Subcategoria"},"icms_orig_id":{"type":"integer","description":"Origem do ICMS (dispensada em serviço)"},"cest_id":{"type":"integer","description":"ID do CEST"},"pais_origem_id":{"type":"integer","description":"ID do país de origem"},"finalidade_produto_id":{"type":"string","description":"ID da finalidade do produto"},"tabela_de_venda_id":{"type":"integer","description":"ID da tabela de venda do emitente"},"armazem_id":{"type":"string","format":"uuid","description":"ID do armazém do emitente"},"stakeholder_fabricante_id":{"type":"integer","description":"ID do fabricante do emitente"},"proprietario_id":{"type":"integer","description":"ID do proprietário do emitente"},"codigo_de_barras_gtin":{"type":"string","description":"Código de barras GTIN"},"codigo_fornecedor":{"type":"string","description":"Código do produto no fornecedor"},"property_indicator":{"type":"string","description":"Indicador de propriedade do produto"}},"required":["descricao","codigo","qtde","pu","p_ipi","unidade_de_medida_codigo","classificacao_fiscal_codigo"]}},"required":["produto"]}}}}}}}}
```

## Consulta um produto

> \*\*Cadastro completo de um produto do estoque\*\*\
> \
> Retorna o cadastro completo de um único produto a partir do seu id, incluindo:\
> \- Identificação, status e códigos (GTIN, código interno, código do fornecedor)\
> \- Estoque, localização física, lote e validade\
> \- Preços, custos e campos fiscais (IPI, ICMS-ST, FCP, ISSQN, FCI)\
> \- Medidas, pesos e dados de e-commerce\
> \- Dados de veículo agrupados no objeto \`veiculo\`\
> \- Relações descritas (NCM, unidade de medida, CEST, origem do ICMS, categoria,\
> &#x20; país de origem, finalidade, tabela de venda, armazém, fabricante, proprietário)\
> \
> Diferente da listagem, as relações vêm como objeto com id, código e descrição —\
> o integrador não precisa manter tabelas próprias de tradução.\
> \
> Produto de outro emitente é tratado como inexistente e devolve 404.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"08. 📊 Controle de Estoque","description":"**Consulta de produtos e posições de estoque**\nConsulta de produtos cadastrados e histórico de posições de estoque.\n**Funcionalidades:**\n- Listagem de produtos cadastrados\n- Consulta de posição histórica de estoque\n- Geração de relatórios em Excel\n- Filtros por código, descrição, NCM e status"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/produtos/{id}":{"get":{"summary":"Consulta um produto","tags":["08. 📊 Controle de Estoque"],"description":"**Cadastro completo de um produto do estoque**\n\nRetorna o cadastro completo de um único produto a partir do seu id, incluindo:\n- Identificação, status e códigos (GTIN, código interno, código do fornecedor)\n- Estoque, localização física, lote e validade\n- Preços, custos e campos fiscais (IPI, ICMS-ST, FCP, ISSQN, FCI)\n- Medidas, pesos e dados de e-commerce\n- Dados de veículo agrupados no objeto `veiculo`\n- Relações descritas (NCM, unidade de medida, CEST, origem do ICMS, categoria,\n  país de origem, finalidade, tabela de venda, armazém, fabricante, proprietário)\n\nDiferente da listagem, as relações vêm como objeto com id, código e descrição —\no integrador não precisa manter tabelas próprias de tradução.\n\nProduto de outro emitente é tratado como inexistente e devolve 404.","parameters":[{"name":"id","in":"path","schema":{"type":"integer"},"description":"ID do produto no estoque","required":true}],"responses":{"200":{"description":"Produto retornado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"ID do produto"},"codigo":{"type":"string","description":"Código do produto"},"descricao":{"type":"string","description":"Descrição do produto"},"status":{"type":"string","nullable":true,"description":"Status do produto"},"ativo":{"type":"boolean","description":"Se o produto está ativo"},"gtin":{"type":"string","nullable":true,"description":"Código de barras GTIN"},"codigo_de_barras_interno":{"type":"string","nullable":true,"description":"Código de barras interno"},"codigo_fornecedor":{"type":"string","nullable":true,"description":"Código do produto no fornecedor"},"numero_di":{"type":"string","nullable":true,"description":"Número da DI de origem"},"numero_duimp":{"type":"string","nullable":true,"description":"Número da DUIMP de origem"},"qtde":{"type":"number","format":"float","description":"Quantidade em estoque"},"qtde_armazenada":{"type":"number","format":"float","description":"Quantidade armazenada"},"qtde_comprometida":{"type":"number","format":"float","description":"Quantidade comprometida"},"pu":{"type":"number","format":"float","description":"Preço unitário de entrada"},"pu_saida":{"type":"number","format":"float","description":"Preço unitário de saída"},"pu_saida_com_ipi":{"type":"number","format":"float","description":"Preço de saída com IPI"},"aliquota_ipi":{"type":"number","format":"float","description":"Alíquota do IPI (%)"},"valor_ipi":{"type":"number","format":"float","description":"Valor do IPI"},"ncm":{"type":"string","nullable":true,"description":"Código NCM (mesmo formato da listagem)"},"created_at":{"type":"string","format":"datetime","nullable":true,"description":"Data de cadastro"},"ultima_modificacao":{"type":"string","format":"datetime","nullable":true,"description":"Data da última modificação"},"veiculo":{"type":"object","description":"Dados de veículo. Sempre presente; campos nulos quando o produto não é veículo","properties":{"chassi":{"type":"string","nullable":true,"description":"Chassi"},"tipo_operacao":{"type":"string","nullable":true,"description":"Tipo de operação"},"numero_motor":{"type":"string","nullable":true,"description":"Número do motor"},"ano_fabricacao":{"type":"string","nullable":true,"description":"Ano de fabricação"},"ano_modelo_fabricacao":{"type":"string","nullable":true,"description":"Ano do modelo de fabricação"}}},"classificacao_fiscal":{"type":"object","description":"NCM do produto, com descrição","properties":{"id":{"type":"integer","description":"ID da classificação fiscal"},"codigo":{"type":"string","nullable":true,"description":"Código NCM"},"descricao":{"type":"string","nullable":true,"description":"Descrição do NCM"}}},"unidade_de_medida":{"type":"object","nullable":true,"description":"Unidade de medida do produto","properties":{"id":{"type":"integer","description":"ID da unidade de medida"},"codigo":{"type":"string","nullable":true,"description":"Sigla da unidade"},"descricao":{"type":"string","nullable":true,"description":"Descrição da unidade"}}},"cest":{"type":"object","nullable":true,"description":"CEST do produto","properties":{"id":{"type":"integer","description":"ID do CEST"},"codigo":{"type":"string","nullable":true,"description":"Código CEST"},"descricao":{"type":"string","nullable":true,"description":"Descrição do CEST"}}},"icms_orig":{"type":"object","nullable":true,"description":"Origem da mercadoria para o ICMS","properties":{"id":{"type":"integer","description":"ID da origem"},"codigo":{"type":"integer","nullable":true,"description":"Código da origem"},"descricao":{"type":"string","nullable":true,"description":"Descrição da origem"}}},"categoria":{"type":"object","nullable":true,"description":"Categoria do produto","properties":{"id":{"type":"integer","description":"ID da categoria"},"nome":{"type":"string","nullable":true,"description":"Nome da categoria"}}},"subcategoria":{"type":"object","nullable":true,"description":"Subcategoria do produto","properties":{"id":{"type":"integer","description":"ID da subcategoria"},"nome":{"type":"string","nullable":true,"description":"Nome da subcategoria"},"nome_com_categoria":{"type":"string","nullable":true,"description":"Nome completo com categoria"}}},"pais_origem":{"type":"object","nullable":true,"description":"País de origem do produto","properties":{"id":{"type":"integer","description":"ID do país"},"nome":{"type":"string","nullable":true,"description":"Nome do país"},"codigo_siscomex":{"type":"string","nullable":true,"description":"Código Siscomex do país"},"codigo_a2":{"type":"string","nullable":true,"description":"Código ISO alpha-2 do país"}}},"finalidade_produto":{"type":"object","nullable":true,"description":"Finalidade do produto","properties":{"id":{"type":"string","format":"uuid","description":"ID da finalidade"},"codigo":{"type":"string","nullable":true,"description":"Código da finalidade"},"descricao":{"type":"string","nullable":true,"description":"Descrição da finalidade"}}},"tabela_de_venda":{"type":"object","nullable":true,"description":"Tabela de venda padrão do produto","properties":{"id":{"type":"integer","description":"ID da tabela"},"codigo":{"type":"string","nullable":true,"description":"Código da tabela"},"descricao":{"type":"string","nullable":true,"description":"Descrição da tabela"}}},"armazem":{"type":"object","nullable":true,"description":"Armazém do produto","properties":{"id":{"type":"string","format":"uuid","description":"ID do armazém"},"nome":{"type":"string","nullable":true,"description":"Nome do armazém"}}},"ultimo_armazem":{"type":"object","nullable":true,"description":"Último armazém que movimentou o produto","properties":{"id":{"type":"integer","description":"ID do stakeholder"},"razao_social":{"type":"string","nullable":true,"description":"Razão social"},"nome_fantasia":{"type":"string","nullable":true,"description":"Nome fantasia"}}},"fabricante":{"type":"object","nullable":true,"description":"Fabricante cadastrado do produto","properties":{"id":{"type":"integer","description":"ID do stakeholder"},"razao_social":{"type":"string","nullable":true,"description":"Razão social"},"nome_fantasia":{"type":"string","nullable":true,"description":"Nome fantasia"}}},"proprietario":{"type":"object","nullable":true,"description":"Proprietário do produto","properties":{"id":{"type":"integer","description":"ID do stakeholder"},"razao_social":{"type":"string","nullable":true,"description":"Razão social"},"nome_fantasia":{"type":"string","nullable":true,"description":"Nome fantasia"}}},"item_di":{"type":"object","nullable":true,"description":"Item da DI que originou o produto","properties":{"id":{"type":"integer","description":"ID do item da DI"},"codigo":{"type":"string","nullable":true,"description":"Código do item"},"cod_sequencial":{"type":"integer","nullable":true,"description":"Número do item dentro da adição"}}},"imagens":{"type":"array","description":"Lista de imagens do produto","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID da imagem"},"url":{"type":"string","description":"URL da imagem"},"principal":{"type":"boolean","nullable":true,"description":"Se é a imagem principal"}}}},"tags":{"type":"array","items":{"type":"string"},"description":"Lista de tags do produto"},"propriedades":{"type":"array","description":"Propriedades customizadas do produto","items":{"type":"object","properties":{"propriedade":{"type":"string","nullable":true,"description":"Nome da propriedade"},"valor":{"type":"string","nullable":true,"description":"Valor da propriedade"}}}},"tabelas_de_vendas":{"type":"array","description":"Tabelas de vendas do emitente com o preço calculado para este produto","items":{"type":"object","properties":{"codigo":{"type":"string","nullable":true,"description":"Código da tabela"},"descricao":{"type":"string","nullable":true,"description":"Descrição da tabela"},"pu_calculado":{"type":"number","format":"float","description":"Preço calculado"}}}}},"required":["id","codigo","descricao","veiculo","classificacao_fiscal","tabelas_de_vendas"]}}}},"404":{"description":"Produto não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Mensagem de erro"}}}}}}}}}}}
```

## Remove um produto

> \*\*Exclusão lógica do cadastro de um produto do estoque\*\*\
> \
> O produto não é apagado do banco: passa para o status de excluído e deixa de\
> aparecer na listagem de produtos. Notas fiscais e pedidos já emitidos continuam\
> íntegros, porque referenciam o cadastro — que permanece acessível pelo GET do\
> produto mesmo depois de excluído.\
> \
> A resposta de sucesso é o mesmo cadastro completo devolvido pelo GET, já com o\
> novo status.\
> \
> \*\*Travas que recusam a exclusão (todas devolvem 422):\*\*\
> \- \`item\_producao\` — o produto está em um planejamento de produção\
> \- \`composicao\` — o produto é matéria prima de outro produto\
> \- \`movimentacao\_estoque\` — o produto tem movimentação de estoque não excluída\
> \
> Cada motivo vem sob \*\*chave própria\*\* dentro de \`errors.fields\`, para que o\
> cliente distinga o caso sem interpretar o texto da mensagem. Quando mais de uma\
> trava existe, apenas a de maior prioridade é acusada, nesta ordem: item de\
> produção, composição, movimentação.\
> \
> \*\*Limitação conhecida:\*\* produto com saldo em estoque (\`qtde > 0\`) tem\
> movimentação de estoque associada e, por isso, \*\*nunca\*\* é excluível por este\
> endpoint — inclusive um produto recém-criado pelo POST desta mesma API. A\
> recusa nesse caso é o comportamento esperado, não falha do sistema.\
> \
> Produto de outro emitente é tratado como inexistente e devolve 404. Produto já\
> excluído também devolve 404: a operação não é idempotente.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"08. 📊 Controle de Estoque","description":"**Consulta de produtos e posições de estoque**\nConsulta de produtos cadastrados e histórico de posições de estoque.\n**Funcionalidades:**\n- Listagem de produtos cadastrados\n- Consulta de posição histórica de estoque\n- Geração de relatórios em Excel\n- Filtros por código, descrição, NCM e status"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/produtos/{id}":{"delete":{"summary":"Remove um produto","tags":["08. 📊 Controle de Estoque"],"description":"**Exclusão lógica do cadastro de um produto do estoque**\n\nO produto não é apagado do banco: passa para o status de excluído e deixa de\naparecer na listagem de produtos. Notas fiscais e pedidos já emitidos continuam\níntegros, porque referenciam o cadastro — que permanece acessível pelo GET do\nproduto mesmo depois de excluído.\n\nA resposta de sucesso é o mesmo cadastro completo devolvido pelo GET, já com o\nnovo status.\n\n**Travas que recusam a exclusão (todas devolvem 422):**\n- `item_producao` — o produto está em um planejamento de produção\n- `composicao` — o produto é matéria prima de outro produto\n- `movimentacao_estoque` — o produto tem movimentação de estoque não excluída\n\nCada motivo vem sob **chave própria** dentro de `errors.fields`, para que o\ncliente distinga o caso sem interpretar o texto da mensagem. Quando mais de uma\ntrava existe, apenas a de maior prioridade é acusada, nesta ordem: item de\nprodução, composição, movimentação.\n\n**Limitação conhecida:** produto com saldo em estoque (`qtde > 0`) tem\nmovimentação de estoque associada e, por isso, **nunca** é excluível por este\nendpoint — inclusive um produto recém-criado pelo POST desta mesma API. A\nrecusa nesse caso é o comportamento esperado, não falha do sistema.\n\nProduto de outro emitente é tratado como inexistente e devolve 404. Produto já\nexcluído também devolve 404: a operação não é idempotente.","parameters":[{"name":"id","in":"path","schema":{"type":"integer"},"description":"ID do produto no estoque","required":true}],"responses":{"200":{"description":"Produto excluído com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"ID do produto"},"codigo":{"type":"string","description":"Código do produto"},"descricao":{"type":"string","description":"Descrição do produto"},"status":{"type":"string","description":"Status do cadastro"}},"required":["id","codigo","descricao"]}}}},"404":{"description":"Produto não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Mensagem de erro"}}}}}},"422":{"description":"Exclusão recusada","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"fields":{"type":"object","description":"Motivo da recusa, sob a chave da trava acionada","properties":{"item_producao":{"type":"array","items":{"type":"string"}},"composicao":{"type":"array","items":{"type":"string"}},"movimentacao_estoque":{"type":"array","items":{"type":"string"}}}},"message":{"type":"string","description":"Mensagem de erro geral"}}}}}}}}}}}}}
```

## Edita um produto

> \*\*Edição parcial do cadastro de um produto do estoque\*\*\
> \
> Envie apenas os campos que quer alterar — os ausentes do payload permanecem\
> como estão. A resposta de sucesso é o mesmo cadastro completo devolvido pelo\
> GET do produto.\
> \
> \*\*Campos ignorados quando enviados (a requisição continua devolvendo 200):\*\*\
> \- \`qtde\` — saldo em estoque\
> \- \`qtde\_armazenada\` — saldo armazenado\
> \- \`qtde\_comprometida\` — saldo comprometido\
> \- \`pu\` — preço unitário de custo\
> \
> Saldo e custo são resultado de movimentação de estoque, não de cadastro:\
> gravá-los direto deixaria o saldo divergente do extrato de movimentações.\
> Ajuste de saldo pela API está fora do escopo deste endpoint, e enviar esses\
> campos \*\*não\*\* é erro — eles são descartados e o resto do payload é aplicado.\
> \
> \`status\` também não é aceito: inativar e reativar produto está fora do escopo.\
> \
> \*\*Campos traduzidos pela API (não são ids):\*\*\
> \- \`unidade\_de\_medida\_codigo\` — criada no cadastro se ainda não existir\
> \- \`classificacao\_fiscal\_codigo\` — NCM que \*\*deve existir\*\*; desconhecida devolve 422\
> \- \`top\_category\_description\` + \`category\_description\` — criadas se não existirem,\
> &#x20; e exigidas em par\
> \
> \*\*Travas deliberadas (ambas devolvem 422):\*\*\
> \- NCM desconhecida é recusada em vez de criada, para não gerar classificação\
> &#x20; fiscal incompleta que contaminaria o cálculo de imposto de uma NF-e futura\
> \- Código já usado por \*\*outro\*\* produto (ativo ou inativo) ou por um combo;\
> &#x20; reenviar o código que o próprio produto já tem não é duplicidade\
> \
> Ids de tabela de venda, armazém, fabricante e proprietário que não pertençam\
> ao emitente autenticado devolvem 422. Produto de outro emitente é tratado como\
> inexistente e devolve 404. Produto já excluído também devolve 404: o que foi\
> excluído não aceita mais edição, embora siga legível no GET.\
> \
> Trocar o NCM pode preencher o CEST automaticamente, quando houver um único\
> CEST associável — mesmo comportamento da tela.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"08. 📊 Controle de Estoque","description":"**Consulta de produtos e posições de estoque**\nConsulta de produtos cadastrados e histórico de posições de estoque.\n**Funcionalidades:**\n- Listagem de produtos cadastrados\n- Consulta de posição histórica de estoque\n- Geração de relatórios em Excel\n- Filtros por código, descrição, NCM e status"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/produtos/{id}":{"patch":{"summary":"Edita um produto","tags":["08. 📊 Controle de Estoque"],"description":"**Edição parcial do cadastro de um produto do estoque**\n\nEnvie apenas os campos que quer alterar — os ausentes do payload permanecem\ncomo estão. A resposta de sucesso é o mesmo cadastro completo devolvido pelo\nGET do produto.\n\n**Campos ignorados quando enviados (a requisição continua devolvendo 200):**\n- `qtde` — saldo em estoque\n- `qtde_armazenada` — saldo armazenado\n- `qtde_comprometida` — saldo comprometido\n- `pu` — preço unitário de custo\n\nSaldo e custo são resultado de movimentação de estoque, não de cadastro:\ngravá-los direto deixaria o saldo divergente do extrato de movimentações.\nAjuste de saldo pela API está fora do escopo deste endpoint, e enviar esses\ncampos **não** é erro — eles são descartados e o resto do payload é aplicado.\n\n`status` também não é aceito: inativar e reativar produto está fora do escopo.\n\n**Campos traduzidos pela API (não são ids):**\n- `unidade_de_medida_codigo` — criada no cadastro se ainda não existir\n- `classificacao_fiscal_codigo` — NCM que **deve existir**; desconhecida devolve 422\n- `top_category_description` + `category_description` — criadas se não existirem,\n  e exigidas em par\n\n**Travas deliberadas (ambas devolvem 422):**\n- NCM desconhecida é recusada em vez de criada, para não gerar classificação\n  fiscal incompleta que contaminaria o cálculo de imposto de uma NF-e futura\n- Código já usado por **outro** produto (ativo ou inativo) ou por um combo;\n  reenviar o código que o próprio produto já tem não é duplicidade\n\nIds de tabela de venda, armazém, fabricante e proprietário que não pertençam\nao emitente autenticado devolvem 422. Produto de outro emitente é tratado como\ninexistente e devolve 404. Produto já excluído também devolve 404: o que foi\nexcluído não aceita mais edição, embora siga legível no GET.\n\nTrocar o NCM pode preencher o CEST automaticamente, quando houver um único\nCEST associável — mesmo comportamento da tela.","parameters":[{"name":"id","in":"path","schema":{"type":"integer"},"description":"ID do produto no estoque","required":true}],"responses":{"200":{"description":"Produto atualizado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"ID do produto"},"codigo":{"type":"string","description":"Código do produto"},"descricao":{"type":"string","description":"Descrição do produto"},"ncm":{"type":"string","nullable":true,"description":"NCM da classificação fiscal"},"qtde":{"type":"number","format":"float","description":"Quantidade em estoque"}},"required":["id","codigo","descricao"]}}}},"404":{"description":"Produto não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Mensagem de erro"}}}}}},"422":{"description":"Payload recusado","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"fields":{"type":"object","description":"Campos recusados e seus motivos"},"message":{"type":"string","description":"Mensagem de erro geral"}}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"produto":{"type":"object","properties":{"descricao":{"type":"string","description":"Descrição do produto (máx. 120 caracteres)"},"codigo":{"type":"string","description":"Código do produto, único no emitente"},"pu_saida":{"type":"number","format":"float","description":"Preço unitário de venda"},"p_ipi":{"type":"number","format":"float","description":"Percentual de IPI"},"unidade_de_medida_codigo":{"type":"string","description":"Sigla da unidade de medida"},"classificacao_fiscal_codigo":{"type":"string","description":"NCM já cadastrado"},"top_category_description":{"type":"string","description":"Categoria principal"},"category_description":{"type":"string","description":"Subcategoria"},"icms_orig_id":{"type":"integer","description":"Origem do ICMS"},"cest_id":{"type":"integer","description":"ID do CEST"},"pais_origem_id":{"type":"integer","description":"ID do país de origem"},"finalidade_produto_id":{"type":"string","description":"ID da finalidade do produto"},"tabela_de_venda_id":{"type":"integer","description":"ID da tabela de venda do emitente"},"armazem_id":{"type":"string","format":"uuid","description":"ID do armazém do emitente"},"stakeholder_fabricante_id":{"type":"integer","description":"ID do fabricante do emitente"},"proprietario_id":{"type":"integer","description":"ID do proprietário do emitente"},"codigo_de_barras_gtin":{"type":"string","description":"Código de barras GTIN"},"codigo_fornecedor":{"type":"string","description":"Código do produto no fornecedor"},"property_indicator":{"type":"string","description":"Indicador de propriedade do produto"}}}},"required":["produto"]}}}}}}}}
```
