Fulfillment - Manual da API
  1. Produtos
Fulfillment - Manual da API
  • 🚀 Introdução
  • 🔒 Autenticação
  • 🚦 Rate Limiting
  • Autenticação
    • Autenticação
    • Sessão do usuário
    • Refresh Token
    • Finalizar Sessão
  • Produtos
    • 📦 Conceitos de Produtos
    • Gerenciamento
      • Coleção de produtos
        GET
      • Criar um novo produto
        POST
      • Detalhes do produto
        GET
      • Estoque do Produto
        GET
      • Modificar Produto
        PUT
      • Excluir Produto
        DELETE
    • Controle
      • Controle de Temperatura
        PUT
      • Controle de Estoque
        PUT
      • Data de validade & Lote
        PUT
    • Códigos fiscais
      • Códigos Fiscais de Produtos
      • Códigos fiscais
        GET
      • Código fiscal
        POST
      • Código fiscal
        GET
      • Código fiscal
        PUT
      • Código fiscal
        DELETE
    • RMA
      • Estatísticas
        GET
      • Qualidade
        GET
      • Ocorrências
        GET
  • Tipos de Operações
    • ♻️ Tipos de Operação
    • 📦 Entrada de Mercadoria
    • Tipos de Operações
    • Tipo de Operação
  • Clientes
    • 👔 Clientes & Parceiros
    • Gerenciamento
      • Coleção de Clientes
      • Novo cliente
      • Detalhes
      • Modificar
      • Excluir
    • Endereços
      • Endereços
      • Adicionar Endereço
      • Detalhes do Endereço
      • Modificar Endereço
  • Pedidos - Gerenciamento
    • 🛒 Pedidos Fulfillment
    • Gerenciamento
      • Pedidos
      • Novo Pedido
      • Detalhes do Pedido
      • Confirmar Pedido
      • Update Order
    • Workflows
      • Situação atual de um pedido
      • Fluxos de execução disponíveis
      • Avançar Workflow
      • Cancelar Pedido / Workflow
    • Itens do Pedido
      • Gerenciamento
        • Itens do Pedido
        • Adicionar Item
        • Detalhes do Item
        • Modificar Item
        • Excluir Item
      • Rastreamento
        • Rastreamentos
        • Adicionar Rastreamento
        • Detalhes do Rastreamento
        • Excluir Rastreamento
    • Agendamento
      • Agendamento
      • Slots Disponíveis
      • Reservar Slots
      • Cancelar Agendamento
      • Confirmar Agendamento
    • Identificação de Produtos
      • Etiquetas
      • Gerar Etiquetas
      • Confirmar impressão
    • Documentos Fiscais
      • Documentos Fiscais
      • Documento Fiscal
      • Detalhes do Documento
      • Excluir Documento
    • Documentos para Impressão
      • Documentos
      • Adicionar Documento
      • Detalhes do Documento
      • Pré-visualização
      • Excluir Documento
  • Pedidos - Aguardando NFe
    • Totais
    • Aguardando NFe
    • Detalhes Fiscal
  • Configurações
    • Webhooks
      • Webhooks
      • Webhook
      • Webhook
      • Webhook
      • Webhook
      • Histórico
      • Estatísticas
      • Teste
      • Eventos Disponíveis
    • Enumeração
      • Enumeração
      • Tipos disponíveis
    • Token de API
      • Token de API
      • Criar um novo Token
  • Locais de Estoque
    • Localizações Exclusivas
    • Ocupação das Localizações
    • Detalhes de uma Localização
    • Produtos de uma Localização
  • Inventário
    • Resumo Geral do Estoque
    • Inventário Detalhado
    • Produtos com Estoque Baixo
    • Consulta Detalhada de Estoque
  1. Produtos

📦 Conceitos de Produtos

O que é um Produto no WMS? 🤔#

No sistema WMS, cada produto é único e indivisível. Isso significa que se você possui um item com variações (como diferentes cores, tamanhos ou sabores), cada variação deve ser cadastrada como um produto separado.

Estrutura de um Produto#

Cada produto possui as seguintes informações obrigatórias organizadas em grupos:

Identificação#

SKU: Código único interno (ex: ALIM-CAFE-CX12)
Nome e Descrição: Identificação comercial
Tipo de Produto: Produto acabado, Matéria prima...
Unidade: Forma de medição (consulte o endpoint de enumeração)
Custo unitário: Valor de custo do produto para uso interno
Código de barras: Campo opcional (obrigatório apenas se has_ean = true)
Status: Se o produto está ativo no sistema

Dimensões Físicas (dimensions)#

Altura, Largura, Comprimento: Em centímetros (cm) (mín. 0,1 cm)
Peso: Em quilogramas (kg) (mín. 0,001 kg)

Características Especiais (characteristics)#

Perigoso: Material que requer cuidados especiais (is_dangerous)
Frágil: Produto que requer manuseio cuidadoso (is_fragile)
Número de série: Controle individual por unidade (has_serial_number)
Controle de lote: Controle por lotes de fabricação (has_batch_control)
Código EAN: Para produtos com código de barras padrão (has_ean)

Controle de Estoque (stock_control)#

Prioridade: Urgência para reabastecimento (0=sem controle, 1=baixa, 2=média, 3=alta)
Estoque mínimo: Quantidade que aciona alerta
Estoque ideal: Meta de reposição

Controle de Validade (expiration_control)#

Tem validade: Se o produto possui data de vencimento (has_expiration_date)
Vida útil: Dias de validade do produto (shelf_life_days)
Validade mínima: Dias mínimos antes do vencimento para venda (min_remaining_shelf_life)
Alerta de vencimento: Dias de antecedência para alertas (expiration_alert_days)

Controle de Temperatura (temperature_control)#

Refrigerado: Produto que precisa de temperatura controlada (is_refrigerated)
Temperatura mínima: Limite inferior de armazenamento (°C)
Temperatura máxima: Limite superior de armazenamento (°C)

Principais Operações com Produtos#

CRUD Básico#

Gestão de Estoque#

Configurações Avançadas#

Tipos de Controle Disponíveis#

1. Controle de Estoque 📦#

Configure pontos de reposição automática:
Estoque mínimo: Quantidade que aciona alerta
Estoque ideal: Meta de reposição
Prioridade: Urgência para reabastecimento (0=sem controle, 1=baixa, 2=média, 3=alta)

2. Controle de Validade 📅#

Para produtos perecíveis:
Vida útil: Dias de validade do produto
Validade mínima: Dias mínimos antes do vencimento para venda
Alerta de vencimento: Dias de antecedência para alertas

3. Controle de Temperatura 🌡️#

Para produtos refrigerados:
Temperatura mínima: Limite inferior de armazenamento
Temperatura máxima: Limite superior de armazenamento

Unidades de Medida Disponíveis#

Para obter os valores válidos das unidades de medida, utilize o endpoint de enumeração:
GET /api/v1/enums/product-unit
Importante sobre conversão de unidades:
Algumas unidades permitem conversão entre si, enquanto outras são específicas
Conversões ocorrem nas fronteiras do sistema (DTOs) e são mantidas consistentes internamente em cm e kg

Regras Importantes ⚠️#

Unicidade do SKU#

Cada SKU deve ser único dentro do seu escopo (cliente ou global)
Não é possível ter dois produtos com o mesmo SKU

Exclusão de Produtos#

Produtos com estoque não podem ser excluídos
Produtos vinculados a pedidos não podem ser excluídos

Como Cadastrar Produtos 📝#

Produtos com Variações - Exemplos Práticos#

Exemplo prático:
❌ Não cadastre: "Camiseta Polo"
✅ Cadastre separadamente:
"Camiseta Polo Azul P" (SKU: CAM-POLO-AZ-P)
"Camiseta Polo Azul M" (SKU: CAM-POLO-AZ-M)
"Camiseta Polo Vermelha P" (SKU: CAM-POLO-VM-P)
Como mencionado, cada variação é um produto único:
// ❌ Incorreto - um produto com múltiplas variações
{
  "sku": "TENIS-NIKE",
  "name": "Tênis Nike",
  "variations": ["37", "38", "39"]
}

// ✅ Correto - cada variação é um produto
[
  {
    "sku": "TENIS-NIKE-37",
    "name": "Tênis Nike Air Max Tamanho 37"
  },
  {
    "sku": "TENIS-NIKE-38",
    "name": "Tênis Nike Air Max Tamanho 38"
  },
  {
    "sku": "TENIS-NIKE-39",
    "name": "Tênis Nike Air Max Tamanho 39"
  }
]

Exemplo de Cadastro Completo#

{
  "sku": "SUPER-CAFE-123",
  "name": "Café Gourmet (Cx 12x500g)",
  "description": "Caixa com 12 pacotes de café gourmet torrado e moído",
  "product_type": "finished_good",
  "unit_cost": 239.9,
  "unit": "un",
  "has_ean": true|false, // true permite a alteração do barcode
  "barcode": "",
  "is_active": true,
  
  // Dimensões físicas agrupadas
  "dimensions": {
    "height": 40,      // altura em centímetros
    "width": 30,       // largura em centímetros
    "length": 20,      // comprimento em centímetros
    "weight": 6        // peso em quilogramas
  },
  
  // Características especiais agrupadas
  "characteristics": {
    "is_dangerous": false,
    "is_fragile": false,
    "has_serial_number": false,
    "has_batch_control": true,
    "has_ean": false
  },
  
  // Configurações de controle de estoque
  "stock_control": {
    "restock_priority": 3,          // 0=sem controle, 1=baixa, 2=média, 3=alta
    "min_stock_quantity": 5,        // estoque mínimo
    "ideal_stock_quantity": 15      // estoque ideal
  },
  
  // Configurações de controle de validade
  "expiration_control": {
    "has_expiration_date": true,
    "shelf_life_days": 180,           // vida útil em dias
    "min_remaining_shelf_life": 30,   // validade mínima para venda
    "expiration_alert_days": 45       // dias de antecedência para alerta
  },
  
  // Configurações de controle de temperatura
  "temperature_control": {
    "is_refrigerated": true,
    "storage_temp_min": 0.1,        // temperatura mínima em °C
    "storage_temp_max": 12          // temperatura máxima em °C
  }
}

Configuração Fiscal#

A configuração fiscal dos produtos inclui múltiplos códigos fiscais por produto, permitindo diferentes configurações para diferentes cenários operacionais.
Cada código fiscal pode incluir NCM, CSTs, alíquotas e outras informações fiscais detalhadas. Para mais detalhes, consulte a documentação específica de códigos fiscais.
Códigos Fiscais
Modified at 2025-09-05 15:16:40
Previous
Finalizar Sessão
Next
Coleção de produtos
Built with