Skip to main content

Architecture Patterns

Zyntem's Cloud API and Embedded Local SDKs are two independent paths for fiscalizing transactions. This page covers how they differ in data flow and common deployment topologies.

Data Flow: Cloud API vs Embedded Local​

The two SDK families have different data paths:

Cloud API:
  Your App  ──HTTPS──>  Zyntem Backend  ──>  Tax Authority
                         (stores records)

Embedded Local:
  Your App  ──>  Embedded SDK  ──>  local queue  ──>  Tax Authority
                 (signs locally)     (SQLite)         (direct submission)

Cloud API transactions flow through the Zyntem backend, which stores fiscal records and forwards them to the tax authority.

Embedded Local transactions are signed and hash-chained locally. The background queue submits directly to the tax authority -- records are not automatically synced back to the Zyntem backend.

What is shared across SDK families​

ResourceShared?Details
API keyYesThe same zyn_live_* key works with both SDKs (for init/token provisioning)
Merchant identityYesSame tax_id, same account
BillingYesBilled per unique merchant VAT ID, not per SDK or deployment
Transaction historyNoCloud API records live in the Zyntem backend; Embedded records live in the local SQLite queue and at the tax authority
Fiscal hash chainNoEach signing context maintains its own chain. Cloud and Embedded chains are independent
CertificatesPartiallyUploaded once via API, but Embedded SDK uses local certificate files

Can My Web Dashboard Query On-Premise POS Transactions?​

Not automatically. Cloud API transactions are stored in the Zyntem backend and queryable via the API. Embedded Local transactions are stored locally and submitted directly to the tax authority -- they don't appear in the Cloud API's transaction list.

If you need a unified view, you'll need to implement your own sync mechanism (e.g., the POS sends transaction records to your backend after local signing).

Common Topologies​

1. Single Cloud API​

All transactions flow through the Cloud API. Simplest setup -- no native dependencies.

  Browser/App  -->  Your Backend  -->  api.zyntem.com  -->  Tax Authority

When to use: Web-only POS, SaaS platforms, server-to-server fiscalization.

Trade-offs:

  • Simplest integration (standard HTTP)
  • Full transaction history in one place (queryable via API)
  • Requires network on every transaction
  • ~100-300 ms latency per call

2. Single Embedded Local​

All transactions are signed locally by the Embedded SDK. The background queue submits them directly to the tax authority.

  POS App  -->  Embedded SDK (in-process)  -->  queue  -->  Tax Authority

When to use: On-premise POS, tablets, kiosks, any environment where offline resilience matters.

Trade-offs:

  • Offline-capable -- transactions never block on network
  • ~1-5 ms latency (local function call)
  • Transaction records live locally (not in Zyntem's backend)
  • Requires embedding a native library in your build

3. Hybrid: Cloud Backend + On-Premise POS​

Your cloud backend uses the Cloud API while on-premise POS terminals run the Embedded SDK. Each path maintains its own transaction records and hash chain.

  Web Dashboard  ----->  Cloud API  ----->  Zyntem Backend  ----->  Tax Authority
                                                                       ^
  On-Premise POS  -->  Embedded SDK  -->  local queue  ────────────────+
                       (local signing)                  (direct submission)

How it works:

  1. POS terminals run the Embedded SDK. Transactions are signed locally and queued for submission directly to the tax authority.
  2. Web dashboard calls the Cloud API for its own transactions, reports, and location management.
  3. Data is not automatically shared between the two paths. If you need the dashboard to see POS transactions, implement a sync from the POS to your own backend.

Important: Each POS terminal and the Cloud API maintain separate hash chains. This is fine for compliance -- the tax authority sees each chain independently. But it means you can't mix transactions from different sources into a single chain.

4. Multi-Country with Mixed Modes​

An ISV operating across multiple countries can use Cloud or Embedded per country -- all under one account.

  Spain (on-premise POS)     -->  Embedded SDK  -->  AEAT
  France (cloud POS)         -->  Cloud API     -->  (local NF525, no submission)
  Portugal (on-premise POS)  -->  Embedded SDK  -->  AT
  Italy (tablet POS)         -->  Embedded SDK  -->  SDI

How it works:

  • Each country uses the appropriate adapter automatically (configured via country field)
  • The same API key covers all countries (for account provisioning)
  • Billing is per unique merchant VAT ID across all countries
  • No per-country SDK -- the same Embedded binary handles all supported countries

Configuration per country:

# Spain POS
country: ES
tax_id: B12345678

# France POS (same API key, different country)
country: FR
tax_id: FR12345678901

# Portugal POS (with client certificate for AT)
country: PT
tax_id: PT123456789
certs:
  dir: /etc/zyntem/certs

Topology Comparison​

TopologyCloud APIEmbeddedOfflineUnified transaction viewComplexity
Single CloudYesNoNoYes (via API)Low
Single EmbeddedNoYesYesNo (local only)Low
HybridYesYesPOS onlyNo (separate data paths)Medium
Multi-country mixedPer countryPer countryWhere embeddedNoMedium

Switching Between Modes​

Switching from Cloud to Embedded (or vice versa) is not a simple swap:

  • Hash chain breaks. Each signing context maintains its own chain. Starting a new SDK means starting a new chain. The tax authority sees this as a new chain origin -- which is allowed but means the old chain ends and a new one begins.
  • Transaction history doesn't migrate. Cloud API records live in the Zyntem backend. Embedded records live locally and at the tax authority. There's no automatic sync between them.
  • Different integration patterns. Cloud API is HTTP request/response. Embedded is init + function call + background queue. The code change is non-trivial.

If you're considering a switch, plan for:

  1. Closing out the old chain cleanly (last transaction on the old SDK)
  2. Starting a new chain on the new SDK
  3. Maintaining access to historical records from the old system
  4. Testing the new integration thoroughly in sandbox before switching production

Recommendation: Choose your deployment mode early. If you need both, run them in parallel from the start (hybrid topology) rather than migrating later.

Next Steps​