Guia de Encomendas (Orders)

Tipo de documento (negócio): Encomenda (NE)

IDs ilustrativos

Os números nos exemplos JSON (ex.: "documentTypeId": 3) são ilustrativos; o mesmo valor pode representar outro tipo de documento noutra base de dados do cliente. Obtenha o id correto com GET /gateway/document-type e faça corresponder description / keyId à encomenda (NE) na base de dados do cliente. Veja Resolução dos IDs de tipo de documento.

As encomendas usam o mesmo endpoint POST /gateway/invoice/invoices. Consulte o Guia de utilização para o contrato partilhado (currencyId, payments[], discountPercentage).

Visão Geral

As encomendas são documentos que:

📦 Registam encomendas confirmadas do cliente
📋 Servem como confirmação e referência de picking
🔄 Podem ser convertidas em faturas (total ou parcial) através de um novo documento
🚚 Suportam fluxos de expedição antes da facturação

A reserva ou movimento de stock nas encomendas depende da configuração do tipo de documento NE.

Quando Usar

✅ Cliente confirma encomenda
✅ Acompanhar encomendas pendentes antes de faturar
✅ Facturar após entrega ou expedição
✅ Entregas parciais ao longo do tempo

Características das Encomendas

Característica	Valor	Descrição
Afeta Stock	⚠️ Conforme tipo	Reserva ou nenhum — configurado por tipo NE
Requer Array de Pagamentos	✅ Sim	`payments[]` obrigatório no contrato
Pode ser Fechada	✅ Sim	Pode ser finalizada
Validação Fiscal	❌ Não	Não é documento fiscal
Permite Edição	✅ Sim	Enquanto não fechada
Conversão	✅ Sim	Criar fatura ao facturar

Movimento de stock

O comportamento de stock segue a configuração do tipo de documento. Para activar reserva em encomendas, configure o tipo NE na API Base / backoffice. As quantidades são sempre positivas.

Criar Encomenda

Encomenda Básica

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}
X-Timezone: Europe/Lisbon

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "entityDescription": "Cliente Exemplo, Lda",
  "obs": "Encomenda confirmada por telefone",
  "dueDate": "2025-12-15",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 615
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Produto 1",
      "quantity": 10,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Encomenda com Desconto na Linha

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 553.5
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10,
      "retailPrice": 50,
      "discountPercentage": 10,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Encomenda em Backorder (stock insuficiente)

Crie a encomenda com as quantidades pedidas. Se o tipo NE estiver configurado para validar stock, a API devolve erro de validação quando o stock é insuficiente; caso contrário, a encomenda é aceite para facturação posterior:

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "obs": "Backorder — aguarda reposição de stock",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 6150
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 100,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Quando houver stock, converta em fatura (ver abaixo).

Actualizar e Fechar Encomenda

PUT /gateway/invoice/invoices/456
Content-Type: application/json
Authorization: Bearer {token}

{
  "id": 456,
  "obs": "Entrega agendada para 2025-12-20",
  "dueDate": "2025-12-20"
}

Fechar quando totalmente facturada ou cancelada:

{
  "id": 456,
  "close": true,
  "obs": "Totalmente facturada — FT A/789"
}

Conversão em Fatura

A facturação faz-se criando uma nova fatura — não existe endpoint de conversão automática.

Conversão Total

1. Obter a encomenda:

GET /gateway/invoice/invoices/456
Authorization: Bearer {token}

2. Criar a fatura:

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 615
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

A saída de stock na fatura segue a configuração do tipo FT. Ver Guia de Faturas.

3. Fechar a encomenda quando totalmente facturada.

Conversão Parcial

Facture apenas parte da encomenda — use quantidade positiva menor na fatura:

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "obs": "Facturação parcial — 5 de 10 unidades",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 307.5
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 5,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Encomenda permanece aberta

Na conversão parcial, mantenha a encomenda aberta até todas as quantidades serem facturadas.

Boas Práticas

✅ Recomendado

Enviar sempre currencyId e payments[] no cabeçalho
Definir entrega prevista em dueDate
Fechar encomendas totalmente facturadas
Manter notas de expedição em obs
Configurar comportamento de stock NE nas definições do tipo
Resolver tipos com GET /gateway/document-type — Guia de utilização

❌ Evitar

Quantidades negativas
Deixar encomendas abertas após facturação total
Criar encomendas duplicadas para o mesmo pedido

Casos de Uso Comuns

Encomenda Standard

Encomenda com stock disponível; facturar após picking.

Encomenda com Reserva

Tipo NE configurado para reservar stock até facturação ou cancelamento.

Cumprimento Parcial

Várias faturas ao longo do tempo para a mesma referência de encomenda.

Backorder

Encomenda aceite pendente de reposição; facturar quando chegar stock.

Diferenças face aos Orçamentos

Aspecto	Orçamento (ORC)	Encomenda (NE)
Compromisso	Proposta	Encomenda confirmada
Stock	Tipicamente nenhum	Conforme tipo NE
Validade	Limitada	Até cumprimento
Finalidade	Negociação	Confirmação

Diferenças face às Faturas

Aspecto	Encomenda (NE)	Fatura (FT/FS)
Stock	Conforme tipo NE	Saída (típico)
Fiscal	Não	Sim
Finalidade	Acompanhamento	Venda definitiva

Para correcções após facturação, use o Guia de Notas de Crédito.

Próximos Passos

Guia de Faturas — Converter encomenda em fatura (FT/FS)
Guia de Faturas-Recibo — Facturar e receber num só passo (FR)
Guia de Orçamentos — De orçamento para encomenda
Guia de utilização — Informação geral da API

Última actualização: 9 de junho de 2026

Visão Geral​

Quando Usar​

Características das Encomendas​

Criar Encomenda​

Encomenda Básica​

Encomenda com Desconto na Linha​

Encomenda em Backorder (stock insuficiente)​

Actualizar e Fechar Encomenda​

Conversão em Fatura​

Conversão Total​

Conversão Parcial​

Boas Práticas​

✅ Recomendado​

❌ Evitar​

Casos de Uso Comuns​

Encomenda Standard​

Encomenda com Reserva​

Cumprimento Parcial​

Backorder​

Diferenças face aos Orçamentos​

Diferenças face às Faturas​

Próximos Passos​