Exposing OFX `online_id` (FITID) in the engine API / Python bindings

[array_hourly_0u at icloud.com]

Greetings,
     I have now submitted a PR for a minor feature enhancement
addressing the online_id issue I presented below.
https://github.com/Gnucash/gnucash/pull/2240

Please reach out if you have any questions or comments.

Kind regards,

Noah




> Date: Sun, 31 May 2026 15:48:01 -0700
> From: array_hourly_0u at icloud.com
> To: gnucash-devel at gnucash.org
> Subject: Exposing OFX `online_id` (FITID) in the engine API / Python
>         bindings
>
> Hi all,
>
> I'm building a small Python tool that imports bank OFX/QFX transactions by
> parsing the file in Python and writing the transactions through the official
> GnuCash Python bindings. To behave like the GnuCash app GUI importer, I
> need two things it gets from libofx:
>
> 1. Per-transaction de-duplication: set/read each imported split's
> **`online_id`**
>    (the OFX **FITID**) so re-imported or overlapping statements don't create
>    duplicates.
> 2. Account mapping: read/write an account's **`online_id`** (the bank
>    identifier) so I know which GnuCash account a statement belongs to.
>
> >From reading the source, both values already live in the engine as a plain
> KVP
> slot (`"online_id"`) on Split/Account/Transaction ? the same slot the OFX
> and
> HBCI importers use. But it isn't reachable the way I'd expect: the only C
> accessors are the `gnc_import_*_online_id` helpers over in the import-export
> module, and nothing is exposed to the Python bindings (the bindings only
> wrap
> functions declared in the public Split/Account/Transaction headers).
>
> The approach I'd like to propose is to promote `online_id` to **first-class
> engine accessors**, alongside an object's other identity data ? e.g.
>  - `xaccSplitGetOnlineID`
>  - `xaccSplitSetOnlineID`
>  - `xaccAccountGetOnlineID`
>  - `xaccAccountSetOnlineID`
>  - `xaccTransactionGetOnlineID`
>  - `xaccTrannsactionSetOnlineID`  (no practical use currently)
>
> There's no new logic ? the KVP get/set already exists
> internally; this just makes it public. A nice side effect is that the Python
> binding then comes essentially for free through the existing auto-wrapper
> (`Split.GetOnlineID()`, etc.), with no SWIG interface changes.
>
> The change is purely additive ? same KVP slot, no behaviour or data change
> ? and I've left the existing import-export helpers untouched (they could
> delegate to the
> new accessors later if you'd like a single source of truth).
>
> I have a branch with the accessors, C round-trip + KVP-parity tests, and
> Python
> binding tests, all passing locally (native build and a from-source container
> build with the SQL backend):
> https://github.com/Noerr/gnucash/tree/online-id-engine-accessors
>
> Before I open a PR I wanted to check: does promoting `online_id` to the
> public engine API sound like an agreeable direction?
>
> Happy to adjust. Thanks for all your work on GnuCash.
>
> Best,
> Noah