Italien Quickstart

Dieser Quickstart führt Sie durch die Erstellung Ihres ersten Fiskalbelegs mit fiskaly SIGN IT — von der Authentifizierung bis zu einem konformen Handelsdokument, das an die AdE (Agenzia delle Entrate) übermittelt wird.

Voraussetzungen

Ein fiskaly-Konto (Registrierung unter hub.fiskaly.com)
Ein API-Schlüssel und -Secret für eine GROUP-Organisation in der TEST-Umgebung
Fisconline-Zugangsdaten für den Steuerpflichtigen (in LIVE; für TEST nicht erforderlich)

⚠️Zugangsdaten sicher aufbewahren

Ihr API-Secret wird nur einmal angezeigt. Speichern Sie es sofort an einem sicheren Ort.

Schritte

Authentifizieren

curl -X POST https://test.api.fiskaly.com/tokens \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -d '{
    "content": {
      "type": "API_KEY",
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    }
  }'

const BASE = "https://test.api.fiskaly.com";
const API_VERSION = "2026-02-03";

const authResp = await fetch(`${BASE}/tokens`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Version": API_VERSION,
  },
  body: JSON.stringify({
    content: { type: "API_KEY", key: "YOUR_API_KEY", secret: "YOUR_API_SECRET" },
  }),
});

const { access_token } = await authResp.json();
const headers = {
  "Authorization": `Bearer ${access_token}`,
  "Content-Type": "application/json",
  "X-Api-Version": API_VERSION,
};

import requests, uuid

BASE = "https://test.api.fiskaly.com"
API_VERSION = "2026-02-03"

auth = requests.post(f"{BASE}/tokens", json={
    "content": {"type": "API_KEY", "key": "YOUR_API_KEY", "secret": "YOUR_API_SECRET"}
}, headers={"X-Api-Version": API_VERSION})

access_token = auth.json()["access_token"]
hdrs = {"Authorization": f"Bearer {access_token}", "X-Api-Version": API_VERSION}

// POST https://test.api.fiskaly.com/tokens
// Headers: Content-Type: application/json, X-Api-Version: 2026-02-03
// Body: {"content":{"type":"API_KEY","key":"...","secret":"..."}}

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Version", "2026-02-03");

var authResp = await client.PostAsJsonAsync(
    "https://test.api.fiskaly.com/tokens",
    new { content = new { type = "API_KEY", key = "YOUR_API_KEY", secret = "YOUR_API_SECRET" } });

📘Note

SIGN IT und SIGN FR nutzen dieselbe API-Plattform. Alle Anfragen erfordern den X-Api-Version-Header. Schreiboperationen benötigen zusätzlich einen X-Idempotency-Key-Header mit einem UUIDv3- oder UUIDv4-Wert.

Organisation UNIT anlegen

curl -X POST https://test.api.fiskaly.com/organizations \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "content": {
      "type": "UNIT",
      "name": "My Italian Merchant"
    }
  }'

const org = await fetch(`${BASE}/organizations`, {
  method: "POST",
  headers: { ...headers, "X-Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    content: { type: "UNIT", name: "My Italian Merchant" },
  }),
}).then(r => r.json());

const orgId = org.id;

org = requests.post(f"{BASE}/organizations", headers={
    **hdrs, "X-Idempotency-Key": str(uuid.uuid4())
}, json={"content": {"type": "UNIT", "name": "My Italian Merchant"}}).json()

org_id = org["id"]

// POST /organizations
// Headers: X-Idempotency-Key: <uuid>
// Body: {"content":{"type":"UNIT","name":"My Italian Merchant"}}

client.DefaultRequestHeaders.Add("X-Idempotency-Key", Guid.NewGuid().ToString());
var org = await client.PostAsJsonAsync($"{BASE}/organizations",
    new { content = new { type = "UNIT", name = "My Italian Merchant" } });

Subject-API-Schlüssel anlegen und authentifizieren

Erstellen Sie einen API-Schlüssel für die UNIT und authentifizieren Sie sich damit:

# Subject-API-Schlüssel anlegen (auf die UNIT beschränkt)
curl -X POST https://test.api.fiskaly.com/subjects \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "X-Scope-Identifier: ${ORG_ID}" \
  -d '{"content": {"type": "API_KEY"}}'

# Mit dem neuen API-Schlüssel authentifizieren
curl -X POST https://test.api.fiskaly.com/tokens \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -d '{"content": {"type": "API_KEY", "key": "NEW_KEY", "secret": "NEW_SECRET"}}'

// Create Subject API Key scoped to the UNIT
const subject = await fetch(`${BASE}/subjects`, {
  method: "POST",
  headers: {
    ...headers,
    "X-Idempotency-Key": crypto.randomUUID(),
    "X-Scope-Identifier": orgId,
  },
  body: JSON.stringify({ content: { type: "API_KEY" } }),
}).then(r => r.json());

// Re-authenticate with the new key
const newAuth = await fetch(`${BASE}/tokens`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Version": API_VERSION,
  },
  body: JSON.stringify({
    content: { type: "API_KEY", key: subject.key, secret: subject.secret },
  }),
}).then(r => r.json());

headers.Authorization = `Bearer ${newAuth.access_token}`;

# Create Subject API Key
subject = requests.post(f"{BASE}/subjects", headers={
    **hdrs, "X-Idempotency-Key": str(uuid.uuid4()),
    "X-Scope-Identifier": org_id,
}, json={"content": {"type": "API_KEY"}}).json()

# Re-authenticate
new_auth = requests.post(f"{BASE}/tokens", headers={"X-Api-Version": API_VERSION},
    json={"content": {"type": "API_KEY", "key": subject["key"], "secret": subject["secret"]}}).json()
hdrs["Authorization"] = f"Bearer {new_auth['access_token']}"

// POST /subjects with X-Scope-Identifier: <orgId>
// Body: {"content":{"type":"API_KEY"}}
// Then POST /tokens with the new key and secret

// Create Subject API Key, then re-authenticate with the new credentials
// POST /subjects → returns key + secret
// POST /tokens → returns new access_token

Steuerpflichtigen, Standort und System anlegen

# Steuerpflichtigen anlegen
curl -X POST https://test.api.fiskaly.com/taxpayers \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "content": {
      "type": "COMPANY",
      "name": {
        "legal": "La Pizzeria di Mario S.r.l.",
        "trade": "La Pizzeria di Mario"
      },
      "address": {
        "line": {
          "type": "STREET_NUMBER",
          "street": "Via Roma",
          "number": "123"
        },
        "code": "00100",
        "city": "Rome",
        "country": "IT"
      },
      "fiscalization": {
        "type": "IT",
        "tax_id_number": "12345678901",
        "vat_id_number": "12345678901",
        "credentials": {
          "type": "FISCONLINE",
          "pin": "1234567890",
          "password": "MySecurePassword123",
          "tax_id_number": "RSSMRA85M01H501Z"
        }
      }
    }
  }'

# Steuerpflichtigen aktivieren
curl -X PATCH "https://test.api.fiskaly.com/taxpayers/${TAXPAYER_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{"content": {"state": "COMMISSIONED"}}'

// Create Taxpayer
const taxpayer = await fetch(`${BASE}/taxpayers`, {
  method: "POST",
  headers: { ...headers, "X-Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    content: {
      type: "COMPANY",
      name: { legal: "My Company S.r.l." },
      address: { street: "Via Roma 1", zip: "00100", city: "Roma", country_code: "IT" },
      fiscalization: {
        type: "IT",
        tax_id_number: "RSSMRA85M01H501Z",
        vat_id_number: "IT12345678901",
      },
    },
  }),
}).then(r => r.json());

// Commission Taxpayer
await fetch(`${BASE}/taxpayers/${taxpayer.id}`, {
  method: "PATCH",
  headers: { ...headers, "X-Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ content: { state: "COMMISSIONED" } }),
});

// Create + Commission Location and System follow the same pattern

# Create Taxpayer
taxpayer = requests.post(f"{BASE}/taxpayers", headers={
    **hdrs, "X-Idempotency-Key": str(uuid.uuid4())
}, json={"content": {
    "type": "COMPANY",
    "name": {"legal": "My Company S.r.l."},
    "address": {"street": "Via Roma 1", "zip": "00100", "city": "Roma", "country_code": "IT"},
    "fiscalization": {"type": "IT", "tax_id_number": "RSSMRA85M01H501Z", "vat_id_number": "IT12345678901"},
}}).json()

# Commission Taxpayer
requests.patch(f"{BASE}/taxpayers/{taxpayer['id']}", headers={
    **hdrs, "X-Idempotency-Key": str(uuid.uuid4())
}, json={"content": {"state": "COMMISSIONED"}})

// POST /taxpayers → create, then PATCH /taxpayers/{id} → commission
// POST /locations → create, then PATCH /locations/{id} → commission
// POST /systems → create, then PATCH /systems/{id} → commission

// POST /taxpayers → create COMPANY with IT fiscalization
// PATCH /taxpayers/{id} → {"content":{"state":"COMMISSIONED"}}
// Same pattern for locations and systems

💡Zuerst Steuerpflichtigen anlegen

Danach legen Sie einen oder mehrere Standorte (type: "BRANCH") und ein System (type: "FISCAL_DEVICE") an. Setzen Sie anschließend den Status auf COMMISSIONED, um sie zu aktivieren. Die vollständige Sequenz finden Sie im vollständigen Integrationsleitfaden.

Ersten Beleg erstellen

Belege erfordern zwei Aufrufe: zuerst eine INTENTION, dann eine TRANSACTION.

# Teil A: Intention
curl -X POST https://test.api.fiskaly.com/records \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "content": {
      "type": "INTENTION",
      "system": {"id": "YOUR_SYSTEM_ID"},
      "operation": {"type": "TRANSACTION"}
    }
  }'

# Teil B: Transaktion
curl -X POST https://test.api.fiskaly.com/records \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "content": {
      "type": "TRANSACTION",
      "record": {
        "id": "your_intention_id"
      },
      "operation": {
        "type": "RECEIPT",
        "document": {
          "number": "1",
          "total_vat": {
            "amount": "2.20",
            "exclusive": "10.00",
            "inclusive": "12.20"
          }
        },
        "entries": [
          {
            "type": "SALE",
            "details": {
              "concept": "GOOD"
            },
            "data": {
              "type": "ITEM",
              "text": "Margherita Pizza",
              "unit": {
                "quantity": "1",
                "price": "12.20"
              },
              "value": {
                "base": "10.00",
                "discount": "0.00"
              },
              "vat": {
                "type": "VAT_RATE",
                "code": "STANDARD",
                "percentage": "22.00",
                "exclusive": "10.00",
                "inclusive": "12.20",
                "amount": "2.20"
              }
            }
          }
        ],
        "payments": [
          {
            "type": "CASH",
            "details": {
              "amount": "12.20"
            }
          }
        ]
      }
    }
  }'

// Part A: Intention
const intention = await fetch(`${BASE}/records`, {
  method: "POST",
  headers: { ...headers, "X-Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    content: {
      type: "INTENTION",
      system: { id: systemId },
      operation: { type: "TRANSACTION" },
    },
  }),
}).then(r => r.json());

// Part B: Transaction
const record = await fetch(`${BASE}/records`, {
  method: "POST",
  headers: { ...headers, "X-Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    content: {
      type: "TRANSACTION",
      intention: { id: intention.id },
      operation: {
        type: "RECEIPT",
        document: {
          number: "1",
          date: "2026-02-27",
          amounts: {
            total_including_vat: "12.20",
            total_excluding_vat: "10.00",
          },
        },
        entries: [{
          type: "SALE",
          description: "Product A",
          nature: "GOOD",
          quantity: "1",
          amounts: {
            unit_including_vat: "12.20",
            total_including_vat: "12.20",
            total_excluding_vat: "10.00",
            vat: { rate: "22.00", amount: "2.20" },
          },
        }],
      },
    },
  }),
}).then(r => r.json());

console.log("Progressive number:", record.compliance?.data);

# Part A: Intention
intention = requests.post(f"{BASE}/records", headers={
    **hdrs, "X-Idempotency-Key": str(uuid.uuid4())
}, json={"content": {
    "type": "INTENTION",
    "system": {"id": system_id},
    "operation": {"type": "TRANSACTION"},
}}).json()

# Part B: Transaction
record = requests.post(f"{BASE}/records", headers={
    **hdrs, "X-Idempotency-Key": str(uuid.uuid4())
}, json={"content": {
    "type": "TRANSACTION",
    "intention": {"id": intention["id"]},
    "operation": {
        "type": "RECEIPT",
        "document": {"number": "1", "date": "2026-02-27",
            "amounts": {"total_including_vat": "12.20", "total_excluding_vat": "10.00"}},
        "entries": [{"type": "SALE", "description": "Product A", "nature": "GOOD",
            "quantity": "1", "amounts": {
                "unit_including_vat": "12.20", "total_including_vat": "12.20",
                "total_excluding_vat": "10.00", "vat": {"rate": "22.00", "amount": "2.20"}}}],
    },
}}).json()

// POST /records → INTENTION with system.id and operation.type = TRANSACTION
// POST /records → TRANSACTION with intention.id and receipt data
// Response includes compliance.data with the AdE progressive number

// POST /records → INTENTION, then POST /records → TRANSACTION
// Each requires X-Idempotency-Key header
// Transaction response contains compliance data from AdE

Sobald der Beleg den Status COMPLETED mit dem Modus FINISHED erreicht, wurde das Handelsdokument an die AdE übermittelt.

Skript ausführen

Möchten Sie alle Schritte automatisch durchlaufen? Laden Sie unser Quickstart-Skript herunter und führen Sie es aus:

# Herunterladen und ausführen
curl -O https://workspace.fiskaly.com/scripts/sign-it-quickstart.sh
export API_KEY="your_api_key"
export API_SECRET="your_api_secret"
export GROUP_ORG_ID="your_group_org_id"
bash sign-it-quickstart.sh

# Herunterladen und ausführen
curl -O https://workspace.fiskaly.com/scripts/sign-it-quickstart.mjs
API_KEY="your_key" API_SECRET="your_secret" GROUP_ORG_ID="your_org_id" node sign-it-quickstart.mjs

Nächste Schritte

Vollständiger Integrationsleitfaden

Komplette Schritt-für-Schritt-Anleitung mit allen 11 Schritten

Belegkonformität

Italienische B2C-Beleganforderungen

Zugangsdaten

So erhalten Sie Fisconline-Zugangsdaten

Was this page helpful?