Italy Quickstart

This quickstart covers the essential steps to get started with the SIGN IT API, from authentication to creating your first fiscal record. For a more detailed walkthrough, refer to our integration guide.

We prepared a Postman collection that allows you to step through the most important functions of this API. You can download it by following these instructions.

Prerequisites

• A fiskaly account (sign up at hub.fiskaly.com)
• An API Key and Secret for an Organization GROUP in the TEST environment
• Fisconline credentials for the taxpayer (real credentials required in LIVE only)

⚠️Store credentials securely

Your API Secret is shown only once. Store it immediately in a secure location.

Steps

1. Authenticate

   cURLJavaScriptPythonJavaC#

   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 and SIGN FR share a unified API platform. All requests require the X-Api-Version header. Write operations also need an X-Idempotency-Key header with a UUIDv3 or a UUIDv4 value.

2. Create an Organization UNIT

   cURLJavaScriptPythonJavaC#

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

3. Create a Subject API Key and authenticate

   Create an API key for the UNIT, then authenticate with it:

   cURLJavaScriptPythonJavaC#

   # Create Subject API Key (scoped to the `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"}}'
   
   # Authenticate with the new API Key
   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

4. Create Taxpayer, Location, and System

   cURLJavaScriptPythonJavaC#

   # Create Taxpayer
   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"
           }
         }
       }
     }'
   
   # Commission Taxpayer
   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

   💡Create Taxpayer first

   After, create one or several Locations (type: "BRANCH") and one or several Systems (type: "FISCAL_DEVICE"). Then update their state to COMMISSIONED to activate them. See the full integration guide for the complete sequence.

   ⚠️Billing warning

   Billing begins as soon as a System is commissioned in the LIVE environment — at which point it will also start transmitting official invoices to the financial authorities.

   No billing or real transmissions take place in the TEST environment.

5. Create your first Record

   Records require two calls: an INTENTION followed by a TRANSACTION.

   cURLJavaScriptPythonJavaC#

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

   If the record reaches COMPLETED state with FINISHED mode, the commercial document has been transmitted to AdE.

Run the Script

Want to run through all the steps automatically? Download and run our quickstart script:

BashNode.js

# Download and run
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

# Download and run
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

Next Steps

Full Integration Guide

Complete step-by-step walkthrough with all 11 steps

Receipt Compliance

Italian B2C receipt requirements

Credentials

How to obtain Fisconline credentials