Configuration Reference

All Embedded Local SDKs accept configuration as either a YAML file path (init(path)) or an inline JSON object (initWithConfig(json)). Both methods accept the same fields.

Initialization Methods

File-based: fiscal_init(path)

Pass a path to a YAML or JSON file. If NULL or empty, the engine uses built-in defaults with environment variable overrides.

# fiscalization.yaml
country: ES
tax_id: B12345678
environment: sandbox
api_key: zyn_test_abc123
live_mode: false

storage:
  backend: sqlite
  sqlite_path: ./fiscalization.db

certs:
  dir: ./certs

submission:
  auto_submit: true
  retry_max: 3
  retry_delay_secs: 60

logging:
  level: info

Inline: fiscal_init_with_config(json)

Pass a JSON string directly. Useful for environments where file access is restricted (Android, WASM) or when config comes from your own settings store.

zyntem_fiscal.init_with_config({
    "country": "ES",
    "tax_id": "B12345678",
    "environment": "sandbox",
    "api_key": "zyn_test_abc123",
})

Configuration Fields

Required

Field	Type	Description
country	string	ISO 3166-1 alpha-2 country code (e.g. "ES", "PT", "FR", "IT")
tax_id	string	Merchant VAT / tax identification number

Authentication

Field	Type	Default	Description
api_key	string	$ZYNTEM_API_KEY	API key for token provisioning. Falls back to the ZYNTEM_API_KEY environment variable if not set
environment	string	"production"	"sandbox" or "production". The SDK validates that the key prefix matches: zyn_test_* requires "sandbox", zyn_live_* requires "production"
live_mode	boolean	false	Must be true for production use with zyn_live_* keys. Also controlled by FISCALIZATION_LIVE_ENABLED env var

Storage

Field	Type	Default	Description
storage.backend	string	"sqlite"	"sqlite" for Embedded SDK, "postgres" for Cloud API server
storage.sqlite_path	string	"./fiscalization.db"	Path to the SQLite database for local storage

Certificates

Field	Type	Default	Description
certs.backend	string	"filesystem"	"filesystem" or "secretmanager" (GCP Secret Manager)
certs.dir	string	"./certs"	Directory for PKCS#12 certificate files (filesystem backend)
certs.password	string	""	PKCS#12 password. Prefer FISCALIZATION_CERTS_PASSWORD env var
certs.secretmanager.project	string	--	GCP project ID (secretmanager backend only)

Submission

The submission queue stores fiscalized transactions locally and submits them to the tax authority in the background.

Field	Type	Default	Description
submission.auto_submit	boolean	true	Automatically submit prepared records to the tax authority
submission.retry_max	integer	3	Maximum retry attempts at the engine level
submission.retry_delay_secs	integer	60	Base delay between retries in seconds

The queue itself retries up to 20 attempts per entry with exponential backoff (starting at 2s, doubling each attempt, capped at 6 hours). After exhausting all attempts, entries move to dead status.

Logging

Field	Type	Default	Description
logging.level	string	"info"	"error", "warn", "info", "debug", "trace". Also overridden by FISCALIZATION_LOG_LEVEL env var

Country-Specific

Country-specific fields go in a country_config object. See the country guides for details:

• Spain -- system, territory, certificate_id
• France -- siret, naf_code, signing key
• Italy -- system (sdi/dc), codice_fiscale, cau_code
• Portugal -- software_certificate_number, series, atcud_code

Environment Variables

Environment variables override config file values. Useful for containerized deployments and CI.

Variable	Overrides	Example
ZYNTEM_API_KEY	api_key	zyn_live_abc123
ENVIRONMENT	environment	production
FISCALIZATION_LIVE_ENABLED	live_mode	true
FISCALIZATION_CERTS_DIR	certs.dir	/data/certs
FISCALIZATION_CERTS_PASSWORD	certs.password	(secret)
FISCALIZATION_STORAGE_BACKEND	storage.backend	sqlite
FISCALIZATION_LOG_LEVEL	logging.level	debug
FISCALIZATION_SUBMISSION_AUTO	submission.auto_submit	true
FISCALIZATION_SUBMISSION_RETRY_MAX	submission.retry_max	3
FISCALIZATION_SUBMISSION_RETRY_DELAY	submission.retry_delay_secs	60

Platform Notes

Android

File paths are relative to the app's internal storage. Use initWithConfig() with a JSON string instead of file paths:

FiscalEngine.initWithConfig("""
    {
        "country": "ES",
        "tax_id": "B12345678",
        "environment": "sandbox",
        "api_key": "zyn_test_abc123",
        "storage": {"sqlite_path": "${context.filesDir}/fiscalization.db"}
    }
""")

WASM / Browser

The WASM build does not support the submission queue or file-based config. Use initWithConfig() with inline JSON. Queue submission must be handled by your backend via the Cloud API.

initialize(JSON.stringify({
  country: "ES",
  tax_id: "B12345678",
  environment: "sandbox",
  api_key: "zyn_test_abc123",
}));

.NET

Config file discovery works from the application's working directory. For Windows services, set environment variables to absolute paths.

Init Response

Both init() and initWithConfig() return a JSON string:

// Success
{"status": "ok"}

// Failure
{"status": "error", "error_message": "missing required field: country"}

Always check status before calling processTransaction(). See Embedded Error Handling for the full list of init errors.