Pular para o conteúdo principal

Guia de Faturas (Sales Invoices)

Tipo de Documento: Fatura de Venda
Document Type ID: 5 (verificar com /document-type)

Visão Geral​

As Faturas (Sales Invoices) são documentos fiscais definitivos que:

  • 🧾 Comprovam a venda de bens ou serviços
  • 📉 AFETAM stock (saída)
  • 💰 Geram contas a receber
  • 📊 Registadas para efeitos fiscais e contabilísticos
  • ✅ Documento fiscal oficial

Quando Usar​

  • ✅ Venda definitiva de produtos/serviços
  • ✅ Emissão de documento fiscal
  • ✅ Registar receita da empresa
  • ✅ Contabilização de IVA

Características das Faturas​

CaracterísticaValorDescrição
Afeta Stock✅ SimSaída de stock
Requer Pagamento✅ SimGera conta a receber
Pode ser Fechada✅ SimFinalização obrigatória
Validação Fiscal✅ SimDocumento fiscal oficial
Permite Edição⚠️ LimitadaSó antes de fechar
Cancelamento⚠️ Via Nota CréditoNão pode ser deletada

Criar Fatura​

Exemplo Completo​

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}
{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "entityDescription": "Cliente Exemplo, Lda",
  "entityVat": "PT123456789",
  "entityAddress": "Rua Exemplo, 123",
  "entityPostalCode": "1000-000",
  "entityCity": "Lisboa",
  "entityCountry": "Portugal",
  "obs": "Fatura referente ao pedido PO-2025-001",
  "docReference": "PO-2025-001",
  "dueDate": "2025-12-31",
  "paymentModeId": 1,
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Produto 1",
      "quantity": 2.0,
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 1,              // Saída de stock
      "stockBehavior": 1,          // Comportamento normal
      "secondTaxId": 0
    }
  ]
}

Fatura com Desconto​

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10.0,
      "retailPrice": 100.00,
      "discountValue": 10.00,      // Desconto por linha
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 1,
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

Fatura Isenta de IVA​

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "exemptionCode": "M01",          // Código de isenção
  "exemptionReason": "Isento ao abrigo do artigo 9.º do CIVA",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 1.0,
      "retailPrice": 100.00,
      "taxId": 2,                  // Taxa de isenção
      "paymentType": 1,
      "stockFlow": 1,
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

Atualizar Fatura​

Atualizar Observações​

PUT /api/v1/invoices/123
Content-Type: application/json
Authorization: Bearer {token}
{
  "id": 123,
  "obs": "Observações atualizadas",
  "docReference": "PO-2025-001-REV"
}

Fechar Fatura​

PUT /api/v1/invoices/123
Content-Type: application/json
Authorization: Bearer {token}
{
  "id": 123,
  "close": true
}
Atenção

Após fechar a fatura, não é possível editá-la. Para corrigir use Nota de Crédito.

Obter Fatura​

Por ID​

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

Por Número​

GET /api/v1/invoices/5/1/1
Authorization: Bearer {token}

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

Listar Faturas​

GET /api/v1/invoices?documentTypeId=5&status=Open&pageNumber=1&pageSize=20
Authorization: Bearer {token}

Ciclo de Vida da Fatura​

graph LR
    A[Criar Fatura] --> B[Status: Open]
    B --> C[Editar se necessário]
    C --> D[Fechar Fatura]
    D --> E[Status: Closed]
    E --> F{Precisa corrigir?}
    F -->|Sim| G[Criar Nota de Crédito]
    F -->|Não| H[Fim]
  1. Criar: Fatura criada com status Open
  2. Editar: Possível editar enquanto Open
  3. Fechar: Finalizar fatura (status Closed)
  4. Correção: Apenas via Nota de Crédito

Validações Importantes​

Dados Obrigatórios​

  • ✅ serieId - Série configurada para faturas
  • ✅ documentTypeId - ID do tipo de documento (5)
  • ✅ entityKeyId - Cliente válido
  • ✅ documentBodies - Pelo menos 1 linha
  • ✅ stockFlow = 1 - Saída de stock

Validações Fiscais​

  • ✅ NIF/VAT do cliente (se PT)
  • ✅ Morada completa
  • ✅ Código de isenção (se aplicável)
  • ✅ Taxa de IVA correta por linha

Validações de Stock​

  • ✅ Produto existe
  • ✅ Stock disponível (se stockBehavior = 1)
  • ✅ Armazém válido

Boas Práticas​

✅ Recomendado​

  • Validar stock antes de criar fatura
  • Incluir morada completa do cliente
  • Definir data de vencimento
  • Referenciar documentos anteriores (OR, EC)
  • Fechar fatura assim que confirmada
  • Incluir informações de pagamento

❌ Evitar​

  • Criar fatura sem validar stock
  • Deixar faturas abertas indefinidamente
  • Tentar editar fatura fechada
  • Criar fatura duplicada
  • Esquecer campos fiscalmente obrigatórios

Casos de Uso Comuns​

Fatura Simples​

Venda direta com pagamento à vista.

Fatura a Prazo​

Venda com prazo de pagamento (30/60/90 dias).

Fatura de Serviços​

Prestação de serviços (sem stock).

Fatura Recorrente​

Fatura mensal de serviços contratados.

Correções e Anulações​

Cenário: Erro na Fatura​

❌ ERRADO: Tentar editar fatura fechada

✅ CORRETO: Criar Nota de Crédito

POST /api/v1/invoices
Content-Type: application/json
{
  "serieId": 3,
  "documentTypeId": 7,           // Nota de Crédito
  "entityKeyId": "CLI001",
  "docReference": "FT A/123",    // Referência à fatura original
  "obs": "Anulação de fatura FT A/123",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": -2.0,            // Quantidade negativa
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": -1,             // Entrada de stock
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

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​

Ver Guia de Recibos

Próximos Passos​

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