Produtos e Estoque

Este endpoint é responsável pelo gerenciamento do cadastro de produtos e seus respectivos custos.

Objeto Produto

Atributo	Tipo	Descrição
id	string	O ID único do produto (UUID).
name	string	O nome do produto.
description	string	Opcional. Uma descrição para o produto.
sku	string	Opcional. Código único para identificação interna do produto.
category	string	Opcional. Categoria do produto (ex: "Informática", "Mobiliário").
brand	string	Opcional. Marca do produto.
minimum_stock	integer	Opcional. Quantidade mínima em estoque para alerta.
unit	string	Opcional. Unidade de medida do produto (ex: "Unidade", "Caixa").
ncm	string	Opcional. Nomenclatura Comum do Mercosul (8 dígitos).
quantity_in_stock	integer	A quantidade atual do produto em estoque.
organization_id	string	O ID da organização à qual o produto pertence.
accounting_period_id	string	O ID do período contábil ao qual o produto pertence.

---

Listar Produtos

Retorna uma lista paginada de todos os produtos para a organização e período contábil ativos.

GET/api/products

Parâmetros de Query

Parâmetro	Tipo	Descrição
page	integer	Opcional. O número da página a ser retornada (padrão: 1).
limit	integer	Opcional. O número máximo de itens por página (padrão: 10).

Resposta

{
  "data": [
    {
      "id": "p1q2r3s4-t5u6-7890-1234-567890abcdef",
      "name": "Produto Exemplo A",
      "description": "Componente eletrônico principal",
      "sku": "SKU001",
      "category": "Eletrônicos",
      "brand": "MarcaX",
      "minimum_stock": 10,
      "unit": "Unidade",
      "ncm": "85044021",
      "quantity_in_stock": 100
    }
  ],
  "count": 1
}

Códigos de Status HTTP

• 200 OK: Produtos listados com sucesso.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 500 Internal Server Error: Erro interno do servidor ao listar os produtos.

---

Criar um Produto

Cria um novo produto. O estoque inicial é zero.

POST/api/products

Corpo da Requisição

{
  "name": "Produto Exemplo B",
  "description": "Componente secundário",
  "sku": "SKU002",
  "category": "Componentes",
  "brand": "MarcaY",
  "minimum_stock": 5,
  "unit": "Unidade",
  "ncm": "85044022"
}

Resposta

Retorna o objeto do produto recém-criado.

Códigos de Status HTTP

• 201 Created: Produto criado com sucesso.
• 400 Bad Request: Dados da requisição inválidos (ex: nome ausente).
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 500 Internal Server Error: Erro interno do servidor ao criar o produto.

---

Atualizar um Produto

Atualiza os detalhes de um produto existente.

PUT/api/products/{id}

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	string	O ID do produto a ser atualizado.

Corpo da Requisição

{
  "name": "Produto Exemplo B (Revisado)",
  "description": "Componente secundário - versão 2.0",
  "minimum_stock": 7
}

Resposta

Retorna o objeto do produto atualizado.

Códigos de Status HTTP

• 200 OK: Produto atualizado com sucesso.
• 400 Bad Request: Dados da requisição inválidos.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 404 Not Found: Produto não encontrado.
• 500 Internal Server Error: Erro interno do servidor ao atualizar o produto.

---

Deletar um Produto

Exclui um produto do cadastro.

DELETE/api/products/{id}

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	string	O ID do produto a ser deletado.

Resposta

204 No Content em caso de sucesso.

Códigos de Status HTTP

• 204 No Content: Produto deletado com sucesso.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 403 Forbidden: O produto não pode ser deletado (ex: possui movimentações de estoque ou lançamentos associados). |
• 404 Not Found: Produto não encontrado.
• 500 Internal Server Error: Erro interno do servidor ao deletar o produto.

---

Registrar Compra de Produto

Registra a compra de um produto, atualizando o estoque e criando um novo lote de inventário.

POST/api/products/purchase

Corpo da Requisição

{
  "product_id": "p1q2r3s4-t5u6-7890-1234-567890abcdef",
  "quantity": 50,
  "unit_cost": 12.50
}

Atributo	Tipo	Descrição
product_id	string	Obrigatório. O ID do produto comprado.
quantity	integer	Obrigatório. A quantidade comprada.
unit_cost	number	Obrigatório. O custo unitário da compra.

Resposta

200 OK com uma mensagem de sucesso.

Códigos de Status HTTP

• 200 OK: Compra registrada e estoque atualizado com sucesso.
• 400 Bad Request: Dados da requisição inválidos.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 404 Not Found: Produto não encontrado.
• 500 Internal Server Error: Erro interno do servidor ao registrar a compra.

---

Calcular Custo da Mercadoria Vendida (CMV)

Calcula o Custo da Mercadoria Vendida (CMV) para uma venda de produto, com base no método de custeio configurado para o período contábil.

POST/api/products/calculate-cogs

Corpo da Requisição

{
  "product_id": "p1q2r3s4-t5u6-7890-1234-567890abcdef",
  "quantity_sold": 10
}

Atributo	Tipo	Descrição
product_id	string	Obrigatório. O ID do produto vendido.
quantity_sold	integer	Obrigatório. A quantidade vendida.

Resposta

200 OK com o valor do CMV calculado.

{
  "cogs": 125.00
}

Códigos de Status HTTP

• 200 OK: CMV calculado com sucesso.
• 400 Bad Request: Dados da requisição inválidos (ex: product_id ou quantity_sold ausente/inválido).
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 404 Not Found: Produto não encontrado.
• 500 Internal Server Error: Erro interno do servidor ao calcular o CMV.