Smart Receipts supplier registration guide

Introduction

Before a company can issue electronic tickets (documento commerciale/scontrino elettronico) in Italy, they must be registered as a supplier in Invopop with the credentials they use on the Agenzia delle Entrate (AdE) portal, so that receipts can be relayed to the AdE on their behalf. In this guide you’ll learn how to register a supplier using the Smart Receipts Italy app. Once a supplier is registered, continue with the companion guide: Italy: Issuing receipts.

-	Sandbox	Live
Supplier	Test data accepted	Real Partita IVA and AdE credentials required

Prerequisites

To register a supplier for Smart Receipts, you will need:

An Italian tax ID (Partita IVA) for the supplier.
The supplier’s codice fiscale.
The supplier’s AdE portal credentials (password and PIN).

Setup

There are three key processes to prepare:

Create a supplier post-registration workflow.
Connect the Italian Smart Receipts app.
Configure a supplier registration workflow.

These instructions work in both sandbox and live environments. The only differences are in supplier data and registration details when using test environments.

Follow these steps in the Invopop Console.

Create Supplier post-registration workflow

Template
Code
Build from scratch

Smart Receipts supplier post-registration workflow

This workflow marks suppliers as Registered. You will select this workflow in the Italian Smart Receipts app configuration later.

Copy and paste into a new Empty Party workflow code view.

Example SDI post-registration workflow

{
  "name": "SDI supplier post-registration",
  "description": "Mark an SDI customer as registered",
  "schema": "org/party",
  "steps": [
    {
      "id": "7e8d8070-3870-11ef-af29-4533d56cea03",
      "name": "Set state",
      "config": {
        "state": "registered"
      },
      "summary": "Set state to `registered`{.state .registered}",
      "provider": "silo.state"
    }
  ],
  "rescue": []
}

Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Party workflow as the base. Then name the workflow with a descriptive label such as “Smart Receipt Post-registration”.This workflow is composed of a single step:

Set state - To Registered.

Though you can customize it to suit your needs (adding a webhook, or an email notification after a supplier has been registered.)

Connect the Italian Smart Receipts app

Navigate to Configuration → Apps.
Find Italian Smart Receipts in the app discovery list.
Click Connect to activate.

Click the Configure button on the app, and choose the “Post-registration workflow” we created in the previous step.Click the Save button.

Configure the supplier registration workflow

Template
Code
Build from scratch

Smart receipts supplier registration workflow

This workflow will issue a registration request for a supplier to complete in order to issue receipts through the AdE.

Copy and paste into a new Empty Party workflow code view.

Example Smart Receipts register supplier workflow

{
  "name": "Smart Receipts register supplier",
  "description": "Register a supplier with AdE",
  "schema": "org/party",
  "steps": [
    {
      "id": "1a1be400-2b32-11f0-984e-0542d5f28f0b",
      "name": "Sign envelope",
      "provider": "silo.close"
    },
    {
      "id": "de116bb0-25b4-11f0-864a-193f213df097",
      "name": "Register supplier with AdE",
      "provider": "ticket-it.register"
    },
    {
      "id": "e0a1b380-25b4-11f0-864a-193f213df097",
      "name": "Set state",
      "provider": "silo.state",
      "summary": "Set state to `processing`{.state .processing}",
      "config": {
        "state": "processing"
      }
    }
  ],
  "rescue": [
    {
      "id": "1deb1470-2b32-11f0-984e-0542d5f28f0b",
      "name": "Set state",
      "provider": "silo.state",
      "summary": "Set state to `error`{.state .error}",
      "config": {
        "state": "error"
      }
    }
  ]
}

Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Party workflow as the base. Then name the workflow with a descriptive label such as “Smart Receipts Register Supplier”.The new workflow will need to perform three steps:

Sign envelope
Register supplier with AdE
Set state - select Processing.

Add any additional steps you may need, and save the new workflow.

Register a supplier

You can register suppliers either manually via the Invopop Console or programmatically via the API. The process is essentially the same. We’ll demonstrate the manual process first, followed by the API flow.

Suppliers in Italy using this system must generate and provide their AdE credentials so that invoices can be processed on their behalf. This is not an automated service and can only be performed manually by a representative of the supplier.

Navigate to Parties → Suppliers in the sidebar
Click + New Supplier
In the editor, enter the supplier details

Here’s an example using test data (only valid for sandbox environments):

View supplier Data for sandbox

{
    "$schema": "https://gobl.org/draft-0/org/party",
    "uuid": "018fbeda-bc61-7000-b66d-398ce3e21c43",
    "name": "Milano Pizza",
    "tax_id": {
        "country": "IT",
        "code": "48220010093"
    },
    "identities": [
        {
            "key": "it-fiscal-code",
            "code": "MRTMTT91D08F205J"
        }
    ]
}

You may notice that we included the Italian fiscal code in the supplier, this is not necessary at the moment but will be asked for, if not provided, during the registration process.

Tap Build, ensure there are no errors, and click Save. We should now see the document. Find and click the Select Workflow button. Select the Register Supplier workflow created during setup, and click Run Workflow. The execution should be successful, and the silo entry will now be in the Processing state. Tap the Meta tab to see the registration link:

You can access the registration link via the API by fetching the silo entry and reading the meta row where the key is set to registration-link.

Tap the registration link and a new browser window will be presented with a form to upload the credentials for the supplier. Note that this form can be shared directly with the supplier if required.

The details from this form are sent securely to our local partner who will be responsible for sending them to the AdE. We will update the supplier with the provided codice fiscale for future use but will not store any type of credentials.

These credentials will expire every 90 days. You must first update your credentials on the official AdE web portal, then enter these new credentials in our registration form. You can use the same registration link to update your credentials.

At this point, you’re ready to start issuing receipts on behalf of the supplier. Head over to the Smart Receipts issuing guide to continue.

Register a supplier via the API

The whole registration process can also be completed programmatically. This is useful in white-label setups where you want to collect the supplier’s credentials inside your own product instead of sharing Invopop’s hosted form.

Upload the supplier

Use the Create an entry endpoint to upload the supplier party, like the example in the previous section. The party must include the company name and an Italian tax_id (Partita IVA). Optionally include the it-fiscal-code identity and an email address to pre-fill the registration form.

Run the registration workflow

Send the supplier to the registration workflow using the Create a job endpoint with the IDs of the silo entry and the supplier registration workflow created during setup.

Fetch the registration link

Fetch the silo entry and read the meta row where the key is registration-link. The link_url will look like this:

https://ticket-it.invopop.com/register/{owner_id}/{entry_id}?exp={expiry}&sig={signature}

The URL is signed: the exp and sig query parameters are validated on every request, so always use the link_url exactly as returned. Requests with missing or modified parameters are rejected.

Submit the credentials

Opening the link in a browser presents the hosted registration form. To submit the credentials from your own product instead, send a PUT request to the link_url (keeping the query parameters intact) with the following JSON body:

{
  "fiscal_id": "48220010093",
  "codice_fiscale": "MRTMTT91D08F205J",
  "email": "supplier@example.com",
  "password": "supplier-ade-password",
  "pin": "12345678"
}

Field	Required	Description
`fiscal_id`	Yes	The supplier’s Partita IVA, without the `IT` country prefix.
`codice_fiscale`	Yes	The supplier’s codice fiscale. It will be stored in the supplier party for future use.
`password`	Yes	The supplier’s AdE portal password.
`pin`	Yes	The supplier’s AdE portal PIN.
`email`	No	Email address to receive AdE notifications. Updates the supplier party if changed.

A 200 response means the registration is complete and the post-registration workflow configured in the app will be launched. Errors are returned as {"error": "<message>"} with a 400 status for client errors (invalid or expired link, missing fields) or 500 for server errors.The same endpoint can be called again with the same link to update the supplier’s credentials when they expire.

FAQ

How do I onboard a new supplier in Italy?

Provide the supplier’s Partita IVA and Codice Fiscale (where different) in their party configuration. No certificate upload is needed — Invopop signs and submits to SDI as the supplier’s intermediary.

How are supplier credentials stored in Invopop for Italy?

No supplier certificates are required. Invopop signs FatturaPA submissions with its own Agenzia delle Entrate-recognized intermediary credentials. Only the Partita IVA and routing metadata are stored.

How do I register a supplier with Smart Receipts?

Run the Smart Receipts Register Supplier workflow with the supplier’s Partita IVA. Invopop registers the merchant with Agenzia delle Entrate’s AdE CF service so issuance can begin immediately.

What credentials does Smart Receipts require to authenticate a supplier?

None at the supplier level. Invopop authenticates to AdE CF via its intermediary credentials. The supplier’s Partita IVA is the only routing identifier needed.

More available in our Italy FAQ section

🇮🇹 Invopop resources for Italy


Compliance	Invoicing compliance in Italy Compliance timeline
Apps	SDI Italy Smart Receipts Italy
Guides	SDI sending guide SDI receiving guide Smart Receipts supplier registration Smart Receipts issuing guide
FAQ	Italy FAQ
GOBL	Italy Tax Regime Italy SDI FatturaPA Addon Italy AdE Ticket Addon
GitHub	gobl.fatturapa

Participate in our community

Ask and answer questions about invoicing in Italy →

Networks

Countries

Set-up

GOBL

Apps

API

Features

Smart Receipts supplier registration guide

Introduction

Prerequisites

Setup

Smart Receipts supplier post-registration workflow

Smart receipts supplier registration workflow

Register a supplier

Register a supplier via the API

FAQ

Participate in our community

​Introduction

​Prerequisites

​Setup

Smart Receipts supplier post-registration workflow

Smart receipts supplier registration workflow

​Register a supplier

​Register a supplier via the API

​FAQ

Participate in our community

Introduction

Prerequisites

Setup

Register a supplier

Register a supplier via the API

FAQ