Avvio rapido Austria

Questa guida rapida ti accompagna attraverso i passaggi essenziali per firmare il tuo primo scontrino conforme a RKSV con fiskaly SIGN AT.

Prerequisiti

Un account fiskaly con un’organizzazione austriaca (registrati su HUB)
Una chiave API e un segreto generati nell’ambiente di TEST
Credenziali di “Utente del servizio web per registratori di cassa” di FinanzOnline dal contribuente

⚠️Conserva le credenziali in modo sicuro

Il tuo segreto API viene mostrato una sola volta. Salvalo immediatamente in un luogo sicuro.

Passaggi

Autenticarsi

curl -X POST https://rksv.fiskaly.com/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "api_secret": "YOUR_API_SECRET"
  }'

const response = await fetch("https://rksv.fiskaly.com/api/v1/auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "YOUR_API_KEY",
    api_secret: "YOUR_API_SECRET",
  }),
});

const { access_token } = await response.json();

import requests

response = requests.post(
    "https://rksv.fiskaly.com/api/v1/auth",
    json={"api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET"},
)
access_token = response.json()["access_token"]

HttpClient client = HttpClient.newHttpClient();
String body = """{"api_key":"YOUR_API_KEY","api_secret":"YOUR_API_SECRET"}""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://rksv.fiskaly.com/api/v1/auth"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

using var client = new HttpClient();
var response = await client.PostAsJsonAsync(
    "https://rksv.fiskaly.com/api/v1/auth",
    new { api_key = "YOUR_API_KEY", api_secret = "YOUR_API_SECRET" });
var result = await response.Content.ReadFromJsonAsync<JsonElement>();
var accessToken = result.GetProperty("access_token").GetString();

Autenticarsi con FinanzOnline

Prima di creare le risorse, autentica le credenziali FinanzOnline del contribuente:

curl -X POST https://rksv.fiskaly.com/api/v1/fon/auth \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "fon_participant_id": "YOUR_FON_PARTICIPANT_ID",
    "fon_user_id": "YOUR_FON_USER_ID",
    "fon_user_pin": "YOUR_FON_USER_PIN"
  }'

await fetch("https://rksv.fiskaly.com/api/v1/fon/auth", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fon_participant_id: "YOUR_FON_PARTICIPANT_ID",
    fon_user_id: "YOUR_FON_USER_ID",
    fon_user_pin: "YOUR_FON_USER_PIN",
  }),
});

requests.post(
    "https://rksv.fiskaly.com/api/v1/fon/auth",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "fon_participant_id": "YOUR_FON_PARTICIPANT_ID",
        "fon_user_id": "YOUR_FON_USER_ID",
        "fon_user_pin": "YOUR_FON_USER_PIN",
    },
)

// POST /api/v1/fon/auth
// Body: {"fon_participant_id":"...","fon_user_id":"...","fon_user_pin":"..."}
// Header: Authorization: Bearer <access_token>

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);
await client.PostAsJsonAsync(
    "https://rksv.fiskaly.com/api/v1/fon/auth",
    new {
        fon_participant_id = "YOUR_FON_PARTICIPANT_ID",
        fon_user_id = "YOUR_FON_USER_ID",
        fon_user_pin = "YOUR_FON_USER_PIN",
    });

📘Note

Queste sono le credenziali per l‘“Utente del servizio web per registratori di cassa” dedicato creato dal contribuente in FinanzOnline — non le credenziali generali di FinanzOnline.

Creare e inizializzare una SCU

SCU_ID=$(uuidgen)

# Creare SCU
curl -X PUT "https://rksv.fiskaly.com/api/v1/signature-creation-unit/${SCU_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"legal_entity_id": {"vat_id": "ATU12345678"}}'

# Inizializzare SCU (registra con FinanzOnline)
curl -X PATCH "https://rksv.fiskaly.com/api/v1/signature-creation-unit/${SCU_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"state": "INITIALIZED"}'

const scuId = crypto.randomUUID();
const BASE = "https://rksv.fiskaly.com/api/v1";
const headers = {
  "Authorization": `Bearer ${accessToken}`,
  "Content-Type": "application/json",
};

// Creare SCU
await fetch(`${BASE}/signature-creation-unit/${scuId}`, {
  method: "PUT", headers,
  body: JSON.stringify({
    legal_entity_id: { vat_id: "ATU12345678" },
  }),
});

// Inizializzare SCU
await fetch(`${BASE}/signature-creation-unit/${scuId}`, {
  method: "PATCH", headers,
  body: JSON.stringify({ state: "INITIALIZED" }),
});

import uuid
scu_id = str(uuid.uuid4())
BASE = "https://rksv.fiskaly.com/api/v1"
hdrs = {"Authorization": f"Bearer {access_token}"}

# Creare SCU
requests.put(f"{BASE}/signature-creation-unit/{scu_id}",
    headers=hdrs, json={"legal_entity_id": {"vat_id": "ATU12345678"}})

# Inizializzare SCU
requests.patch(f"{BASE}/signature-creation-unit/{scu_id}",
    headers=hdrs, json={"state": "INITIALIZED"})

// PUT /signature-creation-unit/{scuId}
// Body: {"legal_entity_id":{"vat_id":"ATU12345678"}}

// PATCH /signature-creation-unit/{scuId}
// Body: {"state":"INITIALIZED"}

var scuId = Guid.NewGuid().ToString();
await client.PutAsJsonAsync(
    $"https://rksv.fiskaly.com/api/v1/signature-creation-unit/{scuId}",
    new { legal_entity_id = new { vat_id = "ATU12345678" } });

await client.PatchAsJsonAsync(
    $"https://rksv.fiskaly.com/api/v1/signature-creation-unit/{scuId}",
    new { state = "INITIALIZED" });

L’inizializzazione della SCU la registra automaticamente con FinanzOnline.

Creare e inizializzare un registratore di cassa

CR_ID=$(uuidgen)

# Creare registratore di cassa
curl -X PUT "https://rksv.fiskaly.com/api/v1/cash-register/${CR_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"description": "POS Terminal 1"}'

# Registrare con FinanzOnline
curl -X PATCH "https://rksv.fiskaly.com/api/v1/cash-register/${CR_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"state": "REGISTERED"}'

# Inizializzare (crea e valida lo scontrino iniziale)
curl -X PATCH "https://rksv.fiskaly.com/api/v1/cash-register/${CR_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"state": "INITIALIZED"}'

const crId = crypto.randomUUID();

// Creare registratore di cassa
await fetch(`${BASE}/cash-register/${crId}`, {
  method: "PUT", headers,
  body: JSON.stringify({ description: "POS Terminal 1" }),
});

// Registrare con FinanzOnline
await fetch(`${BASE}/cash-register/${crId}`, {
  method: "PATCH", headers,
  body: JSON.stringify({ state: "REGISTERED" }),
});

// Inizializzare
await fetch(`${BASE}/cash-register/${crId}`, {
  method: "PATCH", headers,
  body: JSON.stringify({ state: "INITIALIZED" }),
});

cr_id = str(uuid.uuid4())

requests.put(f"{BASE}/cash-register/{cr_id}",
    headers=hdrs, json={"description": "POS Terminal 1"})

requests.patch(f"{BASE}/cash-register/{cr_id}",
    headers=hdrs, json={"state": "REGISTERED"})

requests.patch(f"{BASE}/cash-register/{cr_id}",
    headers=hdrs, json={"state": "INITIALIZED"})

// PUT /cash-register/{crId} → {"description":"POS Terminal 1"}
// PATCH /cash-register/{crId} → {"state":"REGISTERED"}
// PATCH /cash-register/{crId} → {"state":"INITIALIZED"}

var crId = Guid.NewGuid().ToString();
await client.PutAsJsonAsync(
    $"{BASE}/cash-register/{crId}",
    new { description = "POS Terminal 1" });
await client.PatchAsJsonAsync(
    $"{BASE}/cash-register/{crId}", new { state = "REGISTERED" });
await client.PatchAsJsonAsync(
    $"{BASE}/cash-register/{crId}", new { state = "INITIALIZED" });

📘Note

I registratori di cassa richiedono due transizioni di stato: prima a REGISTERED (che registra con FinanzOnline), poi a INITIALIZED (che crea e valida lo scontrino iniziale).

Firmare il primo scontrino

RECEIPT_ID=$(uuidgen)

curl -X PUT "https://rksv.fiskaly.com/api/v1/cash-register/${CR_ID}/receipt/${RECEIPT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "receipt_type": "NORMAL",
    "schema": {
      "standard_v1": {
        "receipt": {
          "amounts_per_vat_rate": [
            {"vat_rate": "STANDARD", "amount": "12.00"}
          ],
          "amounts_per_payment_type": [
            {"payment_type": "CASH", "amount": "12.00"}
          ]
        }
      }
    }
  }'

const receiptId = crypto.randomUUID();

const receipt = await fetch(
  `${BASE}/cash-register/${crId}/receipt/${receiptId}`,
  {
    method: "PUT", headers,
    body: JSON.stringify({
      receipt_type: "NORMAL",
      schema: {
        standard_v1: {
          receipt: {
            amounts_per_vat_rate: [
              { vat_rate: "STANDARD", amount: "12.00" },
            ],
            amounts_per_payment_type: [
              { payment_type: "CASH", amount: "12.00" },
            ],
          },
        },
      },
    }),
  }
).then(r => r.json());

console.log("QR Code Data:", receipt.qr_code_data);
console.log("Receipt Number:", receipt.receipt_number);

receipt_id = str(uuid.uuid4())

receipt = requests.put(
    f"{BASE}/cash-register/{cr_id}/receipt/{receipt_id}",
    headers=hdrs,
    json={
        "receipt_type": "NORMAL",
        "schema": {
            "standard_v1": {
                "receipt": {
                    "amounts_per_vat_rate": [
                        {"vat_rate": "STANDARD", "amount": "12.00"}
                    ],
                    "amounts_per_payment_type": [
                        {"payment_type": "CASH", "amount": "12.00"}
                    ],
                }
            }
        },
    },
).json()

print("QR Code:", receipt["qr_code_data"])

// PUT /cash-register/{crId}/receipt/{receiptId}
// Body: {"receipt_type":"NORMAL","schema":{"standard_v1":{...}}}
// La risposta contiene qr_code_data, receipt_number, time_signature

var receiptId = Guid.NewGuid().ToString();
var receiptResp = await client.PutAsJsonAsync(
    $"{BASE}/cash-register/{crId}/receipt/{receiptId}",
    new {
        receipt_type = "NORMAL",
        schema = new { standard_v1 = new { receipt = new {
            amounts_per_vat_rate = new[] {
                new { vat_rate = "STANDARD", amount = "12.00" } },
            amounts_per_payment_type = new[] {
                new { payment_type = "CASH", amount = "12.00" } },
        }}}});

La risposta contiene tutto il necessario per uno scontrino conforme a RKSV: qr_code_data (dati per il codice QR RKSV obbligatorio), receipt_number, time_signature e cash_register_serial_number (campi di testo richiesti).

Esegui lo script

Vuoi eseguire tutti i passaggi automaticamente? Scarica ed esegui il nostro script di avvio rapido:

# Scarica ed esegui
curl -O https://workspace.fiskaly.com/scripts/sign-at-quickstart.sh
export API_KEY="your_api_key"
export API_SECRET="your_api_secret"
export FON_PARTICIPANT_ID="your_fon_participant_id"
export FON_USER_ID="your_fon_user_id"
export FON_USER_PIN="your_fon_user_pin"
export VAT_ID="ATU12345678"
bash sign-at-quickstart.sh

# Scarica ed esegui
curl -O https://workspace.fiskaly.com/scripts/sign-at-quickstart.mjs
API_KEY="your_key" API_SECRET="your_secret" FON_PARTICIPANT_ID="id" FON_USER_ID="id" FON_USER_PIN="pin" VAT_ID="ATU12345678" node sign-at-quickstart.mjs

Prossimi passi

Guida all'integrazione completa

Guida completa passo dopo passo inclusa la configurazione dell'organizzazione

Dati scontrino

Campi obbligatori dello scontrino e requisiti di formattazione

Riferimento API SIGN AT

Documentazione completa degli endpoint

Was this page helpful?