Section navigation

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-06-01" \
  -d '{
    "content": {
      "type": "API_KEY",
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    }
  }'

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

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-06-01"

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-06-01
// Body: {"content":{"type":"API_KEY","key":"...","secret":"..."}}

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

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-06-01" \
  -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-06-01" \
  -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-06-01" \
  -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-06-01" \
  -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-06-01" \
  -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.

📘Nota sobre la facturación

Para la mayoría de los contratos, los System son las unidades utilizadas para la facturación con fiskaly. Un System pasa a ser relevante para la facturación en cuanto su estado cambia de ACQUIRED a COMMISSIONED en el entorno LIVE. Los recursos en el entorno TEST no se facturan. Para conocer las condiciones exactas de facturación, consulte su contrato con fiskaly.

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-06-01" \
  -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-06-01" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "content": {
      "type": "TRANSACTION",
      "record": {
        "id": "your_intention_id"
      },
      "operation": {
        "type": "RECEIPT",
        "document": {
          "number": "0001"
        },
        "breakdown": [
          {
            "type": "VAT_RATE",
            "code": "STANDARD",
            "percentage": "22.00",
            "exclusive": "20.00",
            "inclusive": "24.40",
            "amount": "4.40"
          },
          {
            "type": "VAT_RATE",
            "code": "REDUCED_1",
            "percentage": "10.00",
            "exclusive": "0.54545455",
            "inclusive": "0.60",
            "amount": "0.05454545"
          }
        ],
        "totals": {
          "vat": {
            "amount": "4.45454545",
            "exclusive": "20.54545455",
            "inclusive": "25.00"
          }
        },
        "entries": [
          {
            "type": "SALE",
            "details": {
              "concept": "GOOD"
            },
            "data": {
              "type": "ITEM",
              "text": "Margherita pizza",
              "unit": {
                "quantity": "2.00",
                "price": {
                  "inclusive": "12.20",
                  "exclusive": "10.00"
                }
              },
              "value": {
                "base": "20.00",
                "discount": "0.00"
              },
              "vat": {
                "type": "VAT_RATE",
                "code": "STANDARD",
                "percentage": "22.00",
                "exclusive": "20.00",
                "inclusive": "24.40",
                "amount": "4.40"
              }
            }
          },
          {
            "type": "SALE",
            "details": {
              "concept": "SERVICE"
            },
            "data": {
              "type": "ITEM",
              "text": "Service ABC",
              "unit": {
                "quantity": "1.00",
                "price": {
                  "inclusive": "0.60",
                  "exclusive": "0.54545455"
                }
              },
              "value": {
                "base": "0.54545455",
                "discount": "0.00"
              },
              "vat": {
                "type": "VAT_RATE",
                "code": "REDUCED_1",
                "percentage": "10.00",
                "exclusive": "0.54545455",
                "inclusive": "0.60",
                "amount": "0.05454545"
              }
            }
          }
        ],
        "payments": [
          {
            "type": "CASH",
            "details": {
              "amount": "25.00"
            }
          }
        ]
      }
    }
  }'

// 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",
      record: { id: intention.id },
      operation: {
        type: "RECEIPT",
        document: {
          number: "0001",
        },
        breakdown: [
          {
            type: "VAT_RATE",
            code: "STANDARD",
            percentage: "22.00",
            exclusive: "20.00",
            inclusive: "24.40",
            amount: "4.40",
          },
          {
            type: "VAT_RATE",
            code: "REDUCED_1",
            percentage: "10.00",
            exclusive: "0.54545455",
            inclusive: "0.60",
            amount: "0.05454545",
          },
        ],
        totals: {
          vat: {
            amount: "4.45454545",
            exclusive: "20.54545455",
            inclusive: "25.00",
          },
        },
        entries: [
          {
            type: "SALE",
            details: {
              concept: "GOOD",
            },
            data: {
              type: "ITEM",
              text: "Margherita pizza",
              unit: {
                quantity: "2.00",
                price: {
                  inclusive: "12.20",
                  exclusive: "10.00",
                },
              },
              value: {
                base: "20.00",
                discount: "0.00",
              },
              vat: {
                type: "VAT_RATE",
                code: "STANDARD",
                percentage: "22.00",
                exclusive: "20.00",
                inclusive: "24.40",
                amount: "4.40",
              },
            },
          },
          {
            type: "SALE",
            details: {
              concept: "SERVICE",
            },
            data: {
              type: "ITEM",
              text: "Service ABC",
              unit: {
                quantity: "1.00",
                price: {
                  inclusive: "0.60",
                  exclusive: "0.54545455",
                },
              },
              value: {
                base: "0.54545455",
                discount: "0.00",
              },
              vat: {
                type: "VAT_RATE",
                code: "REDUCED_1",
                percentage: "10.00",
                exclusive: "0.54545455",
                inclusive: "0.60",
                amount: "0.05454545",
              },
            },
          },
        ],
        payments: [
          {
            type: "CASH",
            details: {
              amount: "25.00",
            },
          },
        ],
      },
    },
  }),
}).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",
    "record": {"id": intention["id"]},
    "operation": {
        "type": "RECEIPT",
        "document": {"number": "0001"},
        "breakdown": [
            {"type": "VAT_RATE", "code": "STANDARD", "percentage": "22.00",
                "exclusive": "20.00", "inclusive": "24.40", "amount": "4.40"},
            {"type": "VAT_RATE", "code": "REDUCED_1", "percentage": "10.00",
                "exclusive": "0.54545455", "inclusive": "0.60", "amount": "0.05454545"},
        ],
        "totals": {"vat": {"amount": "4.45454545", "exclusive": "20.54545455", "inclusive": "25.00"}},
        "entries": [
            {"type": "SALE", "details": {"concept": "GOOD"}, "data": {
                "type": "ITEM", "text": "Margherita pizza",
                "unit": {"quantity": "2.00", "price": {"inclusive": "12.20", "exclusive": "10.00"}},
                "value": {"base": "20.00", "discount": "0.00"},
                "vat": {"type": "VAT_RATE", "code": "STANDARD", "percentage": "22.00",
                    "exclusive": "20.00", "inclusive": "24.40", "amount": "4.40"}}},
            {"type": "SALE", "details": {"concept": "SERVICE"}, "data": {
                "type": "ITEM", "text": "Service ABC",
                "unit": {"quantity": "1.00", "price": {"inclusive": "0.60", "exclusive": "0.54545455"}},
                "value": {"base": "0.54545455", "discount": "0.00"},
                "vat": {"type": "VAT_RATE", "code": "REDUCED_1", "percentage": "10.00",
                    "exclusive": "0.54545455", "inclusive": "0.60", "amount": "0.05454545"}}},
        ],
        "payments": [{"type": "CASH", "details": {"amount": "25.00"}}],
    },
}}).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