Guia de Notas de Crédito

Natureza do documento (negócio): Nota de Crédito (NC)

IDs ilustrativos

Os valores nos exemplos JSON (ex. "documentTypeId": 7) são ilustrativos; o mesmo número pode representar um tipo de documento diferente noutra base de dados. Resolva o id correcto com GET /gateway/document-type e faça corresponder description / keyId a uma nota de crédito na base de dados do cliente. Consulte Resolução de IDs de tipo de documento.

As notas de crédito são emitidas com o mesmo endpoint de qualquer documento de venda:

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

Defina documentTypeId com o tipo de nota de crédito (invoiceType NC).

Visão geral

Uma nota de crédito (NC) reverte ou corrige uma factura previamente emitida. Utilizações típicas:

Devoluções totais ou parciais de produtos
Correcção de erros de preço ou facturação
Descontos pós-venda ou ajustes comerciais
Anulação de factura (com ou sem devolução física)

Regras de emissão (NC)

Regra	Detalhe
Endpoint	`POST /gateway/invoice/invoices` com `documentTypeId` de NC
`emissionReason`	Obrigatório para Portugal e Angola (máx. 50 caracteres)
Quantidades por linha	Sempre positivas — o tipo de documento define a semântica de crédito
`quantity`	Obrigatório e tem de ser maior que zero
Movimento de stock	Controlado pela configuração do tipo de documento NC
`payments[]`	Obrigatório ao nível do cabeçalho juntamente com `currencyId`
Referência à origem	`originBodyGuid` + `relationType` por linha — identifica a linha da factura de origem
Mesmo cliente	A NC deve ser emitida ao mesmo cliente do documento de origem
Art. 78 CIVA (PT)	Texto de observação legal adicionado automaticamente a `obs` quando as referências são válidas

Quantidades são positivas

Use quantity positivo nas linhas de NC. O valor creditado é sempre um valor positivo.

Fluxo passo a passo

Passo 1 — Obter a factura original

Consulte a factura que pretende creditar. Indique referencedQuantitiesRelationType=1 para receber, em cada linha, a quantidade já creditada por notas de crédito anteriores:

GET /gateway/invoice/invoices/{documentTypeId}/{serieId}/{number}/flat?referencedQuantitiesRelationType=1
Authorization: Bearer {token}

Na resposta, recolha os seguintes campos de cada linha que pretende creditar:

Campo	Localização	Utilizado como
`documentBodies[].guid`	Cada linha	`originBodyGuid` na linha da NC
`documentBodies[].quantity`	Cada linha	Quantidade original na linha da factura
`documentBodies[].referencedQuantity`	Cada linha	Quantidade já creditada (`null` = nenhuma ainda)

Quantidade creditável restante por linha = quantity − (referencedQuantity ?? 0)

Exemplo de resposta (factura FAC 1/5, documentTypeId=7, serieId=3, number=123):

{
  "id": 1001,
  "documentNumber": "FAC 1/5",
  "entityVat": "123456789",
  "documentBodies": [
    {
      "guid": "660e8400-e29b-41d4-a716-446655440001",
      "itemKeyId": "PROD001",
      "quantity": 2,
      "retailPrice": 50,
      "netPrice": 40.65,
      "taxId": 1,
      "totalAmount": 100,
      "totalNetAmount": 81.30,
      "referencedQuantity": 1
    },
    {
      "guid": "660e8400-e29b-41d4-a716-446655440002",
      "itemKeyId": "PROD002",
      "quantity": 1,
      "retailPrice": 30,
      "netPrice": 24.39,
      "taxId": 1,
      "totalAmount": 30,
      "totalNetAmount": 24.39,
      "referencedQuantity": null
    }
  ]
}

PROD001 já teve 1 das 2 unidades creditadas — resta apenas 1 unidade. PROD002 ainda não foi creditado.

Passo 2 — Criar a nota de crédito

Monte o payload da NC:

Defina documentTypeId e serieId de NC.
Use o mesmo cliente (entityKeyId) da factura original.
Defina emissionReason (PT/AO — máx. 50 caracteres).
Defina currencyId e payments[] (a soma deve corresponder ao total da NC).
Em cada linha creditada, defina originBodyGuid e relationType em conjunto.
Use quantity positivo.

Campos de referência por linha (ambos obrigatórios juntos, ou ambos omitidos):

Campo	Valor
`originBodyGuid`	`guid` da linha da factura original
`relationType`	`1` (`ReferenceOrigin`)

Campos derivados em linhas referenciadas

Quando uma linha contém originBodyGuid + relationType, os seguintes campos são opcionais — a API deriva-os da linha de origem quando omitidos:

Campo	Comportamento quando omitido	Comportamento quando fornecido
`itemKeyId`	Derivado da origem	Deve coincidir com a origem (→ `DocumentReference.ItemMismatch` se diferente)
`taxId`	Derivado da origem	Aceite — a taxa pode diferir da origem
`retailPrice`	Derivado como `totalOrigem / quantidadeOrigem`	Aceite; bloqueado à origem em vendas angolanas (→ `DocumentReference.PriceMismatch` se diferente)
`netPrice`	Derivado como `totalLíquidoOrigem / quantidadeOrigem`	Aceite; bloqueado à origem em vendas angolanas (→ `DocumentReference.PriceMismatch` se diferente)
`discountPercentage`	Assume zero	Aceite

Angola — omita sempre os preços em linhas referenciadas

Em Angola, o preço unitário das linhas referenciadas está bloqueado ao valor da origem. A API garante isso: se retailPrice ou netPrice for fornecido, deve corresponder exactamente a totalAmount / quantity — não ao campo retailPrice devolvido pelo GET /flat.

O retailPrice no GET /flat é o preço unitário armazenado na linha; totalAmount / quantity é o preço efectivamente cobrado e pode diferir por várias razões (ex. descontos de linha). Fornecer o retailPrice bruto quando diverge de totalAmount / quantity causará DocumentReference.PriceMismatch.

Omita sempre retailPrice e netPrice em linhas de NC/ND angolanas. A API deriva o valor fiscal correcto a partir dos totais da origem automaticamente.

Se não conseguir omitir os preços por razão técnica (por ex. integração legada que preenche sempre todos os campos), use:

retailPrice = totalAmount / quantity
netPrice = totalNetAmount / quantity

Devolução total (com referências por linha)

O cliente devolve toda a compra — ambas as linhas da factura referenciadas na totalidade.

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityVat": "123456789",
  "entityDescription": "Cliente Exemplo, Lda",
  "currencyId": 1,
  "emissionReason": "Devolução total - mercadoria com defeito",
  "obs": "Devolução da factura FAC 1/5",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 153
    }
  ],
  "documentBodies": [
    {
      "quantity": 2,
      "originBodyGuid": "660e8400-e29b-41d4-a716-446655440001",
      "relationType": 1
    },
    {
      "quantity": 1,
      "originBodyGuid": "660e8400-e29b-41d4-a716-446655440002",
      "relationType": 1
    }
  ]
}

O artigo, a taxa e os preços são derivados automaticamente de cada linha de origem. Pode substituí-los seguindo as regras da tabela acima.

Art. 78 CIVA (Portugal)

Quando existem referências por linha válidas, o seguinte texto legal é adicionado automaticamente a obs:

Nos termos do n.º 5 do artigo 78.º do CIVA, agradecemos a devolução do duplicado desta Nota de Crédito, devidamente carimbado e assinado.

Não duplique este texto manualmente.

Devolução parcial

O cliente devolve apenas parte da compra — referencie uma linha com quantity inferior ao original.

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityVat": "123456789",
  "currencyId": 1,
  "emissionReason": "Devolução parcial - 1 de 2 unidades",
  "obs": "Devolução parcial da factura FAC 1/5",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 61.5
    }
  ],
  "documentBodies": [
    {
      "quantity": 1,
      "originBodyGuid": "660e8400-e29b-41d4-a716-446655440001",
      "relationType": 1
    }
  ]
}

quantity (1,0) não pode exceder a quantidade por referenciar na linha de origem 660e8400-…440001 (originalmente 2,0, menos eventuais NCs anteriores).

Correcção de valor (sem movimento de stock)

Use quando corrige um erro de facturação ou concede um desconto pós-venda sem devolução física. Referencie a(s) linha(s) da factura afectada(s) e forneça preços explícitos que reflictam o valor corrigido.

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityVat": "123456789",
  "currencyId": 1,
  "emissionReason": "Correcção de preço - erro de facturação",
  "obs": "Correcção à factura FAC 1/5",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 10
    }
  ],
  "documentBodies": [
    {
      "quantity": 1,
      "retailPrice": 10,
      "netPrice": 8.13,
      "originBodyGuid": "660e8400-e29b-41d4-a716-446655440001",
      "relationType": 1
    }
  ]
}

O comportamento de stock é determinado pela configuração do tipo de documento NC.

Erros comuns

Código de erro	Causa	Resolução
`SaleDocumentRules.NCND.MissingReferences`	Sem referências por linha (origem interna) (PT/AO)	Use referências GUID por linha para facturas Soba
`SaleDocumentRules.NCND.MissingEmissionReason`	`emissionReason` vazio (PT/AO)	Defina `emissionReason` (máx. 50 caracteres)
`DocumentReference.OriginBodyNotFound`	`originBodyGuid` não existe ou foi eliminado	Verifique os GUIDs via `GET /gateway/invoice/invoices/{id}`
`DocumentReference.BalanceExceeded`	`quantity` + qtd. já referenciada > qtd. linha de origem	Reduza `quantity` ou verifique NCs anteriores sobre a mesma linha
`DocumentReference.ItemMismatch`	`itemKeyId` fornecido não coincide com o artigo da linha de origem	Omita `itemKeyId` ou envie o mesmo artigo que a origem
`DocumentReference.PriceMismatch`	Preço fornecido difere do preço derivado da origem num documento rectificativo angolano	Para Angola, omita sempre `retailPrice`/`netPrice` — a API deriva os preços a partir dos totais da origem. Se fornecidos, os valores devem ser iguais a `totalAmount / quantity` e `totalNetAmount / quantity`, não os preços unitários brutos do GET /flat
`DocumentReference.EntityMismatch`	Cliente da NC diferente do cliente do documento de origem	Use o mesmo `entityKeyId` da factura de origem
`Payment.InsufficientValue`	Soma de `payments[].amount` ≠ total da NC	Recalcule o total e ajuste os montantes de pagamento

A validação também rejeita pares de referência incompletos — originBodyGuid e relationType devem ambos estar presentes ou ambos omitidos.

Guias relacionados

Guia de Utilização — Campos de cabeçalho/linha, pagamentos e tratamento de erros
Guia de Facturas — Emissão da factura de venda original
Guia de Recibos — Fluxos de reembolso e tesouraria

Última actualização: 30 de Junho de 2026

Visão geral​

Regras de emissão (NC)​

Fluxo passo a passo​

Passo 1 — Obter a factura original​

Passo 2 — Criar a nota de crédito​

Campos derivados em linhas referenciadas​

Devolução total (com referências por linha)​

Devolução parcial​

Correcção de valor (sem movimento de stock)​

Erros comuns​

Guias relacionados​