Comarch Optima API: a developer's guide to integrating Optima

Why I'm Writing This

The most-read page on this site is a developer's guide to enova365 WebAPI. Roughly once a month somebody emails asking for the Optima equivalent, and my answer disappoints them every time: it depends entirely on what you mean by "the API".

Optima is the most widely installed ERP in Polish small and mid-sized companies. It is also the one where "does it have an API?" has the least useful answer — and not because the answer is no.

Five different things carry that name. Different owners, different licences, different failure modes, and different people who pick up the phone when one of them stops working at 2 a.m.

This is the developer-level companion to my earlier piece on integrating Optima with a B2B portal, which covers architecture — sync jobs, pricing, order flow. This one is closer to the metal.

"Optima API" Is Not One Thing. It Is Five

Sort this out before any technical decision is made. Most of the argument in a first meeting comes down to two people using one phrase for two different products:

1. CDN.API — Comarch's own COM object model. This is what Comarch means internally when it says "API".
2. Comarch ERP Web API — a REST service Comarch ships and you switch on in configuration.
3. Praca Rozproszona — XML file exchange, built for splitting sales from accounting.
4. Direct SQL — not an API at all, and used as one constantly.
5. Third-party "Web API for Optima" — commercial add-ons from resellers, sold as products.

So the first question on an Optima project is not how you authenticate. It is: which of these five is on this installation, who owns it, and who supports it when it breaks. I've watched a two-week estimate turn into two months because nobody asked until week three.

CDN.API: What Comarch Means When It Says API

CDN.API is a COM object model. You reference it, log in, do your work, log out — a session model, sitting close to the ERP's own logic. Through it you can create and update contractors, items, addresses, attribute definitions and values, payments, trade documents, warehouse documents, and customer reservations.

Three consequences that decide your architecture on day one:

It runs on Windows, in-process, next to an installed Optima. You cannot call it from a container somewhere else. The standard shape is a thin HTTP service sitting on that Windows host, and your real application talks to the service. That is not a workaround, it is the right design: the shim becomes the only component coupled to Optima's version, and you can redeploy everything else without touching the ERP host.

It logs in as an operator, so it occupies a seat. An integration polling every five minutes is a user as far as licensing is concerned. Ask how many module licences the installation has before you design the polling loop.

It applies Optima's business logic, which is the whole reason to use it rather than SQL. Document numbering, stock movements, reservation semantics — all of it happens the way it happens when a person clicks the button.

Comarch ERP Web API: Real, Shipped, Documented Behind a Partner Wall

Comarch does ship a REST service. You enable it under Konfiguracja → Stanowisko → Wymiana danych → Comarch ERP Web API, set a port (8080 by default) and a server address, and restart the Windows service. That last step is not optional and it is the most common cause of a 401 that appears immediately after somebody swears they configured everything correctly.

Two caveats, and both of them change the plan. Its surface grew around Comarch's own ecosystem — e-Sklep, Mobile, BPM — so it covers what those products needed, which may or may not overlap with what you need. And the complete technical documentation goes to Comarch Partners rather than being published openly.

Put those together and you get a specific project risk. "Optima has a Web API" is true and tells you almost nothing. Ask your partner for the actual endpoint specification for the version installed at the client, and read it before you give anyone a date. This is the Optima version of the licence check I put at the top of the enova365 WebAPI guide: a question that costs one email and routinely saves a week.

Praca Rozproszona: Underrated, Occasionally the Right Answer

Praca Rozproszona is a file exchange mechanism — dictionary data and documents move between the sales side and the accounting side as XML, compressed to .zip since version 2017.5.1, tagged with an accounting identifier that defaults to K1 and is frequently not K1 at the client. It was designed for offline separation of departments, not for integration, and developers dismiss it for exactly that reason.

They are often wrong. It goes through Optima's own import logic, so you are not coupled to any schema. It survives version upgrades better than anything else on this list. And when it fails, it fails visibly: a file that did not import is a file sitting in a directory.

It is the wrong answer the moment you need to answer a question in real time, because there is no query surface at all — only what somebody exported. It also brings the failure mode I wrote about in the scheduled-tasks piece: a directory nobody watches, where a job that stopped running and a job that found nothing to send leave identical evidence, which is to say none.

The SQL Database: Read Freely, Write Never

Reading Optima's SQL database is common, works, and for reporting it is usually the sane choice. Writing to it is not a trade-off, it is a mistake: direct writes bypass business logic, corrupt data in ways that surface months later, and put you outside Comarch support. The schema is undocumented for external use and moves between builds.

There is a second consequence, and it gets missed because it is not a data problem at all. A SQL connection does not know the ERP's permission model exists. Operator rights, module boundaries, record-level restrictions — none of it applies. This is the same trap I described for enova365 service accounts: read-only at the database is a far broader grant than read-only in the ERP, and the two get called the same thing in the same meeting.

Third-Party "Web API for Optima": What You Are Actually Buying

There is a real market of commercial APIs bolted onto Optima, and it exists because the gap above is real. Two examples, both easy to find: Lagarta sells Web API packages for Optima in the range of roughly 5 800 to 8 800 PLN net depending on scope and whether the licence covers one company or an accounting office with several; WebArm ERP API runs as a local HTTP service exposing Optima entities as JSON with Swagger documentation and advertises around 1 100 endpoints.

These are legitimate products, and buying one is often cheaper than building the shim yourself. Three questions before you do:

• Whose schema is it? Map to a third-party API and your integration is coupled to that vendor, not to Comarch. A real dependency, with a real renewal price attached.
• What happens on the next Optima build? Comarch releases several a year. Ask about their upgrade cadence, and how quickly they shipped compatibility for the last two versions.
• Where does it run? Most of these still have to sit on or beside the Optima host. If your architecture assumed a cloud call, check before signing.

The protocols differ too — some are SOAP over XML, some are modern JSON. So when a vendor tells you "Optima has a Web API", the useful follow-up is: whose?

Deciding It in One Meeting

• Real-time reads and writes, you own the code → CDN.API behind your own HTTP shim.
• Real-time reads and writes, you would rather buy than build → a third-party API, with the three questions above answered in writing.
• The other system is a Comarch product → Comarch ERP Web API, spec in hand first.
• Periodic document flow into accounting → Praca Rozproszona, with a heartbeat on the directory.
• Reporting and analytics → SQL, read-only.
• Writing into SQL tables → never. There is no version of this that ends well.

Where Optima Integrations Actually Break

In rough order of how often I see it:

Version upgrades. Several releases a year, and both the schema and the object surface can shift. Keep a test database on the target build and validate before the client upgrades production, not after.

The Windows host nobody budgeted. CDN.API needs one. It appears in week two of a project priced in week zero.

The licence seat. Discovered at month end, by the person who could not log in.

Reservation semantics. A rezerwacja odbiorcy is a real document that holds stock. An integration that helpfully creates one per basket will make inventory disappear in a way that looks like a warehouse problem for about three days.

Document numbering. Let Optima assign it. Every time. The same rule as every other Polish ERP, broken for the same tempting reason: you already know what the number should be.

Where This Leads

Everything above is plumbing, and plumbing is the boring half of the work. The interesting half is what you run through it: a process that reads documents from Optima, checks them against something outside the ERP, and puts a reviewable draft in front of a person instead of asking them to retype it.

If you are scoping an Optima integration and want somebody who has already hit these failure modes to look at the specific installation before you commit to a date, get in touch. The groundwork described here is exactly what the AI agents I build sit on: read first, write later, a human on every approval.