Pular para o conteúdo principal

Guia de Notas de Crédito (Credit Notes)

Tipo de Documento: Nota de Crédito
Document Type ID: 7 (verificar com /document-type)

Visão Geral​

As Notas de Crédito (Credit Notes) são documentos que:

  • ↩️ Revertem vendas (total ou parcial)
  • 📈 AFETAM stock (entrada/devolução)
  • 💸 Geram crédito a favor do cliente
  • 🧾 Documento fiscal oficial
  • ✅ Corrigem ou anulam faturas

Quando Usar​

  • ✅ Devolução de produtos
  • ✅ Correção de erro em fatura
  • ✅ Anulação de venda
  • ✅ Desconto posterior à venda

Características das Notas de Crédito​

CaracterísticaValorDescrição
Afeta Stock✅ SimEntrada de stock
Requer Reembolso⚠️ DependePode gerar crédito
Pode ser Fechada✅ SimFinalização obrigatória
Validação Fiscal✅ SimDocumento fiscal oficial
Permite Edição⚠️ LimitadaSó antes de fechar
Referência Fatura⚠️ RecomendadoDeve referenciar fatura

Tipos de Notas de Crédito​

1. Devolução Total​

Cliente devolve toda a compra.

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}
{
  "serieId": 3,
  "documentTypeId": 7,
  "entityKeyId": "CLI001",
  "entityDescription": "Cliente Exemplo, Lda",
  "obs": "Devolução total - produto com defeito",
  "docReference": "FT A/123",      // Fatura original
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Produto 1",
      "quantity": -2.0,            // Quantidade NEGATIVA
      "retailPrice": 50.00,        // Preço original
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": -1,             // ENTRADA de stock
      "stockBehavior": 1,
      "destinationWarehouse": 1,
      "secondTaxId": 0
    }
  ]
}
Quantidade Negativa

Use quantidade negativa (-2.0) e stockFlow = -1 para entrada de stock.

2. Devolução Parcial​

Cliente devolve apenas parte da compra.

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityKeyId": "CLI001",
  "obs": "Devolução parcial - 1 de 2 unidades",
  "docReference": "FT A/123",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": -1.0,            // Apenas 1 unidade
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": -1,
      "stockBehavior": 1,
      "destinationWarehouse": 1,
      "secondTaxId": 0
    }
  ]
}

3. Correção de Valor​

Corrigir erro de preço sem devolução física.

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityKeyId": "CLI001",
  "obs": "Correção de preço - erro de faturação",
  "docReference": "FT A/123",
  "documentBodies": [
    {
      "itemKeyId": "PGTO001",      // Item genérico de correção
      "itemDescription": "Correção de valor",
      "quantity": -1.0,
      "retailPrice": 10.00,        // Diferença de valor
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 0,              // NÃO afeta stock
      "stockBehavior": 0,
      "secondTaxId": 0
    }
  ]
}

4. Anulação Total​

Anular fatura completamente (sem devolução física).

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityKeyId": "CLI001",
  "obs": "Anulação de fatura FT A/123 - emitida por erro",
  "docReference": "FT A/123",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": -2.0,
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": -1,             // Entrada de stock
      "stockBehavior": 1,
      "destinationWarehouse": 1,
      "secondTaxId": 0
    }
  ]
}

Gestão de Reembolsos​

Cenário 1: Reembolso Imediato​

  1. Criar nota de crédito
  2. Emitir recibo negativo (se aplicável)
  3. Registar saída de tesouraria

Cenário 2: Crédito para Compras Futuras​

  1. Criar nota de crédito
  2. Registar crédito no sistema contabilístico
  3. Cliente usa crédito em próxima compra

Cenário 3: Desconto em Fatura Futura​

  1. Criar nota de crédito
  2. Próxima fatura: incluir crédito como desconto

Validações Importantes​

Dados Obrigatórios​

  • ✅ documentTypeId = 7 - Nota de Crédito
  • ✅ docReference - Referência à fatura original
  • ✅ quantity negativa - Valor a creditar
  • ✅ stockFlow = -1 - Entrada de stock (se devolução física)

Validações de Negócio​

  • ✅ Valor da NC ≤ Valor da fatura original
  • ✅ Quantidade devolvida ≤ Quantidade vendida
  • ✅ Fatura original existe e está fechada
  • ✅ Cliente é o mesmo da fatura original

Boas Práticas​

✅ Recomendado​

  • Sempre referenciar fatura original em docReference
  • Incluir motivo detalhado no campo obs
  • Validar valores antes de emitir
  • Fechar nota de crédito imediatamente
  • Fotografar produtos devolvidos (devolução física)
  • Coordenar com departamento financeiro

❌ Evitar​

  • Emitir NC sem fatura vinculada
  • Valores superiores à fatura original
  • Esquecer de registar entrada de stock
  • Deixar NC aberta
  • NC por motivos triviais (desconto → usar fatura com desconto)

Cenários Práticos​

Devolução por Defeito​

Situação: Produto com defeito, cliente quer reembolso total.

Passos:

  1. Verificar fatura original
  2. Criar NC com devolução física (stockFlow = -1)
  3. Processar reembolso
  4. Enviar produto defeituoso para fornecedor/qualidade

Erro de Faturação​

Situação: Preço errado na fatura.

Passos:

  1. Criar NC com correção de valor
  2. Não afetar stock (stockFlow = 0)
  3. Emitir nova fatura correta (se necessário)

Desconto Comercial Posterior​

Situação: Cliente negociou desconto após fatura.

Passos:

  1. Criar NC com valor do desconto
  2. Não afetar stock
  3. Registar em contas a receber

Diferenças vs Faturas​

AspectoFaturaNota de Crédito
QuantidadePositivaNegativa
StockSaídaEntrada
ReceitaAumentaDiminui
ObjetivoVendaCorreção/Devolução
ReferênciaOpcionalObrigatória

Integração com Fatura​

Fluxo Completo​

graph LR
    A[Fatura Emitida] --> B{Problema?}
    B -->|Sim| C[Criar Nota de Crédito]
    C --> D[Processar Devolução]
    D --> E[Reembolso/Crédito]
    B -->|Não| F[Fim]

Relatórios e Análise​

Métricas Importantes​

  • Taxa de devolução por produto
  • Valor total de NCs por período
  • Motivos mais comuns de devolução
  • Clientes com mais devoluções

Consultar NCs​

GET /api/v1/invoices?documentTypeId=7&fromDate=2025-01-01&toDate=2025-12-31
Authorization: Bearer {token}

Próximos Passos​

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