Skip to main content

Quickstart

Get your first fiscalized transaction running in 5 minutes. Each example goes from install to a verified transaction.

Prerequisites​

  • A Zyntem account with an API key (zyn_test_* for sandbox, zyn_live_* for production)
  • Your merchant's country code and tax ID

Python (Embedded Local)​

pip install zyntem-fiscal
import zyntem_fiscal

# 1. Initialize in sandbox mode
zyntem_fiscal.init_with_config({
    "country": "ES",
    "tax_id": "B12345678",
    "environment": "sandbox",
})

# 2. Process a transaction
result = zyntem_fiscal.process_transaction({
    "type": "sale",
    "amount": "100.00",
    "currency": "EUR",
    "items": [
        {
            "description": "Widget",
            "amount": "100.00",
            "tax_rate": "21.0",
        }
    ],
})

# 3. Check the result
if result["status"] == "ok":
    print(f"Fiscal ID: {result['fiscal_id']}")
    print(f"Signature: {result['signature']}")
else:
    print(f"Error: {result['error_message']}")

.NET (Embedded Local)​

dotnet add package Zyntem.Fiscalization
using Zyntem.Fiscalization;

// 1. Initialize with JSON config
string configResult = FiscalEngine.InitWithConfig(@"{
    ""country"": ""ES"",
    ""tax_authority"": ""AEAT"",
    ""mode"": ""sandbox""
}");
Console.WriteLine($"Init: {configResult}");

// 2. Process a transaction
string txResult = FiscalEngine.ProcessTransaction(@"{
    ""type"": ""sale"",
    ""amount"": 100.00,
    ""vat_rate"": 21.0,
    ""currency"": ""EUR"",
    ""description"": ""Test transaction""
}");
Console.WriteLine($"Result: {txResult}");

Kotlin / Android (Embedded Local)​

Add to your module's build.gradle.kts:

implementation("com.zyntem.fiscalization:fiscalization-sdk:1.0.0")
import com.zyntem.fiscalization.FiscalEngine

// 1. Initialize (call once, e.g. in Application.onCreate)
val initResult = FiscalEngine.init("""
    {"country": "ES", "tax_id": "B12345678", "environment": "sandbox"}
""")

if (!initResult.success) {
    Log.e("Fiscal", "Init failed: ${initResult.errorMessage}")
    return
}

// 2. Process a transaction
val result = FiscalEngine.processTransaction("""
    {
        "type": "sale",
        "amount": 4200,
        "currency": "EUR",
        "items": [
            {
                "description": "Premium Widget",
                "quantity": 2000,
                "unit_price": 2100,
                "tax_rate": 2100,
                "tax_amount": 882,
                "total_amount": 5082
            }
        ]
    }
""")

if (result.success) {
    Log.i("Fiscal", "Fiscal ID: ${result.fiscalId}")
} else {
    Log.e("Fiscal", "Failed: ${result.errorMessage}")
}

JavaScript / Node.js (WASM)​

npm install @zyntem/fiscal
import { load, initialize, processTransaction } from "@zyntem/fiscal";

// 1. Load the WASM module (once, at startup)
await load();

// 2. Initialize the engine
const initResult = initialize(JSON.stringify({
  country: "ES",
  tax_id: "B12345678",
  environment: "sandbox",
}));
console.log("Init:", JSON.parse(initResult));

// 3. Process a transaction
const result = processTransaction(JSON.stringify({
  transaction_type: "sale",
  amount: 4200,
  currency: "EUR",
  country: "ES",
  tax_id: "B12345678",
  items: [
    {
      description: "Premium Widget",
      quantity: 2000,
      unit_price: 2100,
      tax_rate: 2100,
      tax_amount: 882,
      total_amount: 5082,
    },
  ],
}));
console.log("Result:", JSON.parse(result));

C (Embedded Local, shared library)​

Download the tarball for your platform from GitHub Releases and extract it.

#include <stdio.h>
#include <fiscalization.h>

int main(void) {
    // 1. Initialize with JSON config
    char *init = fiscal_init_with_config(
        "{\"country\":\"ES\",\"tax_id\":\"B12345678\",\"environment\":\"sandbox\"}"
    );
    printf("Init: %s\n", init);
    fiscal_free_string(init);

    // 2. Process a transaction
    char *result = fiscal_process_transaction(
        "{\"type\":\"sale\",\"amount\":10000,\"currency\":\"EUR\","
        "\"items\":[{\"description\":\"Widget\",\"amount\":10000,\"tax_rate\":2100}]}"
    );
    printf("Result: %s\n", result);
    fiscal_free_string(result);

    return 0;
}

Compile and link:

# Using pkg-config (if tarball is installed)
gcc example.c $(pkg-config --cflags --libs fiscalization) -o example

# Or link manually
gcc example.c -I./include -L./lib -lfiscalization -o example

Cloud API (TypeScript)​

npm install @zyntem/fiscalapi
import { FiscalAPI } from '@zyntem/fiscalapi';

const client = new FiscalAPI({
  apiKey: 'zyn_test_...',          // sandbox key
  baseUrl: 'https://api.zyntem.com' // optional, this is the default
});

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 }
  ],
});

console.log(result.fiscal_id);
console.log(result.status);

Verifying It Worked​

All Embedded SDKs return a JSON response with the same structure:

{
  "status": "ok",
  "fiscal_id": "ES-AEAT-2026-00001",
  "signature": "a1b2c3d4...",
  "hash_chain": "prev:0000...;curr:a1b2...",
  "queued_at": "2026-03-22T10:00:00Z"
}
FieldMeaning
status"ok" = signed and queued, "failed" = validation or engine error
fiscal_idAuthority-assigned or locally-generated fiscal identifier
signatureCryptographic signature for the transaction
hash_chainPrevious and current hash in the chain (tamper evidence)
queued_atWhen the transaction was queued for submission (Embedded only)

Next Steps​