The totals on an invoice we generated added up perfectly. The VAT breakdown was off by exactly one discount.
We had taken a discount that belonged to one line and also added it into the document-level allowance total. Each number looked fine on its own. Together they pulled the same money out twice in one place and not at all in the other.
That is the part that bites you. An allowance at document level and an allowance on a line are not two sizes of the same thing. They reach the totals by different paths.
A document-level allowance carries its own VAT category and rate. It gets summed into BT-107, the document allowance total, and it moves the taxable amount of the specific VAT breakdown group it names. It is a first-class tax object.
A line-level allowance carries no category at all. It reaches the totals only through the line net amount, BT-131 (quantity times price, less that line's allowances, plus that line's charges). By the time it gets there, it is invisible as a discount. It is just a smaller line.
So in invoicerules, our open-source rule set for invoice documents, we made both directions of that mistake refusals instead of warnings. A line discount that also shows up in the document allowance total is rejected. A line allowance missing from the line net amount is rejected. And a percentage allowance is checked against the base amount it claims to be a percentage of, because a percentage with no base it matches is a number someone typed, not a calculation.
What changed in how we work: we stopped treating totals as something to verify at the end. Anything derivable gets derived, and the derivation is the check. If a value can be computed two ways, the library refuses to take it as input.
If you have built invoicing against a national e-invoicing standard, you probably know where your mismatches came from: the tax rules, or the places where the format lets you say the same thing twice.