Guia de Orçamentos (Quotes)

Tipo de documento (negócio): Orçamento (ORC)

IDs ilustrativos

Os números nos exemplos JSON (ex.: "documentTypeId": 1) 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 ao orçamento (ORC) na base de dados do cliente. Veja Resolução dos IDs de tipo de documento.

Se não existir um tipo de documento de orçamento, crie um na API Base com POST /gateway/document-type (família de vendas, invoiceType / natureza ORC) e use depois o id desse tipo. Isto requer a permissão administrativa adequada. Detalhes: Guia de utilização – Criar tipos de documento.

Os orçamentos usam o mesmo endpoint POST /gateway/invoice/invoices que todos os documentos de venda. Consulte o Guia de utilização para autenticação, cabeçalhos e modelo de dados partilhado.

Visão Geral

Os orçamentos são documentos comerciais que:

📝 Apresentam propostas de venda ao cliente
💭 Não afetam stock na configuração típica de ORC
💵 Não liquidam pagamento — payments[] regista condições previstas, não numerário recebido
📄 Servem como base para faturas ou encomendas futuras
⏱️ Geralmente têm validade limitada

Quando Usar

✅ Proposta comercial antes da venda
✅ Apresentação de preços ao cliente
✅ Negociação de condições
✅ Base para aprovação de encomendas

Características dos Orçamentos

Característica	Valor	Descrição
Afeta Stock	❌ Não (típico)	Definido na configuração do tipo — não por campos nas linhas
Requer Array de Pagamentos	✅ Sim	`payments[]` obrigatório no contrato; valores reflectem condições propostas
Pode ser Fechado	✅ 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 ou encomenda

Movimento de stock

A movimentação de stock é determinada pela configuração do tipo de documento. Os tipos ORC estão normalmente configurados sem movimento de stock. As quantidades são sempre positivas.

Criar Orçamento

Exemplo Básico

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

{
  "serieId": 10,
  "documentTypeId": 1,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "entityDescription": "Cliente Potencial, Lda",
  "entityVat": "PT123456789",
  "obs": "Orçamento válido até 31/12/2025",
  "dueDate": "2025-12-31",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 6150
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Solução Completa",
      "quantity": 1,
      "retailPrice": 5000,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Defina payments[].amount com o total esperado do documento após impostos e descontos. Obtenha o paymentTypeId com GET /gateway/payment-types.

Orçamento com Desconto na Linha

Use discountPercentage (0–100):

{
  "serieId": 10,
  "documentTypeId": 1,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "obs": "Desconto especial para novo cliente",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 994.5
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10,
      "retailPrice": 100,
      "discountPercentage": 15,
      "observation": "Desconto por volume",
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Orçamento com Desconto no Cabeçalho

{
  "serieId": 10,
  "documentTypeId": 1,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "discountPercentage": 5,
  "dueDate": "2025-12-31",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 5700
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 1,
      "retailPrice": 5000,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Actualizar e Fechar Orçamento

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

{
  "id": 123,
  "obs": "Preços revistos — válido 30 dias",
  "dueDate": "2026-01-15"
}

Fechar quando aceite, rejeitado ou convertido:

{
  "id": 123,
  "close": true,
  "obs": "Convertido em fatura FT A/456"
}

Conversão em Fatura

A conversão é um processo de negócio: criar um novo documento fiscal com as linhas aprovadas — não existe endpoint de conversão automática.

1. Obter o orçamento aprovado:

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

2. Criar fatura (FT ou FR) com os mesmos dados comerciais:

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

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

Use o Guia de Faturas para FT/FS ou o Guia de Faturas-Recibo para FR. O movimento de stock na fatura segue a configuração do tipo de documento de fatura.

3. Fechar o orçamento original (ver acima).

Boas Práticas

✅ Recomendado

Enviar sempre currencyId e payments[] no cabeçalho
Incluir data de validade em dueDate
Detalhar condições comerciais em obs
Usar discountPercentage para descontos promocionais
Fechar orçamentos rejeitados ou expirados
Resolver tipos de documento com GET /gateway/document-type — Guia de utilização

❌ Evitar

Quantidades negativas
Deixar orçamentos abertos após conversão

Casos de Uso Comuns

Proposta Simples

Produto único com condições standard e data de validade.

Proposta com Desconto por Volume

discountPercentage progressivo nas linhas consoante a quantidade.

Proposta Multi-linha

Vários produtos ou serviços num único orçamento.

Proposta com Condições Especiais

Modo de pagamento personalizado via paymentModeId e payments[].

Diferenças face às Faturas

Aspecto	Orçamento (ORC)	Fatura (FT/FS)
Stock	Tipicamente nenhum	Saída (conforme tipo)
Fiscal	Não	Sim
Validade	Limitada	Definitiva
Edição	Sim (aberto)	Limitada
Finalidade	Proposta	Venda

Próximos Passos

Guia de Encomendas — Converter orçamento em encomenda (NE)
Guia de Faturas — Converter orçamento em fatura (FT/FS)
Guia de utilização — Informação geral da API

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

Visão Geral​

Quando Usar​

Características dos Orçamentos​

Criar Orçamento​

Exemplo Básico​

Orçamento com Desconto na Linha​

Orçamento com Desconto no Cabeçalho​

Actualizar e Fechar Orçamento​

Conversão em Fatura​

Boas Práticas​

✅ Recomendado​

❌ Evitar​

Casos de Uso Comuns​

Proposta Simples​

Proposta com Desconto por Volume​

Proposta Multi-linha​

Proposta com Condições Especiais​

Diferenças face às Faturas​

Próximos Passos​