Subiekt GT Sfera: a developer's guide to integrating Subiekt GT

Why This Guide Exists

Yesterday I wrote the developer's guide to Comarch Optima's five different things called "the API". Subiekt GT is the other half of that pair, and it has exactly the opposite problem. With Optima, the question is which interface you are looking at. With Subiekt GT there is only one, everybody finds it inside ten minutes — and then the team spends three weeks working out what it actually is.

It is called Sfera. It is not an API in the sense you use that word in 2026.

This is the Subiekt-side companion to my enova365 WebAPI guide and to the comparison of Subiekt, Optima and enova365 from an integration standpoint. Every technical claim below comes from InsERT's own documentation, its published price list, or open-source code you can read yourself. Nothing is invented — in this corner of the market, an invented object name costs somebody a day.

What Sfera Actually Is

InsERT's own description is precise, and worth reading literally: Sfera "umożliwia napisanie rozszerzeń, korzystających z wewnętrznych mechanizmów Subiekta GT", built on COM and OLE Automation.

Unpack that and three consequences land on day one, before you write a line of code:

It runs on Windows, next to an installed Subiekt. Not in your container, not in your data centre, not from the Linux box your application already lives on. There is a Windows host in this project. Somebody has to own it, patch it and pay for it — and that is the line item which never makes it into the first estimate.

It goes through Subiekt's own logic. This is the reason to prefer it over the database, and it is a real reason. Documents created through Sfera get numbered, priced, stock-adjusted and validated the way Subiekt would do it if a person clicked the buttons. Anything you write straight into the tables gets none of that.

It is an add-on you buy. Sfera is not part of Subiekt GT. It is a separate licence, and that licence has a shape which catches people out. More on that below.

Sfera exists for five programmes in the line — Subiekt GT, Rewizor GT, Gestor GT, Gratyfikant GT and InsERT GT itself. That matters more than it sounds like it should.

The Connection Has Two Identities

The whole object model fits in a paragraph. You create a COM object with the ProgID InsERT.GT, set properties on it, and call Uruchom.

The properties are Serwer, Baza, Uzytkownik, UzytkownikHaslo, Operator, OperatorHaslo, Autentykacja and Produkt. Read that list twice. It holds the single most important architectural fact about Sfera, and it is easy to skim straight past:

There are two sets of credentials. Uzytkownik and UzytkownikHaslo are a Microsoft SQL Server login. Operator and OperatorHaslo are a Subiekt operator — a person's account inside the ERP. Your integration authenticates twice, at two layers, with two different permission models.

I wrote a whole piece recently on what read-only actually means for a service account, and this is the cleanest example of the problem I have seen in any Polish ERP. When somebody in a meeting says the integration account is read-only, ask which of the two they mean. The SQL login inherits none of the operator's restrictions. The operator's restrictions do not constrain the SQL login. And both get called "the integration account" in the same sentence.

Produkt selects which programme in the line you are attaching to — Subiekt GT is 1, Rachmistrz 2, Rewizor 3, Gratyfikant 4, mikroGratyfikant 5, Gestor 6. And then Uruchom(tryb_dostosowania, tryb_uruchomienia) returns the application object you actually work with.

The Second Argument to Uruchom Is Your Architecture

The running mode is a small integer and it decides more about your system than anything else you will type that week:

• 0 — start the application unless a running one can be attached to.
• 1 — same, but only attach if the running instance is not in a blocked state (Subiekt blocks itself during startup, licence checks and operator switching with Ctrl+F2).
• 2 — always start a new instance.
• 4 — attach or start without the user interface. The application runs in the background.

Mode 4 is what an integration wants. A surprising number of first attempts do not use it — which is how you end up with a Subiekt window opening on a server nobody is looking at. Mode 2 is the one that costs money: a new instance per job means a new login per job, and a login occupies a licence seat exactly like a person does.

Do not skip the blocked-state note under mode 1 either. Startup, licence check and operator switch are all states where Subiekt exists as a process but is not ready. An integration that assumes "process exists, therefore attachable" fails intermittently — and for the first two days it looks exactly like a network problem.

Sfera Is Priced Per Programme and Per Workstation

From InsERT's retail price list effective 2 January 2026 — check the current one before quoting, but the structure does not move:

Item	Net PLN
Sfera dla Subiekta GT (add-on to an existing Subiekt)	1 045
— extension to each additional workstation	655
Subiekt GT Sfera (bundle)	2 090
Sfera dla Rewizora GT	1 975
Sfera dla Gratyfikanta GT	1 915
Sfera dla Gestora GT	875

The last three rows are the ones that change conversations. Sfera is bought per programme. An integration that issues sales documents in Subiekt needs Sfera dla Subiekta GT. The moment scope grows to "and post it in accounting", that means Rewizor GT and a second Sfera licence at nearly twice the price of the first.

Raise this in the first meeting, not the invoicing one. "We'll also handle the accounting side" sounds like a small extension of scope. In licence terms it is the bigger purchase.

Fifteen Days of Free Certainty

InsERT ships a trial version of Sfera. You turn it on from the Sfera icon in the programme's toolbar and it runs for 15 days, after which Sfera expires and anything built on it stops working until a licence is bought and activated.

Almost nobody uses it. And it is the highest-value fifteen days available on a Subiekt project — not to build the integration, but to answer one question: can the documents this project depends on actually be created, on this client's database, with this client's configuration? Warehouse states, price lists, unit definitions, required fields somebody added in 2019, the operator permissions in force. All of it you find out in an afternoon with a trial licence. Or in week five without one.

The expiry is a named failure mode too. A proof of concept built on the trial, demoed successfully, then left running while commercial terms get agreed, dies on day sixteen. It dies at the client's, in production-shaped conditions, with nobody expecting it.

Where the Documentation Is

There is no public Sfera reference on the internet. People waste real time looking for one.

The documentation is inside the installation. In the programme: Pomoc → InfoSfera, then F1 into the help module. On disk it is a CHM file under the InsERT directory — and the path itself tells you something you need to know:

C:\Program Files (x86)\InsERT\InsERT GT\Pomoc\gta.chm

(x86). Thirty-two bit.

Which is why the most common day-one failure is a .NET project built as AnyCPU on a 64-bit machine, throwing "Klasa niezarejestrowana" — class not registered — against a COM object that is registered perfectly well, just not for a 64-bit process. Target x86 and the error disappears. A five-minute fix that regularly costs half a day, because the message points at registration and the cause is bitness.

The Failure Modes Worth Designing For

The RPC server disappears. Sfera holds a live connection to a running subiekt.exe. If that process ends — a user closes it, an update restarts it, the machine reboots overnight — your object handle is dead and it will not heal itself. The integration has to detect that and reconnect. If it does not, the symptom is a service that ran happily for six weeks and then silently stopped: the same failure shape I described for unwatched scheduled jobs in enova365.

The licence seat at month end. Covered above. Ask how many workstations the installation has before you design a polling loop, not after.

Direct SQL writes. Read from the database freely — reporting off the Subiekt tables is normal practice and it works. Write to it and you have bypassed the business logic that was the entire reason to use Sfera in the first place, produced documents Subiekt does not fully believe in, and walked off the ground where InsERT support can help you.

Version drift. Subiekt GT is still being developed — version 1.89 carries the current wave of KSeF changes, including new reference fields on receivables and payables. Good news for the platform, standing obligation for you. An ERP that keeps changing is an integration that needs re-testing on a schedule, and the Sfera licence requires the current version to be activated anyway.

What I Would Build First

Put a thin HTTP service on the Windows host that owns the Subiekt installation, and let it be the only component in your system that knows Sfera exists. Your application talks to that service over JSON. The shim absorbs COM, the bitness constraint, the reconnect logic and the version coupling — so everything above becomes one small, replaceable component instead of a property of your whole architecture.

Then start with reads. Stock levels and contractor data, exposed read-only, with a heartbeat so a dead connection shows up within minutes rather than at the next complaint. A week of work. It earns you the right to talk about writing documents, and it turns the licence and permission questions from theoretical into concrete.

Weighing this against an order-intake project? The connection is direct: everything above is the plumbing under an ERP-integrated B2B portal, and the portal is where the return on it shows up.

Working out whether a Subiekt GT integration is worth building? Get in touch — an hour with your installation and your real document flow will tell you more than any estimate written from a feature list.