Debit Notes Guide

Document nature (business): Debit Note (ND)

Illustrative IDs

The values in the JSON examples (e.g. "documentTypeId": 8) are illustrations; the same number can represent a different document type in another client's database. Resolve the correct id with GET /gateway/document-type and match description / keyId to a debit note in the client's database. See Resolving document type IDs.

Debit notes are issued with the same endpoint as any sales document:

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

Set documentTypeId to the debit-note type for debit notes (invoiceType ND).

Overview

A debit note (ND) charges an additional amount to a customer, typically when there is a shortage or undercharge on a previously issued invoice. Typical uses:

Billing shortfall correction (undercharged amount)
Additional charges (transport, handling, penalties)
Price adjustment after delivery
Supplementary charges agreed after invoicing

Issuance rules (ND)

Rule	Detail
Endpoint	`POST /gateway/invoice/invoices` with ND `documentTypeId`
`emissionReason`	Required for Portugal and Angola (max 50 characters)
Line quantities	Always positive — the document type defines debit semantics
`quantity`	Required and must be greater than zero
Stock movement	Handled by the ND document type configuration
`payments[]`	Required at header level together with `currencyId`
Origin linkage	Per-line `originBodyGuid` + `relationType` to identify the origin line
Same customer	ND must be issued to the same customer as the origin document

Quantities are positive

Use positive quantity on ND lines. The charged amount is always a positive value.

Step-by-step workflow

Step 1 — Get the original invoice

Retrieve the invoice you want to debit. Pass referencedQuantitiesRelationType=1 to receive, on each line, the quantity already debited by previous debit notes:

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

From the response, collect the fields below for each line you want to reference:

Field	Location	Used as
`documentBodies[].guid`	Each line	`originBodyGuid` on the ND line
`documentBodies[].quantity`	Each line	Original quantity on the invoice line
`documentBodies[].referencedQuantity`	Each line	Quantity already debited (`null` = none yet)

Remaining debitable quantity per line = quantity − (referencedQuantity ?? 0)

Example response (invoice 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": 10,
      "retailPrice": 20,
      "netPrice": 16.26,
      "taxId": 1,
      "totalAmount": 200,
      "totalNetAmount": 162.60,
      "referencedQuantity": null
    }
  ]
}

PROD001 has not been debited yet — all 10 units are available.

Step 2 — Create the debit note

Build the ND payload:

Set ND documentTypeId and serieId.
Use the same customer (entityKeyId) as the original invoice.
Set emissionReason (PT/AO — max 50 chars).
Set currencyId and payments[] (sum must match the ND total).
On each charged line, set originBodyGuid and relationType together.
Use positive quantity.

Per-line reference fields (both required together, or omit both):

Field	Value
`originBodyGuid`	Line `guid` of the original invoice line
`relationType`	`1` (`ReferenceOrigin`)

Derived fields on referenced lines

When a line carries originBodyGuid + relationType, the following fields are optional — the API derives them from the origin line when omitted:

Field	Behaviour when omitted	Behaviour when supplied
`itemKeyId`	Derived from origin	Must match origin (→ `DocumentReference.ItemMismatch` if different)
`taxId`	Derived from origin	Accepted — tax may differ from origin
`retailPrice`	Derived as `originTotalAmount / originQuantity`	Accepted; locked to origin on Angolan sales (→ `DocumentReference.PriceMismatch` if different)
`netPrice`	Derived as `originTotalNetAmount / originQuantity`	Accepted; locked to origin on Angolan sales (→ `DocumentReference.PriceMismatch` if different)
`discountPercentage`	Defaults to zero	Accepted

Angola — always omit prices on referenced lines

In Angola, the unit prices on referenced lines must reflect the origin. The API enforces this: if retailPrice or netPrice is supplied, it must match totalAmount / quantity exactly — not the retailPrice field returned by GET /flat.

retailPrice in GET /flat is the stored unit price on the line; totalAmount / quantity is the effective charged price and may differ for various reasons (e.g. line discounts). Supplying the raw retailPrice when it diverges from totalAmount / quantity will cause DocumentReference.PriceMismatch.

Always omit retailPrice and netPrice on Angolan NC/ND lines. The API derives the correct fiscal value from the origin totals automatically.

If you cannot omit prices due to a technical constraint (e.g. a legacy integration that always populates all fields), supply:

retailPrice = totalAmount / quantity
netPrice = totalNetAmount / quantity

Billing shortfall correction (with line references)

Customer was undercharged on a previous invoice — additional 2 units of the same item.

{
  "serieId": 4,
  "documentTypeId": 8,
  "entityVat": "123456789",
  "entityDescription": "Example Client, Ltd",
  "currencyId": 1,
  "emissionReason": "Billing correction - 2 units omitted from FAC 1/5",
  "obs": "Supplementary charge on invoice FAC 1/5",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 48.4
    }
  ],
  "documentBodies": [
    {
      "quantity": 2,
      "originBodyGuid": "660e8400-e29b-41d4-a716-446655440001",
      "relationType": 1
    }
  ]
}

Item, tax, and prices are derived automatically from the origin line. You may override them following the rules in the derived fields table above.

Price adjustment (supply explicit prices)

Use when the additional charge reflects a price different from the original invoice.

{
  "serieId": 4,
  "documentTypeId": 8,
  "entityVat": "123456789",
  "currencyId": 1,
  "emissionReason": "Additional transport charges",
  "obs": "Supplementary charge on invoice FAC 1/5",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 25
    }
  ],
  "documentBodies": [
    {
      "quantity": 1,
      "retailPrice": 25,
      "netPrice": 20.33,
      "originBodyGuid": "660e8400-e29b-41d4-a716-446655440001",
      "relationType": 1
    }
  ]
}

Stock behaviour is determined by the ND document type configuration.

Minimal request (fully derived)

The simplest valid ND request — all item/price/tax information is derived from the origin line; no need to repeat itemKeyId, taxId, retailPrice, or netPrice:

{
  "serieId": 4,
  "documentTypeId": 8,
  "entityVat": "123456789",
  "currencyId": 1,
  "emissionReason": "Supplementary charge",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 40
    }
  ],
  "documentBodies": [
    {
      "originBodyGuid": "660e8400-e29b-41d4-a716-446655440001",
      "relationType": 1,
      "quantity": 2
    }
  ]
}

Common errors

Error code	Cause	Resolution
`SaleDocumentRules.NCND.MissingReferences`	No per-line refs (in-app origin) (PT/AO)	Use per-line GUID refs for Soba invoices
`SaleDocumentRules.NCND.MissingEmissionReason`	`emissionReason` empty (PT/AO)	Set `emissionReason` (max 50 characters)
`DocumentReference.OriginBodyNotFound`	`originBodyGuid` does not exist or has been deleted	Verify GUIDs from `GET /gateway/invoice/invoices/{id}`
`DocumentReference.BalanceExceeded`	`quantity` + already-referenced qty > origin line qty	Reduce `quantity` or check prior NDs on the same line
`DocumentReference.ItemMismatch`	Supplied `itemKeyId` does not match the origin line's item	Omit `itemKeyId` or send the same item as the origin
`DocumentReference.PriceMismatch`	Supplied price differs from origin-derived price on an Angolan rectifying document	For Angola, always omit `retailPrice`/`netPrice` — the API derives prices from the origin totals. If supplied, values must equal `totalAmount / quantity` and `totalNetAmount / quantity`, not the raw unit prices from GET /flat
`DocumentReference.EntityMismatch`	Customer on the ND differs from the customer of the origin document	Use the same `entityKeyId` as the origin invoice
`Payment.InsufficientValue`	Sum of `payments[].amount` ≠ ND total	Recalculate total and adjust payment amounts

Validation also rejects incomplete reference pairs — originBodyGuid and relationType must both be present together or both omitted.

Usage Guide — Header/line fields, payments, and error handling
Invoices Guide — Issuing the original sales invoice
Credit Notes Guide — Reversing or correcting an invoice

Last Updated: July 7, 2026

Overview​

Issuance rules (ND)​

Step-by-step workflow​

Step 1 — Get the original invoice​

Step 2 — Create the debit note​

Derived fields on referenced lines​

Billing shortfall correction (with line references)​

Price adjustment (supply explicit prices)​

Minimal request (fully derived)​

Common errors​

Related guides​