Skip to main content

SDK Overview

Zyntem offers two SDK families, each designed for a different deployment model. Pick the one that matches your architecture -- you only need one.

Choose Your Deployment Mode​

Cloud APIEmbedded Local
How it worksYour POS calls api.zyntem.com over HTTPSYour POS calls a native library in-process
Network requiredYes, on every transactionOnly for initial token provisioning and queued submission
Latency~100-300 ms (network round-trip)~1-5 ms (local function call)
Offline supportNoYes -- transactions are signed locally and queued for submission
Best forWeb apps, cloud-native POS, SaaS platformsTraditional POS (Windows/.NET, Linux), tablet POS (iPad, Android), kiosks
Integration effortLow -- standard HTTP callsMedium -- embed native library in your build

Decision Flowchart​

Start
 |
 v
Does your POS run in a browser or cloud-only environment?
 |-- Yes --> Cloud API
 |-- No
      |
      v
    Do you need offline transaction processing?
     |-- Yes --> Embedded Local
     |-- No
          |
          v
        Is network latency a concern (> 100 ms round-trip)?
         |-- Yes --> Embedded Local
         |-- No
              |
              v
            Do you want the simplest possible integration?
             |-- Yes --> Cloud API
             |-- No  --> Embedded Local

Common Scenarios​

ScenarioRecommendationWhy
SaaS POS (web dashboard)Cloud APIRuns in the browser, always online
On-premise Windows POSEmbedded Local (.NET)Offline resilience, low latency
Android tablet POS in a restaurantEmbedded Local (Android)Wi-Fi drops, need offline receipts
iPad POS in retailEmbedded Local (iOS)Same as above
Cloud backend fiscalizing on behalf of merchantsCloud APIServer-to-server, reliable connectivity
Kiosk / vending machineEmbedded Local (C/Linux)No guaranteed connectivity
Hybrid: web dashboard + on-premise POSBothCloud API for the dashboard, Embedded Local for the POS
Multi-country ISV rolloutEitherSame SDK, configure country per merchant -- no per-country SDK
White-label ISV distributing to merchantsEmbedded LocalEach merchant instance runs independently offline

Combining Both​

You can use both SDK families under the same account. The same API key (zyn_live_*) works with Cloud API and Embedded Local. Billing is based on unique merchant VAT IDs -- your deployment topology doesn't affect pricing.

Each SDK maintains its own hash chain and transaction records. Cloud API records live in the Zyntem backend; Embedded records live locally and are submitted directly to the tax authority. They don't automatically sync.

Switching Between Modes​

Switching from Cloud to Embedded (or vice versa) is not a simple swap. The hash chain breaks -- each signing context maintains its own chain. Transaction history doesn't migrate between the two. Plan for this upfront.

See Architecture Patterns for the full migration checklist.

Recommendation: Choose your deployment mode early. If you need both, run them as a hybrid from the start rather than migrating later.

Cloud API SDKs​

Standard HTTP client libraries generated from our OpenAPI specification. Use these if your POS has reliable internet connectivity and you prefer a thin integration.

# JavaScript/TypeScript
npm install @zyntem/fiscal

# Python
pip install zyntem-fiscal

# Go
go get github.com/javipelopi-dev/fiscalapi-go

Usage is straightforward HTTP:

import { Fiscal } from '@zyntem/fiscal';

const client = new Fiscal({ apiKey: 'zyn_live_...' });
const result = await client.transactions.create({
  location_id: 'loc_123',
  type: 'sale',
  currency: 'EUR',
  items: [{ description: 'Coffee', quantity: 1, unit_price: 350, tax_rate: 2100 }]
});

Available for: JavaScript/TypeScript, Python, Go, PHP, Ruby, Java.

Embedded Local SDKs​

Native libraries that run the fiscalization engine inside your application. Transactions are signed and hash-chained locally with full legal validity. A background queue forwards them to the tax authority within the regulatory window -- no real-time network dependency.

PlatformPackageInstall
Windows (.NET)Zyntem.Fiscalizationdotnet add package Zyntem.Fiscalization
Androidcom.zyntem.fiscalizationimplementation("com.zyntem.fiscalization:fiscalization-sdk:1.0.0")
iOS/iPadFiscalizationSDKSwift Package Manager (binary target)
Web/Node.js (WASM)@zyntem/fiscalnpm install @zyntem/fiscal
Pythonzyntem-fiscalpip install zyntem-fiscal
C/C++/Go (via cgo)Pre-built .so/.dylibDownload from GitHub Releases

All Embedded SDKs expose the same three-function API:

  1. init() or initWithConfig() -- load configuration and provision the engine
  2. processTransaction() -- sign, hash-chain, and queue a transaction
  3. queueStatus() (native only) -- inspect the background submission queue

How Embedded Local Works​

  1. First boot: The library exchanges your API key for a signed token (one network call per merchant)
  2. Every transaction: Signed and hash-chained locally -- no network needed
  3. Background queue: Forwards fiscal records to the tax authority within the legal submission window
  4. Offline resilience: If the network is down, transactions continue. The queue drains when connectivity returns

Token and Billing​

Both SDK families use the same API key (zyn_live_*) and the same account. Billing is based on registered locations across all deployments -- cloud and embedded locations are counted together.

Next Steps​