myaade

Every document carries a series and a sequence number (AA). The provider API returns error 603 — "Invoice already has been sent" — if that number was already used. The obvious reading is that you sent a duplicate. The real cause is usually stranger, and it lives entirely on my side of the boundary.

A request that times out on my client can still have been accepted upstream. The document goes through; my local database never learns about it and still believes the number is free. The next issue reuses it and comes back rejected. And because that can happen more than once, the drift is not always one number deep.

So retrying once and incrementing is not a fix, it's a coin flip. The backend retries up to five times, incrementing and persisting the sequence number on every 603, which repairs the drift rather than papering over it. The cap is the part I'd defend hardest: past five, the cause is no longer transient drift but a genuine mismatch that needs a person. It fails loudly, with the SQL to correct the series, instead of retrying against a paid API in a loop.

Totals, VAT and partial credits are computed on integer cents, not floating-point euros. This sounds like pedantry until you write the validation for a partial credit note.

A credit note cannot exceed the uncredited balance of the original invoice. Express that check as `remaining > 0` over float arithmetic and `0.1 + 0.2 !== 0.3` eventually issues a credit note for a cent that doesn't exist. Best case it comes back rejected and a user sees an error they cannot act on. Worst case it goes through, and the books are wrong in a way nobody notices for months.

Issuing a credit note (type 5.1) means referencing the original document's MARK, staying within the remaining balance, and accounting for the fact that a single invoice may accumulate several partial credits over its life.

The naive build is a form that posts and shows whatever comes back. I moved the constraint earlier: the UI derives the available balance per invoice, shows it on each option, and disables fully-credited documents at selection time. An invalid credit can't be composed in the first place, so the round trip is never spent finding out.

Credit notes also net out of period totals automatically — they reduce debt rather than collect revenue, and a summary card that adds them up is quietly lying to the person reading it.

The retry loop treats a symptom. The disease is that an issue request has no identity of its own, so a timeout leaves my client genuinely unable to tell "never arrived" from "arrived and succeeded". A key generated before the first attempt would let a retry ask "did this specific document go through?" instead of guessing at the counter. I'd build that first now, and most of the retry logic would disappear.

There is nothing worth testing about the provider's API — that's their contract and they test it. But the balance derivation for partial credits, the totals and VAT arithmetic, and the sequence-counter update are my logic, they are pure functions, and they are the part with real consequences. I verified them by hand and then wrote documentation about their edge cases, which is the wrong order.

Debugging a rejected document meant reading console output and guessing. Every request and response should be persisted with a correlation ID — not for observability points, but because that trail is the only thing that answers "what exactly did we send in March" six months later.