Guia de Faturas (Sales Invoices)

Tipos de documento (negócio): Fatura (FT) e Fatura Simplificada (FS)

IDs ilustrativos

Os números nos exemplos JSON (ex.: "documentTypeId": 5) 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 à fatura (FT) ou fatura simplificada (FS) na base de dados do cliente. Veja Resolução dos IDs de tipo de documento.

Tanto FT como FS usam o mesmo endpoint e a mesma estrutura de payload. O comportamento fiscal, movimento de stock e validações dependem do documentTypeId escolhido. Consulte o Guia de utilização para o modelo de dados partilhado.

Quando o pagamento é recebido no mesmo documento, use fatura-recibo (FR) — veja o Guia de Faturas-Recibo.

---

Visão Geral

As faturas de venda são documentos fiscais definitivos que:

• 🧾 Comprovam a venda de bens ou serviços
• 📉 Afetam stock (saída) — conforme a configuração do tipo de documento
• 💰 Exigem payments[] no cabeçalho e geram conta a receber quando não pagas na totalidade
• 📊 São registadas para efeitos fiscais e contabilísticos
• ✅ São documentos fiscais oficiais

Quando Usar

Natureza	Código	Uso típico
Fatura	FT	Vendas B2B, valores elevados, identificação completa do cliente
Fatura simplificada	FS	Retalho / POS, valores reduzidos dentro dos limites legais

• ✅ Venda definitiva de produtos ou serviços
• ✅ Emissão de documento fiscal
• ✅ Registo de receita e IVA

---

Características das Faturas

Característica	Valor	Descrição
Afeta Stock	✅ Sim	Saída — conforme o tipo de documento configurado
Requer Pagamento	✅ Sim	payments[] obrigatório no cabeçalho
Pode ser Fechada	✅ Sim	Finalização obrigatória
Validação Fiscal	✅ Sim	Documento fiscal oficial
Permite Edição	⚠️ Limitada	Só antes de fechar
Cancelamento	⚠️ Via Nota de Crédito	Não pode ser eliminada — veja Guia de Notas de Crédito

Movimento de stock

A movimentação de stock segue a configuração do tipo de documento e do artigo. As quantidades nas linhas são sempre positivas.

---

Criar Fatura

Exemplo Completo (FT)

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

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "entityDescription": "Cliente Exemplo, Lda",
  "entityVat": "PT123456789",
  "entityAddress": "Rua Exemplo, 123",
  "entityPostalCode": "1000-000",
  "entityCity": "Lisboa",
  "entityCountry": "Portugal",
  "paymentModeId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 123
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Produto 1",
      "quantity": 2,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

A soma de payments[].amount deve corresponder ao total do documento. Obtenha o paymentTypeId na configuração de GET /gateway/payment-types.

Resposta (201 Created) — campos relevantes:

{
  "id": 123,
  "documentNumber": "FT A/1",
  "total": 123,
  "totalTaxes": 23,
  "totalDiscounts": 0,
  "change": 0,
  "netChange": 0,
  "guid": "550e8400-e29b-41d4-a716-446655440000"
}

Quando o cliente paga acima do total com um tipo de pagamento que permite troco (ex.: numerário), a resposta inclui change e netChange.

Fatura com Desconto na Linha

Use discountPercentage (0–100) para descontos no cabeçalho e nas linhas:

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

Fatura com Desconto no Cabeçalho

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

Fatura com menu ou artigo composto

Menus exigem linhas filho com guid / parentGuid para as opções seleccionadas. Artigos compostos podem ir numa única linha (só o itemKeyId do composto). Ver o Guia de utilização — exemplos de menu e artigo composto.

Fatura Isenta de IVA

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

Fatura Simplificada (FS)

Use o documentTypeId cujo invoiceType seja FS. O payload é o mesmo; os limites legais vêm das definições do tipo de documento FS:

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

---

Pagamento Múltiplo

Divida o pagamento por vários mecanismos no cabeçalho:

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

Se o cliente pagar 130 € em numerário por um total de 123 €, o change é calculado automaticamente quando o tipo de pagamento o permite:

{
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 130
    }
  ]
}

Exemplo de excerto da resposta:

{
  "total": 123,
  "change": 7,
  "netChange": 7
}

---

Limites legais (FS)

Na emissão de FS, os totais são verificados face aos limiares configurados no tipo de documento (GET /gateway/document-type). Campos típicos:

Definição	Finalidade
limitValue	Total líquido máximo permitido para FS. Acima deste limite, a operação falha ou o sistema pode sugerir/usar um tipo substituto (ex.: FT).
fullInfoLimit	Quando o total líquido excede este valor, são obrigatórios dados fiscais completos do cliente (nome, morada, NIF, etc.).
nifLimit	Quando o total líquido excede este valor, é obrigatório um NIF/VAT válido — o NIF genérico 999999990 não é aceite.

Estes limites reflectem regras fiscais portuguesas (ex.: artigo 40.º do CIVA para FS) e as definições do tipo de documento. Na dúvida, use FT para vendas B2B ou de valor elevado com identificação completa do cliente.

Códigos de validação comuns: SaleDocumentRules.FS.AboveLegal, SaleDocumentRules.Nif.RequiredVat, SaleDocumentRules.FullInfo.RequiredCustomer, SaleDocumentRules.FullInfo.CustomerFiscalData.

---

Atualizar Fatura

Atualizar Observações

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

{
  "id": 123,
  "obs": "Observações actualizadas"
}

Fechar Fatura

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

{
  "id": 123,
  "close": true
}

Atenção

Depois de fechar a fatura, não pode ser editada. Para corrigir, use uma Nota de Crédito.

---

Obter Fatura

Por ID

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

Por Número

GET /gateway/invoice/invoices/5/1/1
Authorization: Bearer {token}

Parâmetros: documentTypeId=5, serieId=1, number=1

Listar Faturas

GET /gateway/invoice/invoices?documentTypeId=5&status=Open&page=1&pageSize=20
Authorization: Bearer {token}

---

Ciclo de Vida da Fatura

1. Criar: Fatura criada com estado Open
2. Editar: Possível enquanto Open
3. Fechar: Finalizar fatura (estado Closed)
4. Correção: Apenas via Nota de Crédito

---

Validações Importantes

Dados Obrigatórios

• ✅ serieId — Série configurada para faturas
• ✅ documentTypeId — Tipo de documento FT ou FS
• ✅ entityKeyId — Cliente válido
• ✅ currencyId — Identificador de moeda (> 0)
• ✅ documentBodies — Pelo menos uma linha com quantidades positivas
• ✅ payments[] — Pelo menos uma entrada com paymentTypeId e amount

Validações Fiscais

• ✅ NIF/VAT do cliente quando o valor excede nifLimit (especialmente em FS)
• ✅ Morada completa quando o valor excede fullInfoLimit
• ✅ Código e motivo de isenção quando aplicável
• ✅ Taxa de IVA correcta por linha

Stock

• ✅ Artigo existe e stock disponível quando o tipo de documento está configurado para movimentar stock
• ✅ A movimentação de stock segue a configuração do tipo de documento

---

Boas Práticas

✅ Recomendado

• Enviar sempre currencyId e payments[] no cabeçalho
• Resolver documentTypeId e tipos de pagamento via API — Guia de utilização
• Validar stock antes de criar a fatura (quando o FT movimenta stock)
• Incluir morada completa para valores elevados
• Definir data de vencimento em vendas a crédito
• Fechar a fatura assim que confirmada
• Usar FT quando os limites de FS seriam excedidos

❌ Evitar

• Quantidades negativas em FT/FS (use Notas de Crédito para estornos)
• Deixar faturas abertas indefinidamente
• Tentar editar fatura fechada

---

Casos de Uso Comuns

Fatura Simples (FT)

Venda directa com dados completos do cliente e pagamento único.

Fatura Simplificada (FS)

Venda de retalho dentro dos limites legais; garantir regras de NIF para o total.

Fatura de Serviços

Linhas de serviço com quantidades positivas; movimento de stock depende do artigo e do tipo de documento.

---

Correções e Cancelamentos

❌ ERRADO: Editar ou eliminar fatura fechada, ou usar quantidades negativas em FT/FS.

✅ CORRECTO: Emitir Nota de Crédito (NC) com referência à fatura original, quantidades positivas e referências de linha conforme descrito nesse guia.

---

Integração com Outros Documentos

De Orçamento para Fatura

Ver Guia de Orçamentos

De Encomenda para Fatura

Ver Guia de Encomendas

Fatura para Recibo / FR

Para pagamento no mesmo documento, ver Guia de Faturas-Recibo. A natureza RE não está disponível nesta API — ver Guia de utilização.

---

Próximos Passos

• Guia de utilização — Modelo partilhado, cabeçalhos e endpoints
• Guia de Notas de Crédito — Correções e devoluções
• Guia de Faturas-Recibo — FR com pagamento no mesmo documento
• Guia de Orçamentos — Propostas ORC
• Guia de Encomendas — Encomendas NE

---

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