Idempotency from the order number
The key for each receipt is derived from the order itself. A retry, a restart or a duplicated event can never produce a second receipt.
The problem.
Our diagnostics showed that 69 of the last 77 orders had no fiscal document at all. A receipt cannot be cancelled once issued, so the fix had to be exact on the first try.
What we built.
- A listener on the marketplace order journal that reacts to payment, not shipment, so the receipt goes out on time.
- Business buyers with a tax ID are skipped automatically; there is a cut-off date so old orders are never fiscalized twice.
- Currency conversion at the central bank rate for the previous business day, with Warsaw-time day boundaries.
- Cash-on-delivery handling, a status webhook and Telegram alerts when something needs a person.
- Tax category codes set in bulk on 219 products through the invoicing service’s API.
Decisions worth explaining.
Small on purpose
About 1,700 lines on the standard library and SQLite. Fewer moving parts means fewer things that can break in a system that handles tax documents.
In numbers.
69 / 77orders had no receipt before the bridge
924marketplace events parsed on the first live run
219products got correct tax codes in one pass
0chance of a duplicate receipt by design
Stack
- Python 3.12
- SQLite
- Allegro REST API
- OAuth Device Flow
- e-paragony API
- NBP API
- Fakturownia API
- Ubuntu
- nginx
Need something like this?
Describe your process. We will tell you which parts of this system fit it and what it would cost.