Inicio rápido de Italia

Este inicio rápido te guía a través de la creación de su primer registro fiscal con fiskaly SIGN IT, desde la autenticación hasta un documento comercial conforme transmitido a la AdE (Agenzia delle Entrate).

Requisitos previos

Una cuenta fiskaly (regístrese en hub.fiskaly.com)
Una clave de API y un secreto para una organización GROUP en el entorno TEST
Credenciales de Fisconline para el contribuyente (en LIVE; no necesarias para TEST)

⚠️Almacene las credenciales de forma segura

Tu secreto de API se muestra solo una vez. Guárdelo inmediatamente en un lugar seguro.

Pasos

Autenticarse

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 y SIGN FR comparten la misma plataforma de API. Todas las solicitudes requieren el encabezado X-Api-Version. Las operaciones de escritura también necesitan un encabezado X-Idempotency-Key con un valor UUIDv3 o UUIDv4.

Crear una organización UNIT

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" } });

Crear una clave de API de sujeto y autenticarse

Crea una clave de API para la UNIT y autentíquese con ella:

# Crear clave de API de sujeto (con ámbito en la UNIT)
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"}}'

# Autenticarse con la nueva clave de API
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

Crear contribuyente, ubicación y sistema

# Crear contribuyente
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"
        }
      }
    }
  }'

# Activar contribuyente
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

💡Crea primero el contribuyente

Después, crea una o varias ubicaciones (type: "BRANCH") y un sistema (type: "FISCAL_DEVICE"). Luego actualiza su estado a COMMISSIONED para activarlos. Consulta la guía de integración completa para conocer la secuencia completa.

Crear su primer registro

Los registros requieren dos llamadas: una INTENTION seguida de una TRANSACTION.

# Parte 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"}
    }
  }'

# Parte B: Transaction
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

Una vez que el registro alcanza el estado COMPLETED con el modo FINISHED, el documento comercial ha sido transmitido a la AdE.

Ejecutar el script

¿Desea ejecutar todos los pasos automáticamente? Descarga y ejecuta nuestro script de inicio rápido:

# Descargar y ejecutar
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

# Descargar y ejecutar
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

Próximos pasos

Guía de integración completa

Guía paso a paso completa con los 11 pasos

Conformidad de recibos

Requisitos de recibos B2C italianos

Credenciales

Cómo obtener credenciales de Fisconline

Was this page helpful?