Guia de Encomendas (Orders)

Tipo de Documento: Encomenda
Document Type ID: 3 (verificar com /document-type)

---

Visão Geral

As Encomendas (Orders) são documentos que:

• 📦 Registam pedidos de clientes
• ⚠️ OPCIONALMENTE reservam stock
• 🔄 Podem ser convertidas em faturas (total ou parcial)
• 📋 Servem como confirmação de pedido
• 🚚 Base para picking e expedição

Quando Usar

• ✅ Cliente confirma pedido
• ✅ Necessário reservar stock
• ✅ Controlar encomendas pendentes
• ✅ Faturação posterior à encomenda

---

Características das Encomendas

Característica	Valor	Descrição
Afeta Stock	⚠️ Opcional	Pode reservar stock
Requer Pagamento	❌ Não	Pedido confirmado
Pode ser Fechada	✅ Sim	Pode ser finalizado
Validação Fiscal	❌ Não	Não é documento fiscal
Permite Edição	✅ Sim	Enquanto não fechado
Conversão	✅ Sim	Pode gerar Fatura

---

Criar Encomenda

Encomenda Básica

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "entityDescription": "Cliente Exemplo, Lda",
  "obs": "Encomenda confirmada via telefone",
  "docReference": "PO-2025-001",
  "dueDate": "2025-12-15",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Produto 1",
      "quantity": 10.0,
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 0,              // Não afeta stock
      "stockBehavior": 0,          // Sem validação stock
      "secondTaxId": 0
    }
  ]
}

Encomenda com Reserva de Stock

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "obs": "Stock reservado até 31/12/2025",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10.0,
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 2,              // Reserva de stock
      "stockBehavior": 1,          // Valida disponibilidade
      "originWarehouse": 1,
      "secondTaxId": 0
    }
  ]
}

Reserva de Stock

Use stockFlow = 2 para reservar stock. O stock fica bloqueado para outras vendas.

---

Conversão para Fatura

Conversão Total

1. Obter encomenda:

GET /api/v1/invoices/456
Authorization: Bearer {token}

2. Criar fatura:

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}

{
  "serieId": 1,
  "documentTypeId": 5,             // Fatura
  "entityKeyId": "CLI001",
  "docReference": "EC A/456",      // Referência à encomenda
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10.0,            // Quantidade total
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 1,              // Saída de stock
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

3. Fechar encomenda:

PUT /api/v1/invoices/456

{
  "id": 456,
  "close": true,
  "obs": "Faturado totalmente - FT A/789"
}

Conversão Parcial

Para faturar apenas parte da encomenda, crie fatura com quantidade menor:

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "docReference": "EC A/456 (Parcial)",
  "obs": "Faturação parcial - 5 de 10 unidades",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 5.0,             // Apenas 5 unidades
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 1,
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

Encomenda Continua Aberta

Em conversão parcial, a encomenda permanece aberta para faturações futuras.

---

Gestão de Backorders

Cenário: Stock Insuficiente

Se não houver stock suficiente, crie encomenda sem reserva:

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "obs": "Backorder - aguardar reposição de stock",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 100.0,           // Quantidade solicitada
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 0,              // Sem reserva (backorder)
      "stockBehavior": 0,          // Sem validação
      "secondTaxId": 0
    }
  ]
}

Quando stock disponível, converta para fatura.

---

Boas Práticas

✅ Recomendado

• Validar stock antes de reservar
• Usar referência do pedido do cliente
• Definir prazo de entrega em dueDate
• Fechar encomendas totalmente faturadas
• Manter histórico no campo obs
• Usar reserva de stock quando apropriado

❌ Evitar

• Reservar stock sem necessidade
• Deixar encomendas abertas após faturação
• Esquecer de referenciar encomenda na fatura
• Criar múltiplas encomendas para mesmo pedido

---

Casos de Uso Comuns

Encomenda Padrão

Cliente faz pedido, stock disponível, faturação imediata.

Encomenda com Reserva

Cliente faz pedido, stock reservado, faturação posterior.

Encomenda Parcial

Cliente faz pedido grande, entregas/faturas parciais.

Backorder

Cliente faz pedido, stock insuficiente, aguarda reposição.

---

Fluxos de Stock

Valor stockFlow	Comportamento	Quando Usar
0	Não afeta stock	Backorder, encomenda sem reserva
1	Saída de stock	NÃO usar em encomendas
2	Reserva de stock	Encomenda com reserva
-1	Entrada de stock	NÃO usar em encomendas

---

Diferenças vs Orçamentos

Aspecto	Orçamento	Encomenda
Compromisso	Proposta	Pedido confirmado
Stock	Nunca afeta	Pode reservar
Validade	Limitada	Até cumprir
Objetivo	Negociação	Confirmação

---

Diferenças vs Faturas

Aspecto	Encomenda	Fatura
Stock	Reserva (opcional)	Saída
Fiscal	Não	Sim
Pagamento	Não exigido	Exigido
Objetivo	Pedido	Venda definitiva

---

Próximos Passos

• Guia de Faturas - Converter encomenda em fatura
• Guia de Orçamentos - De orçamento para encomenda
• Guia de Utilização - Informações gerais da API

---

Última Atualização: 28 de Novembro de 2025