Integrazione passo dopo passo

📘Note

Se avete già integrato SIGN IT o SIGN FR, i passaggi di configurazione iniziali di questa guida vi saranno probabilmente familiari e potrebbero già essere completati. In tal caso, potete passare direttamente al Passaggio 10 per esaminare i passaggi aggiuntivi richiesti.

Per iniziare il processo di integrazione, consultate le istruzioni dettagliate passo dopo passo fornite qui.

Il diagramma allegato illustra il flusso di lavoro e mette in evidenza i passaggi essenziali necessari per completare con successo la vostra integrazione, per i quali dovrete utilizzare la nostra API SIGN PT.

1. Registrarsi su HUB

   Iniziate registrandovi sul fiskaly HUB. Per ulteriori indicazioni su come iniziare, consultate la nostra sezione HUB - Primi passi.

   
2. Creare Account e Organizzazione GROUP

   Creare un Account fiskaly è il primo passo, dopodiché è possibile procedere con la configurazione della prima struttura organizzativa per la propria azienda e generare la Chiave API.

   L’Account rappresenta il fornitore di POS o un rivenditore che gestisce il proprio sistema POS. È l’organizzazione di livello superiore nella struttura.

   Dopo aver creato l’Account fiskaly, si accederà al Selettore di Organizzazione dove è possibile creare il proprio Gruppo.

   Un Gruppo è un livello intermedio all’interno di un Account che aiuta a organizzare più Unit in cluster logici.

3. Creare una Chiave API

   Il passo successivo consiste nel generare una Chiave API per la propria organizzazione tramite il HUB. Questa coppia Chiave API e Segreto è necessaria per creare la prima Organizzazione di tipo UNIT (Passo 5).

   💡Ambienti TEST vs. LIVE

   Le Chiavi API generate nell’ambiente TEST (https://test.api.fiskaly.com) creeranno risorse TEST, mentre quelle dell’ambiente LIVE (https://live.api.fiskaly.com) creeranno risorse LIVE.

1. Creare un Token

   A partire da questo passaggio, utilizzerete l’API SIGN PT.

   Chiamate l’endpoint createToken con la Chiave API e il Segreto del passo 3 per ottenere un token bearer. Includete questo token nell’intestazione Authorization dei passi 5 e 6.

   I token sono JWT di breve durata che autenticano ogni chiamata SIGN PT successiva. Vengono ottenuti per ambito di Account o Organizzazione.

2. Creare un'Organizzazione UNIT

   Create un’Organizzazione di tipo UNIT tramite l’endpoint createOrganization. Una UNIT rappresenta una singola entità legale (commerciante). Dovrete creare un’Organizzazione UNIT per ogni rappresentazione di contribuente che gestite.

   L’utilizzo del token bearer generato nel Passo 4 con la Chiave API e il Segreto creati per il vostro Gruppo garantisce che la UNIT sia correttamente nidificata sotto quel Gruppo nella gerarchia.

3. Creare un Subject (Chiave API)

   Create un Subject di tipo API_KEY per l’Organizzazione UNIT tramite l’endpoint createSubject.

   Per associare il Subject (Chiave API) alla vostra UNIT, includete l’intestazione X-Scope-Identifier con l’id dell’Organizzazione UNIT nella vostra richiesta.

4. Creare un nuovo Token

   Create un token usando la Chiave API Subject e il Segreto appena generati. Questo token bearer verrà utilizzato per tutti i passaggi successivi per creare risorse all’interno dell’Organizzazione UNIT corrispondente.

1. Creare un Contribuente

   Ora siete pronti per iniziare a creare le parti operative necessarie per la fiscalizzazione in Portogallo.

   Utilizzate l’endpoint createTaxpayer dell’API SIGN PT per creare la rappresentazione di un contribuente come segue:

   • Impostate il contribuente come tipo Company (persona giuridica) o Individual (persona fisica). In entrambi i casi, devono essere forniti il nome e l’indirizzo.
   • All’interno delle informazioni di fiscalizzazione portoghese, devono essere forniti almeno i seguenti dati del contribuente:
     • tax_id_number: il NIF (Número de Identificação Fiscal) portoghese del contribuente. 9 cifre, senza spazi o separatori (ad es. 501234567).
     • credentials: le credenziali dell’utente secondario AT che SIGN PT utilizzerà per chiamare i servizi web AT per conto di questo contribuente:
       • Nome utente: l’identificatore dell’utente secondario nel formato <NIF>/<subuser-id> (ad es. 501234567/5), come emesso dal Portal das Finanças.
       • Password: la password impostata per quell’utente secondario.

   Queste non sono le credenziali principali del Portal das Finanças del commerciante. Devono essere un utente secondario dedicato creato appositamente per l’accesso al servizio web — vedere la nota Importante di seguito.

   ⚠️Importante

   L’utilizzo dei Servizi Web AT tramite SIGN PT richiede una configurazione preventiva sul Portal das Finanças da parte del contribuente o del suo rappresentante legale: deve essere creato un utente secondario dedicato al Servizio Web, devono essere concesse le autorizzazioni richieste (ad es. WSE, WFA, WDT) e devono essere accettati i termini e le condizioni AT applicabili.

   Per istruzioni passo dopo passo sulla creazione dell’utente secondario, consultate Creazione dell’utente secondario sul Portal das Finanças.

   Una volta creato un Taxpayer, sia di tipo Company che Individual, il suo stato viene impostato su ACQUIRED per impostazione predefinita. Per renderlo completamente funzionante, aggiornate lo stato a COMMISSIONED utilizzando l’endpoint updateTaxpayer.

2. Creare una Sede

   📘Note

   Una sede HEAD_OFFICE viene creata automaticamente insieme al contribuente. Tuttavia, ai fini della fiscalizzazione, si consiglia di creare una sede separata di tipo BRANCH (può avere lo stesso indirizzo). Se ci sono più sedi, deve essere creata una filiale corrispondente per ciascuna.

   Per ogni sede commerciale operativa, create una Sede di tipo BRANCH tramite l’endpoint createLocation.

   Una volta creata una Sede, il suo stato viene impostato su ACQUIRED per impostazione predefinita. Aggiornate lo stato a COMMISSIONED utilizzando l’endpoint updateLocation prima di procedere.

3. Creare un Sistema

   L’endpoint createSystem consente di creare un’astrazione di ogni Sistema di Registrazione Elettronica (ERS) utilizzato per le operazioni fiscali. Ogni registratore di cassa o punto vendita deve essere fornito come nuovo Sistema di tipo FISCAL_DEVICE.

   • Un Sistema sarà collegato a una Sede specifica di tipo BRANCH, creata in precedenza.

   Una volta creato un Sistema, il suo stato viene impostato su ACQUIRED per impostazione predefinita. Per creare Record, il suo stato deve essere aggiornato a COMMISSIONED utilizzando l’endpoint updateSystem.

4. Creare un Record

   Per ogni operazione commerciale effettuata nel Sistema, l’endpoint createRecord deve essere chiamato due volte in sequenza: prima per registrare l’intenzione di avviare una transazione, e poi per fornire i dati della transazione.

   Parte A) Intention

   Un Record di tipo INTENTION contiene l’associazione con il Sistema che effettuerà la transazione e un’Operazione di tipo TRANSACTION, che rappresenta l’intenzione del Sistema di registrare una transazione.

   Parte B) Transaction

   Un Record di tipo TRANSACTION è associato all’INTENTION creata in precedenza e può eseguire una delle seguenti operazioni:

   • INVOICE/RECEIPT: Rappresenta la vendita di un bene o servizio, inclusi i dettagli del documento (numero del documento, codice attività, data della transazione, importi totali IVA inclusa ed esclusa) e le righe degli articoli (ogni riga ha un entries[].type come SALE, descrizione, se si tratta di un GOOD o SERVICE, ecc.).
   • CORRECTION: Emette un documento correttivo (NC per credito / ND per debito) con riferimento a un INVOICE/RECEIPT creato in precedenza. Contiene le righe corrette e un reference_id al documento originale.
   • CANCELLATION: Utilizzato per invalidare un’intera transazione. Richiede l’id di un record creato in precedenza.

   Dopo la sottomissione del Record TRANSACTION, SIGN PT esegue le fasi di emissione conformi per l’operazione selezionata: assegna il prossimo numero sequenziale della serie (i numeri non vengono pre-assegnati), firma e concatena il documento e genera i dati necessari per la rappresentazione finale orientata al cliente.

   A seconda della configurazione di comunicazione del Contribuente, gli stessi dati della transazione vengono quindi:

   • inclusi nella comunicazione/esportazione SAF-T (PT) (per invio mensile), e/o
   • comunicati ad AT tramite servizi web (ad es., fatture tramite WFA; documenti di trasporto tramite WDT, se applicabile e se le autorizzazioni sono state concesse).

   Una volta completata l’elaborazione, SIGN PT restituisce (tramite la risposta del Record e/o gli artefatti recuperabili del Record):

   • il payload di conformità richiesto per la stampa (ad es., ATCUD, contenuto del codice QR, l’estratto hash e il numero di certificato del software)
   • i dati del documento firmato/concatenato necessari per costruire la rappresentazione finale della ricevuta/fattura, e
   • le informazioni sullo stato di elaborazione del Record (successo/fallimento e dettagli degli errori rilevanti).

   📘Note

   Tutti i Record creati nell’ambiente LIVE rappresentano documenti fiscalmente rilevanti e devono sempre riflettere transazioni reali. Utilizzate l’ambiente TEST designato per i test di integrazione.