Intégration étape par étape

⚠️ Vous consultez la documentation pour la version API 2026-02-03. La dernière version est 2026-05-04. La nouvelle version de l’API n’apporte aucun changement à l’intégration italienne. Elle ajoute cependant le support SIGN PT, permettant aux équipes qui prévoient de s’étendre au Portugal de réutiliser la même intégration déjà en place pour l’Italie.

Ce guide vous accompagne tout au long du processus complet d’intégration de l’API fiskaly SIGN IT pour la conformité fiscale italienne, en utilisant une combinaison du fiskaly HUB et des requêtes API. À la fin, vous aurez un Système entièrement fonctionnel avec des Records transmis à l’Agenzia delle Entrate (AdE).

Flux d’intégration

Le diagramme ci-dessous illustre le flux de travail et met en évidence les étapes essentielles nécessaires pour compléter avec succès votre intégration. Chaque vignette pointe directement vers l’étape de configuration correspondante ci-dessous.

⚠️Important

Les étapes marquées en jaune doivent être complétées directement sur HUB, tandis que les étapes restantes doivent être gérées via l’API. Effectuer chaque action dans le bon contexte est une étape importante vers une intégration réussie.

Prérequis

📘Before you begin

Vous aurez besoin d’un outil pour effectuer des requêtes HTTP — tel que cURL (ligne de commande), Postman, ou votre propre code d’application. Une compréhension de base des API REST et des flux d’authentification est recommandée.

Vous pouvez également télécharger notre collection Postman pour SIGN IT, qui inclut des requêtes préconstruites pour chaque étape de ce guide.

Configuration étape par étape

S'inscrire sur HUB
Commencez par vous inscrire sur le fiskaly HUB.
Pour plus de conseils sur la prise en main, rendez-vous dans notre section HUB - Premiers pas.
Créer un Account et une Organization GROUP
La création d’un Account fiskaly est la première étape, après quoi vous pouvez procéder à la mise en place de la première structure organisationnelle pour votre entreprise et générer votre API Key.
L’Account représente le fournisseur PoS ou un détaillant qui gère son propre système PoS. C’est l’organisation de niveau supérieur dans la structure.
Après avoir créé votre Account fiskaly, vous serez dirigé vers le Sélecteur d’Organisation où vous pouvez créer votre Group. Un Group est un niveau intermédiaire au sein d’un Account qui vous aide à organiser plusieurs Units en clusters logiques.
Créer une API Key
L’étape suivante consiste à générer une API Key pour votre Organisation via HUB au sein de votre Group.
Vous recevrez une API Key et un secret API. Sauvegardez-les en toute sécurité — vous en aurez besoin pour vous authentifier dans l’API SIGN IT et créer vos Organisation(s) de type UNIT (étape 5). Le secret API n’est affiché qu’une seule fois. Assurez-vous de le sauvegarder en toute sécurité avant de fermer la boîte de dialogue.
💡TEST vs. LIVE environments
Les API Keys générées dans l’environnement TEST (https://test.api.fiskaly.com) créeront des ressources TEST, tandis que celles de l’environnement LIVE (https://live.api.fiskaly.com) créeront des ressources LIVE. Pour plus de détails, référez-vous à notre article sur les environnements TEST et LIVE.

Créer un Token
À partir de cette étape, vous utiliserez l’API SIGN IT.
Appelez l’endpoint createToken avec la API Key et le secret de l’étape 3 pour obtenir un token bearer. Incluez ce token dans l’en-tête Authorization des étapes 5 et 6.
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" } }'
Exemple de réponse (200 OK)
{ "content": { "id": "6f1c5c9e-3d9c-4f8c-9f20-7de8f3a91b11", "authentication": { "type": "JWT", "bearer": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_at": "2026-03-02T12:00:00Z" }, "organization": { "id": "b7b6f971-5a3c-4e1e-9f58-2f2a8457bb2d" }, "subject": { "id": "2d4a0c2a-c2c9-4e3b-a0e8-b8f7e70d6f33" } } }

Créer une Organization UNIT

Créez une Organisation de type UNIT via l’endpoint createOrganization. Une UNIT représente une seule entité juridique (commerçant). Vous devrez créer une Organisation UNIT pour chaque représentation de contribuable que vous gérez.

L’utilisation du token bearer généré à l’étape 4 avec la API Key et le secret créés pour votre Group garantit que la UNIT est correctement imbriquée sous ce Group dans la hiérarchie.

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

const response = await fetch(
  "https://test.api.fiskaly.com/organizations",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      content: {
        type: "UNIT",
        name: "My Retail Store",
      },
    }),
  }
);

const organization = await response.json();
const organizationId = organization.id;

Exemple de réponse (201 Created)

{
  "content": {
    "id": "9a746f13-0ef7-4a0f-a7df-8e52089c5f3a",
    "state": "ENABLED",
    "type": "UNIT",
    "name": "My Retail Store",
    "organization": {
      "id": "d4c7b3d1-71f6-45d6-a289-4adf5d54b9c1"
    }
  },
  "metadata": {
    "trace_identifier": "trace_abc123",
    "api_version": "2026-02-03"
  }
}

Créer un Subject (API Key)

Créez un Subject de type API_KEY pour l’Organisation UNIT via l’endpoint createSubject.

Pour associer le Subject (API Key) à votre UNIT, incluez l’en-tête X-Scope-Identifier défini sur l’id de l’Organisation UNIT dans votre requête.

curl -X POST https://test.api.fiskaly.com/subjects \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "X-Scope-Identifier: ${ORGANIZATION_ID}" \
  -d '{
    "content": {
      "type": "API_KEY",
      "name": "my-api-key-03"
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/subjects",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${accessToken}`,
      "X-Scope-Identifier": organizationId,
    },
    body: JSON.stringify({
      content: {
        type: "API_KEY",
        name: "my-api-key-03",
      },
    }),
  }
);

const subject = await response.json();
// Save the returned key and secret for the next step

Exemple de réponse (201 Created)

{
  "content": {
    "id": "2d4a0c2a-c2c9-4e3b-a0e8-b8f7e70d6f33",
    "state": "ENABLED",
    "type": "API_KEY",
    "name": "my-api-key-03",
    "credentials": {
      "api_key": "fsk_unit_abc123",
      "api_secret": "secret_only_shown_once"
    }
  },
  "metadata": {
    "trace_identifier": "trace_abc123",
    "api_version": "2026-02-03"
  }
}

Créer un Token

Créez un token en utilisant la API Key et le secret du Subject que vous venez de générer. Ce token bearer sera utilisé pour toutes les étapes suivantes afin de créer des ressources au sein de l’Organisation UNIT correspondante.

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": "subject_api_key",
      "secret": "subject_api_secret"
    }
  }'

const tokenResponse = await fetch(
  "https://test.api.fiskaly.com/tokens",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
    },
    body: JSON.stringify({
      content: {
        type: "API_KEY",
        key: "subject_api_key",
        secret: "subject_api_secret",
      },
    }),
  }
);

const { access_token: unitToken } = await tokenResponse.json();

Exemple de réponse (200 OK)

{
  "content": {
    "id": "3a5b4c61-2e8d-4a9d-9ac1-6df5a4e9138d",
    "authentication": {
      "type": "JWT",
      "bearer": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
      "expires_at": "2026-03-02T12:00:00Z"
    },
    "organization": {
      "id": "9a746f13-0ef7-4a0f-a7df-8e52089c5f3a"
    },
    "subject": {
      "id": "2d4a0c2a-c2c9-4e3b-a0e8-b8f7e70d6f33"
    }
  },
  "metadata": {
    "trace_identifier": "trace_abc123",
    "api_version": "2026-02-03"
  }
}

Créer un Taxpayer

Vous êtes maintenant prêt à créer les parties opérationnelles requises pour la fiscalisation en Italie.

Utilisez l’endpoint createTaxpayer pour ajouter les informations du Taxpayer à l’Organisation UNIT que vous avez précédemment créée :

Définissez le Taxpayer comme type COMPANY (personne morale) ou INDIVIDUAL (personne physique). Dans les deux cas, le name et l’address doivent être fournis.
Dans les informations de fiscalization italiennes, les données de contribuable suivantes doivent être fournies :
- tax_id_number : Code fiscal italien (Codice fiscale) de l’entreprise
- vat_id_number : Numéro de TVA italien (Partita IVA) de l’entreprise
- credentials : PIN, mot de passe et numéro fiscal de l’utilisateur Fisconline requis pour accéder aux services de l’AdE

curl -X POST https://test.api.fiskaly.com/taxpayers \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${UNIT_TOKEN}" \
  -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"
        }
      }
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/taxpayers",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      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",
          },
        },
      },
    }),
  }
);

const taxpayer = await response.json();
const taxpayerId = taxpayer.id;

Exemple de réponse (201 Created)

{
  "content": {
    "address": {
      "city": "Rome",
      "code": "00100",
      "country": "IT",
      "line": {
        "number": "123",
        "street": "Via Roma",
        "type": "STREET_NUMBER"
      }
    },
    "country": "Italy",
    "created_at": "2026-03-05T14:58:05.729928Z",
    "fiscalization": {
      "credentials": {
        "password": "ccf9ac1c",
        "pin": "c775e7b7",
        "tax_id_number": "RSSMRA85M01H501Z",
        "type": "FISCONLINE"
      },
      "tax_id_number": "12345678901",
      "type": "IT",
      "vat_id_number": "12345678901"
    },
    "id": "019cbe81-8721-7e27-99d9-1bb4a267ba56",
    "locations": [
      {
        "description": "Head office location.",
        "type": "HEAD_OFFICE"
      },
      {
        "description": "Branch location.",
        "type": "BRANCH"
      }
    ],
    "mode": "INACTIVE",
    "name": {
      "legal": "La Pizzeria di Mario S.r.l.",
      "trade": "La Pizzeria di Mario"
    },
    "state": "ACQUIRED",
    "type": "COMPANY",
    "updated_at": "2026-03-05T14:58:05.729928Z",
    "vat_number": "IT12345678901"
  }
}

Une fois un Taxpayer créé, son state est défini sur ACQUIRED par défaut. Pour le rendre entièrement fonctionnel, mettez à jour l’état à COMMISSIONED en utilisant l’endpoint updateTaxpayer :

curl -X PATCH "https://test.api.fiskaly.com/taxpayers/${TAXPAYER_ID}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "Authorization: Bearer ${UNIT_TOKEN}" \
  -d '{
    "content": {
      "state": "COMMISSIONED"
    }
  }'

await fetch(
  `https://test.api.fiskaly.com/taxpayers/${taxpayerId}`,
  {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      content: {
        state: "COMMISSIONED",
      },
    }),
  }
);

Exemple de réponse (200 OK)

{
  "content": {
    "address": {
      "city": "Rome",
      "code": "00100",
      "country": "IT",
      "line": {
        "number": "123",
        "street": "Via Roma",
        "type": "STREET_NUMBER"
      }
    },
    "country": "Italy",
    "created_at": "2026-03-05T14:58:05.729928Z",
    "fiscalization": {
      "credentials": {
        "password": "ccf9ac1c",
        "pin": "c775e7b7",
        "tax_id_number": "RSSMRA85M01H501Z",
        "type": "FISCONLINE"
      },
      "tax_id_number": "12345678901",
      "type": "IT",
      "vat_id_number": "12345678901"
    },
    "id": "019cbe81-8721-7e27-99d9-1bb4a267ba56",
    "locations": [
      {
        "description": "Head office location.",
        "type": "HEAD_OFFICE"
      },
      {
        "description": "Branch location.",
        "type": "BRANCH"
      }
    ],
    "mode": "OPERATIVE",
    "name": {
      "legal": "La Pizzeria di Mario S.r.l.",
      "trade": "La Pizzeria di Mario"
    },
    "state": "COMMISSIONED",
    "type": "COMPANY",
    "updated_at": "2026-03-05T15:02:41.223565Z",
    "vat_number": "IT12345678901"
  }
}

📘Note

Seuls les identifiants Fisconline sont valides pour utiliser SIGN IT lite. Le contribuable doit effectuer manuellement une première connexion au portail web de l’Agence des impôts afin de s’assurer que les identifiants fonctionnent correctement et d’accepter les conditions, termes et clauses supplémentaires prévus.

⚠️Credentials renewal required

Les identifiants Fisconline expirent tous les 90 jours sur le portail AdE, mais nous recommandons de les renouveler tous les 60 jours comme bonne pratique. Découvrez comment dans cet article : SIGN IT - Comment mettre à jour les identifiants FISCONLINE

Pour plus d’informations, veuillez consulter notre section Identifiants.

Pour un Guide commerçant détaillé sur la façon de demander des identifiants Fisconline, veuillez contacter notre équipe commerciale.

Créer un Location

Pour chaque emplacement commercial opérationnel, vous devez créer un Location de type BRANCH via l’endpoint createLocation.

curl -X POST https://test.api.fiskaly.com/locations \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${UNIT_TOKEN}" \
  -d '{
    "content": {
      "type": "BRANCH",
      "taxpayer": {
        "id": "your_taxpayer_id"
      },
      "name": "Roma Centro Branch",
      "address": {
        "line": {
          "type": "STREET_NUMBER",
          "street": "Via Roma",
          "number": "1"
        },
        "code": "00100",
        "city": "Roma",
        "country": "IT"
      }
    },
    "metadata": {
      "store_code": "STORE001"
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/locations",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      content: {
        type: "BRANCH",
        taxpayer: {
          id: taxpayerId,
        },
        name: "Roma Centro Branch",
        address: {
          street: "Via Roma 1",
          zip: "00100",
          city: "Roma",
          country_code: "IT",
        },
      },
    }),
  }
);

const location = await response.json();
const locationId = location.id;

Exemple de réponse (201 Created)

{
  "content": {
    "address": {
      "city": "Roma",
      "code": "00100",
      "country": "IT",
      "line": {
        "number": "1",
        "street": "Via Roma",
        "type": "STREET_NUMBER"
      }
    },
    "created_at": "2026-03-05T15:07:09.776328Z",
    "id": "019cbe89-d450-7501-9928-1e7d94339208",
    "mode": "INACTIVE",
    "name": "Roma Centro Branch",
    "state": "ACQUIRED",
    "systems": [
      {
        "description": "Fiscal device (SIGN IT lite).",
        "type": "FISCAL_DEVICE"
      }
    ],
    "taxpayer": {
      "id": "019cbe81-8721-7e27-99d9-1bb4a267ba56"
    },
    "type": "BRANCH",
    "updated_at": "2026-03-05T15:07:09.776328Z"
  },
  "metadata": {
    "store_code": "STORE001"
  }
}

Une fois un Location créé, son state est défini sur ACQUIRED par défaut. Mettez à jour l’état à COMMISSIONED en utilisant l’endpoint updateLocation avant de continuer.

📘Note

Si le contribuable opère depuis un seul emplacement commercial qui coïncide avec l’adresse légale, la création d’un Location::BRANCH n’est pas obligatoire. Un Location::HEAD_OFFICE est automatiquement créé lors de la création du Taxpayer et partage le même UUID que le Taxpayer. Lorsque le Taxpayer est défini sur COMMISSIONED, le Location::HEAD_OFFICE est automatiquement défini sur COMMISSIONED également.

Créer un System (FISCAL_DEVICE)

L’endpoint createSystem vous permet de créer une abstraction de chaque Système d’Enregistrement Électronique (ERS) utilisé pour les opérations fiscales. Chaque caisse enregistreuse ou point de vente doit être fourni comme un nouveau System de type FISCAL_DEVICE.

Un System sera connecté à un Location spécifique précédemment créé.
Pour chaque System, vous devez fournir des informations sur le producer et le software pour suivre quel appareil effectue les transactions fiscales. Pour plus d’informations, consultez cet article FAQ.

curl -X POST https://test.api.fiskaly.com/systems \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${UNIT_TOKEN}" \
  -d '{
    "content": {
      "type": "FISCAL_DEVICE",
      "location": {
        "id": "your_location_id"
      },
      "producer": {
        "type": "MPN",
        "number": "FD-001",
        "details": {
          "name": "My Fiscal Device"
        }
      },
      "software": {
        "name": "My POS Software",
        "version": "1.0.0"
      }
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/systems",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      content: {
        type: "FISCAL_DEVICE",
        location: {
          id: locationId,
        },
        producer: {
          type: "MPN",
          number: "FD-001",
          details: {
            name: "My Fiscal Device",
          },
        },
        software: {
          name: "My POS Software",
          version: "1.0.0",
        },
      },
    }),
  }
);

const system = await response.json();
const systemId = system.id;

Exemple de réponse (201 Created)

{
  "content": {
    "compliance": {
      "software": {
        "name": "My POS Software",
        "version": "1.0.0"
      }
    },
    "created_at": "2026-03-05T13:57:00.016909Z",
    "id": "019cbe49-97f0-7dde-adae-e10fea9d64c9",
    "journal": {
      "cryptography": {
        "certificate": {
          "expires_at": "2029-03-05T13:57:00Z",
          "serial_number": "7E7D991D5D1768AF224A754A3E815537",
          "x509_pem": "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIQfn2ZHV0XaK8iSnVKPoFVNzANBgkqhkiG9w0BAQsFADAT\nMREwDwYDVQQKEwhmaXNrYWx5LjAeFw0yNjAzMDUxMzU3MDBaFw0yOTAzMDUxMzU3\nMDBaMBMxETAPBgNVBAoTCGZpc2thbHkuMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A\nMIIBCgKCAQEAzE++CjP6UrE9d4ftaRU50yWWycU1/ql5iLgpFjjBZdXAuay82ely\n11sMfjlL3RJaIkIF8w9VcrnaCnSJLzSihEPcohFF8B9iX+/GLHA9FNHMpRrNBaC/\nMmXv7iuPkOFZDTxueWtkti0BqEE+H3RoCsOkPxzMMQ0UYCtZx9V5i/bXO+Akb8HC\nuq80+73m/DP1WFQgD6d/vwfqr+eM4jZTUiRPyy9W6yBOj02SbFL6Oeop2yDNo7Ws\nhZLoquNgVe9lEHZV2N62AVe1OEXdDzn2BlNvCnlwb9RJCGTVCMQbOsN84EMhpwOG\nsRNHgezSeGhO7aca+/igmiuSW7Uw3YdWWwIDAQABo0IwQDAOBgNVHQ8BAf8EBAMC\nAoQwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUn+BqmtpyTeC4wdZNEMYf96hV\ny78wDQYJKoZIhvcNAQELBQADggEBACXaL/EXGW4PnjC+Dj5ZUySE5vtysPUV0Tkw\n4+EtLJUs86itNZgyhQpXfwzvpgj/wL7XA+GAnPqpUbrMOXLawsWGtID8BZHrQRRJ\ny/ZcHRQyIwoHNNl5bbDDNC/icG78GhK+RmdCw3wcVyxABBzpE/CckNn4hltsCqUo\n01eqms+SmY+MBUBj3ec1iVcD0bz/pyMmIQSVfWjKWtHofwUTCkgEm9cKqtyfajzB\ne6bKoScTziojhlCtnEfPb20vtQ+UE183FOG36WfuRV8EtS+3Cgx83yEj8QXVuYcA\nKQAgoPy6/6xHMDkZH3P/XTOfBf8UkZvQy5egibgC6k2wqjxYWtY=\n-----END CERTIFICATE-----\n"
        },
        "signature": {
          "hash": "SHA-256",
          "type": "RSA"
        }
      }
    },
    "kind": "INTERNAL",
    "location": {
      "id": "019cbe89-d450-7501-9928-1e7d94339208"
    },
    "mode": "INACTIVE",
    "producer": {
      "details": {
        "name": "My Fiscal Device"
      },
      "number": "FD-001",
      "type": "MPN"
    },
    "records": [
      {
        "description": "Intention of an upcoming transaction.",
        "type": "INTENTION::TRANSACTION"
      },
      {
        "description": "Receipt transaction information.",
        "type": "TRANSACTION::RECEIPT"
      },
      {
        "description": "Correction of an issued transaction.",
        "type": "TRANSACTION::CORRECTION"
      },
      {
        "description": "Cancellation of an issued transaction.",
        "type": "TRANSACTION::CANCELLATION"
      }
    ],
    "software": {
      "name": "SIGN IT Lite",
      "version": "v1.0.0"
    },
    "state": "ACQUIRED",
    "type": "FISCAL_DEVICE",
    "updated_at": "2026-03-05T13:57:00.016909Z",
    "vat_exemptions": [
      {
        "code": "NOT_SUBJECT",
        "description": "Not subject (Non soggette)"
      },
      {
        "code": "NOT_TAXABLE",
        "description": "Not taxable (Non imponibili)"
      },
      {
        "code": "CAUSE_1",
        "description": "Exempt (Esenti)"
      },
      {
        "code": "CAUSE_2",
        "description": "Exclusive Art. 15"
      },
      {
        "code": "CAUSE_3",
        "description": "Marginal scheme (Regime del margine)"
      },
      {
        "code": "CAUSE_4",
        "description": "Other (Altre non IVA)"
      }
    ],
    "vat_rates": [
      {
        "code": "STANDARD",
        "description": "Standard VAT rate",
        "historic": false,
        "percentage": "22"
      },
      {
        "code": "REDUCED_1",
        "description": "Reduced VAT rate 1",
        "historic": false,
        "percentage": "10"
      },
      {
        "code": "REDUCED_2",
        "description": "Reduced VAT rate 2",
        "historic": false,
        "percentage": "5"
      },
      {
        "code": "REDUCED_3",
        "description": "Super-reduced VAT rate",
        "historic": false,
        "percentage": "4"
      }
    ]
  }
}

Une fois un System créé, son state est défini sur ACQUIRED par défaut. Pour créer des Records, son état doit être mis à jour à COMMISSIONED en utilisant l’endpoint updateSystem.

Créer un Record

Pour chaque opération commerciale effectuée dans le Système, l’endpoint createRecord doit être utilisé en deux appels successifs :

Partie A) INTENTION : enregistre l’intention de démarrer une TRANSACTION
Partie B) TRANSACTION : fournit les données de la transaction

Partie A) Créer l’Intention

Un Record de type INTENTION contient l’association avec le System qui effectuera la transaction et une Operation de type TRANSACTION, représentant l’intention du System d’enregistrer une transaction.

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

const intentionResponse = await fetch(
  "https://test.api.fiskaly.com/records",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      content: {
        type: "INTENTION",
        system: {
          id: systemId,
        },
        operation: {
          type: "TRANSACTION",
        },
      },
    }),
  }
);

const intention = await intentionResponse.json();
const intentionId = intention.id;

Exemple de réponse (201 Created)

{
  "content": {
    "file": {
      "location": "SERVICE"
    },
    "id": "019cbe96-8e57-7693-a4ef-4ed89a76ef9b",
    "journal": {
      "signature": "yrrXNoHGF0YYPVgUWH81tXQYCf6H3BCjTed6YUT2ZvmmRaq8qoZAUOaP8wJI4ipN",
      "signed_at": "2026-03-05T15:21:03.84326335Z"
    },
    "mode": "PROCESSING",
    "operation": "{\"type\":\"TRANSACTION\"}",
    "state": "ACCEPTED",
    "system": {
      "id": "019cbe96-7245-7b49-91d6-ba66a235fc72"
    },
    "type": "INTENTION::TRANSACTION"
  }
}

Partie B) Créer la Transaction

Un Record de type TRANSACTION est associé à l’INTENTION précédemment créée et peut effectuer l’une des opérations suivantes :

RECEIPT : Représente la vente d’un bien ou service, incluant les informations sur le document (par ex. numéro de document, montants totaux TVA incluse et TVA exclue) et les lignes (identification d’une SALE, description, si c’est un GOOD ou SERVICE, etc.).
CORRECTION : Représente un processus de retour. Contient les mêmes données qu’une opération RECEIPT, plus un id de référence au document RECEIPT original.
CANCELLATION : Utilisé pour invalider une transaction entière. Nécessite l’id d’un enregistrement précédemment créé.

curl -X POST https://test.api.fiskaly.com/records \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer ${UNIT_TOKEN}" \
  -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"
            }
          }
        ]
      }
    }
  }'

const transactionResponse = await fetch(
  "https://test.api.fiskaly.com/records",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "Authorization": `Bearer ${unitToken}`,
    },
    body: JSON.stringify({
      content: {
        type: "TRANSACTION",
        intention: {
          id: intentionId,
        },
        operation: {
          type: "RECEIPT",
          document: {
            number: 1,
            date: "2026-02-03",
            total: {
              amount_incl_vat: "12.20",
              amount_excl_vat: "10.00",
            },
          },
          entries: [
            {
              type: "SALE",
              description: "Margherita Pizza",
              category: "GOOD",
              quantity: 1,
              unit_price: "10.00",
              vat_rate: "22.00",
              amount_incl_vat: "12.20",
            },
          ],
        },
      },
    }),
  }
);

const transaction = await transactionResponse.json();

Exemple de réponse (201 Created)

{
  "content": {
    "compliance": {
      "data": "DCW0000/0000-0000",
      "url": "https://ivaservizi.agenziaentrate.gov.it/ser/api/documenti/v1/doc/documenti/00000000/stampa/"
    },
    "file": {
      "location": "SERVICE"
    },
    "id": "019cbea1-4775-7b70-9b83-79cac7107266",
    "journal": {
      "record": {
        "id": "019cbe96-8e57-7693-a4ef-4ed89a76ef9b"
      },
      "signature": "vGQtUR29rogalpYCVIJPnu-3gPLScA5wEEyxrllfviUGvoK2lkLj5bw3OimfvzuP",
      "signed_at": "2026-03-05T15:32:46.594042649Z"
    },
    "mode": "FINISHED",
    "operation": "{\"document\":{\"number\":\"1\",\"total_vat\":{\"amount\":\"2.20\",\"exclusive\":\"10.00\",\"inclusive\":\"12.20\"}},\"entries\":[{\"data\":{\"text\":\"Margherita Pizza\",\"type\":\"ITEM\",\"unit\":{\"price\":\"12.20\",\"quantity\":\"1\"},\"value\":{\"base\":\"10.00\",\"discount\":\"0.00\"},\"vat\":{\"amount\":\"2.20\",\"code\":\"STANDARD\",\"exclusive\":\"10.00\",\"inclusive\":\"12.20\",\"percentage\":\"22.00\",\"type\":\"VAT_RATE\"}},\"details\":{\"concept\":\"GOOD\",\"purpose\":\"STANDARD\"},\"type\":\"SALE\"}],\"payments\":[{\"details\":{\"amount\":\"12.20\"},\"type\":\"CASH\"}],\"type\":\"RECEIPT\"}",
    "record": {
      "id": "019cbe96-8e57-7693-a4ef-4ed89a76ef9b"
    },
    "state": "COMPLETED",
    "system": {
      "id": "019cbe49-97f0-7dde-adae-e10fea9d64c9"
    },
    "transmission": {
      "request": {
        "data": "e30A",
        "type": "application/json"
      },
      "response": {
        "data": "e30A",
        "type": "application/json"
      }
    },
    "type": "TRANSACTION::RECEIPT"
  }
}

Une fois la transaction correctement enregistrée et les informations du document commercial transmises avec succès au portail web de l’AdE (état COMPLETED, mode FINISHED), le compliance.data retourné dans la réponse API inclut le numéro progressif attribué par l’AdE au document commercial (numéro DCW) et, si fourni, le code Loterie du consommateur.

Remarque : Si un état REJECTED ou FAILED est retourné à la place, veuillez consulter notre section États et modes des Records pour plus de conseils.

📘Note

Tous les enregistrements créés dans l’environnement LIVE sont transmis aux Autorités Fiscales et génèrent des documents commerciaux valides. Par conséquent, ces documents doivent toujours refléter des transactions réelles.

Prochaines étapes

Référence API SIGN IT

Documentation API complète pour l'endpoint SIGN IT — toutes les ressources, paramètres et réponses.

Gestion de la perte de connexion

Apprenez à gérer les scénarios de perte de connexion et à assurer la conformité fiscale lors des pannes.

Glossaire

Termes clés et définitions pour le système de conformité fiscale italienne.

Guide HUB

Apprenez à gérer les organisations, les API Keys et les ressources via fiskaly HUB.

Was this page helpful?

Intégration étape par étape

Flux d’intégration

Prérequis

Configuration étape par étape

S'inscrire sur HUB

Créer un Account et une Organization GROUP

Créer une API Key

Créer un Token

Créer une Organization UNIT

Créer un Subject (API Key)

Créer un Token

Créer un Taxpayer

Créer un Location

Créer un System (FISCAL_DEVICE)

Créer un Record

Prochaines étapes

Référence API SIGN IT

Gestion de la perte de connexion

Glossaire

Guide HUB