Pantheon Middleware

What it needed to solve.

In most installations a webshop and the Pantheon ERP are two separate worlds. Orders get re-keyed by hand, invoices are issued manually, and Croatian fiscalization - a legal requirement - either sits outside the flow or is handled by a separate tool.

The result is familiar: a lag between order and invoice, re-keying errors, and a dependency on someone running the same sequence of steps every day.

What was needed was a production-grade service that takes an order from the webshop and carries it all the way to a fiscalized invoice emailed to the customer - reliably, repeatably, and without anyone touching it.

How we built it.

We built a forward-only integration service: the webshop sends orders in one direction and the middleware does the rest. A clean contract on the front, safe writes and fiscalization on the back - simple to reason about, hard to knock over.

• Our own API contract. The middleware defines the order format, not the other way round. Canonical JSON published as an OpenAPI/Swagger spec, with Zod/DTO validation at the edge and example requests. The webshop integrates against a stable, documented, versioned interface - no adapters, no guesswork, no surprises later.
• Safe ERP writes. Every write goes through Pantheon stored procedures - never a direct INSERT into ERP tables. Writes are wrapped in transactions, document numbering stays owned by the ERP, and access runs through a dedicated integration user with least privilege. The ERP never ends up in an inconsistent state because of the integration.
• Croatian fiscalization, built in-house. ZKI generation, digitally signed XML (XML-DSig), exchange with FINA's service, JIR retrieval and a QR code on the invoice. No intermediary, no third-party fiscalization service. The demo → production certificate cutover is run as a controlled, documented procedure.
• Automated invoicing. PDF invoices rendered by headless Chromium from templates, carrying the fiscal data and QR code, delivered to the customer by email over SMTP - with internal BCC copies.
• Resilient & idempotent. A durable job queue with retries and exponential backoff. Order-level idempotency - the same order sent twice never creates two documents. Crash-safe state tracking, dead-letter handling with re-queueing, and automatic ERP reconnect after a dropped connection.
• Observable. Structured JSON logging with a correlation ID across the whole request lifecycle - from HTTP request to sent email. Health and readiness probes for every dependency (ERP, database, queue, SMTP) and a job-queue dashboard.
• Configurable business rules. Discounts, warehouse mapping, digital-item handling, tax rates, invoice templates - all of it is per-environment configuration, not code changes. The same image runs for different clients with different settings.

Two processes, one codebase.

The service runs as two independent processes from a single codebase, so each can scale and fail on its own without taking the other down.

Least privilege, nothing in the clear.

• Token authentication on incoming requests, rejecting anything that fails the schema.
• No direct writes into ERP tables; a dedicated integration user instead of an admin account.
• Secrets and certificates come from the environment only - never in the repository or the image.
• Source-free delivery: the app is packaged into the image compiled to V8 bytecode, so readable source never reaches the client's infrastructure. Only the image ships.

Two ways to host it.

The service ships as a Docker image, so it runs the same anywhere - and the client picks where.

Chosen for reliability.

Built to be handed over.

• TypeScript strict mode with extra safety flags; typed error classes with cause chains.
• Unit, integration (against a live Pantheon instance) and end-to-end test suites.
• Two deployment paths - a self-contained handoff package for external operators, or repo-based deploy with redeploy, backup and rollback tooling.
• Separate test and production environments, with a demo fiscalization certificate on test.
• Bilingual (EN / HR) documentation: API spec, technical docs, deploy and go-live runbooks.

Where it stands.

The service is in production. The whole flow runs with no manual steps: order ingest → customer ensure → ERP order & invoice → fiscalization → PDF → email to the customer.

Alongside production there is a separate test environment with demo fiscalization, where integrations are developed and verified before they reach real invoices.

Middleware, not a one-off integration.

The service is built as a product, not as a bespoke build for a single client. The contract facing the webshop, the Pantheon access layer and the fiscalization layer are all generic; what differs from client to client - credentials, certificate, warehouses, tax rates, invoice templates, business rules - is environment configuration.

In practice that means onboarding a new Pantheon user comes down to configuration and a check on the test environment, not a new development cycle.

A fit for merchants running Pantheon ERP who want webshop orders to end up as fiscalized invoices without manual work - whatever platform powers the webshop, because the webshop integrates against our published spec.