e-Faktura API
e-Faktura APIPayroll API
v1 Guides MK Get started

e-Faktura API

Signing: Mode A vs Mode B

A qualified electronic signature has to be produced on the certificate holder’s own device — a server-held key is at most an advanced signature, not a qualified one. Because of that, this API has no “send us your certificate” mode. Instead, every document call to UJP is signed by a signing agent that you run, which keeps an outbound connection to Merot and signs short-lived signing requests.

Mode A — Merot Bridge (default)

Merot Bridge is a desktop app for Windows, macOS and Linux. It talks to your token or smart card over PKCS#11 (with a Windows CNG fallback), shows you what’s about to be signed, and signs it locally — your private key never leaves the device. This is the right choice for businesses and accounting firms with someone at a desk to confirm signatures, and it’s compliant from day one on all three operating systems.

Mode B — an SDK signing worker

If you run your own server (typical for software vendors), the TypeScript or C# SDK’s SigningWorker connects as an agent the same way Bridge does, using a PKCS#11 token/HSM or a PFX certificate file on that server. No desktop app is involved. This keeps the certificate on infrastructure you control, but note: a PFX file is an advanced signature unless the device holding it is itself a certified QSCD (e.g. an HSM) — talk to your certificate provider about what your certificate requires.

Note

There is no Mode C. A hosted certificate — Merot holding your signing key — is not offered, and won’t be unless UJP confirms that a legal-entity e-seal or remote qualified signing is acceptable for e-Faktura JWS signatures.

How a signature request works

  1. Merot builds the document, computes the exact JWS signing input (header + payload), and — if your registered signer is bridge or sdk custody — creates a signing request instead of signing it itself. The e-invoice sits in awaiting_signature.
  2. Your agent receives the request over its open connection (wss://, with a long-poll fallback), parses the payload itself (never trusting Merot’s summary alone), and — for a write (send, storno, correction, accept/reject) — asks you to confirm, unless you’ve opted into unattended writes for that installation. Reads (status polling, list, PDF, …) are signed automatically once the agent is unlocked.
  3. The agent posts the signature back (POST /v1/signing-requests/{id}/signature). Merot verifies it against your registered certificate before sending anything to UJP.
  4. Signing requests expire after 240 seconds (inside UJP’s own 300-second freshness window); an expired one is silently replaced by a new request, not counted as a failed attempt.

Pairing

In the console, generate an 8-character pairing code (10-minute expiry, single use) and enter it in Merot Bridge or pass it to SigningWorker. The agent gets its own Ed25519 device key, stored in your OS keystore (DPAPI/Keychain/libsecret) — a leaked agent secret alone is useless without it.

Unattended writes

By default, every write needs a human to confirm on the Bridge. An account owner can opt an installation into unattended writes (server mode) for fully automated pipelines — this is audited, and the agent still refuses anything outside the expected payload shape for its stated purpose.