Per i clienti SIGN ES

Guida all’integrazione SIGN PT per i clienti SIGN ES

Questa guida aiuta i team che hanno già integrato SIGN ES a capire come lo stesso flusso di business si applica in SIGN PT utilizzando l’approccio Unified API di fiskaly.

Da SIGN ES a SIGN PT

Se conosci già SIGN ES, molte parti del flusso ti sembreranno familiari. Allo stesso tempo, SIGN PT introduce alcune differenze importanti nella struttura degli endpoint, nella denominazione delle risorse e nel ciclo di vita delle risorse.

Panoramica comparativa

SIGN ES	SIGN PT / Unified API	Significato
Organizzazione principale	Organization::GROUP	Rappresenta l’integratore (fornitori di software o commercianti con il proprio sistema di fatturazione).
Organizzazione gestita	Organization::UNIT	Rappresenta un NIF (commerciante o contribuente).
Un contribuente per organizzazione gestita	Contribuente collegato a una o più risorse Location::BRANCH	Un contribuente può operare da diverse sedi aziendali. Location::BRANCH rappresenta le singole sedi negozio.
signer	gestito automaticamente	Il componente di firma viene gestito automaticamente nel flusso Unified API. L’integratore non ha bisogno di creare questa risorsa.
client	System::FISCAL_DEVICE	I terminali POS/fatturazione sono rappresentati come sistemi invece di oggetti client.
invoice	Record::INTENTION e Record::TRANSACTION	Fatture o ricevute vengono gestite come record, con due chiamate: INTENTION per indicare l’intenzione di emettere una ricevuta o fattura, e TRANSACTION con il contenuto finale della ricevuta o fattura.
UUID definiti dal client	UUID assegnati automaticamente più X-Idempotency-Key	Non si forniscono più UUID delle risorse direttamente; l’idempotenza protegge dai duplicati.

Prima di iniziare

📘Prerequisiti

È necessario un account fiskaly e l’accesso al fiskaly HUB. Sarà inoltre necessario uno strumento per effettuare richieste HTTP, come cURL, Postman o il proprio codice applicativo.

Se hai già integrato SIGN ES, il flusso di business ti sembrerà familiare, ma la configurazione è più esplicita in SIGN PT e utilizza il modello di risorse Unified API. Con questa integrazione, sblocchi diversi paesi con una sola integrazione.

Prima di iniziare, è utile pensare in termini di risorse da configurare:

• Organization — un GROUP per la struttura di livello superiore e una o più organizzazioni UNIT per singoli commercianti o contribuenti.
• API Key e Token — credenziali create in HUB e poi scambiate con token usati nel flusso Unified API.
• Taxpayer — una risorsa COMPANY o INDIVIDUAL che rappresenta l’entità legale che emette documenti fiscali.
• Location — una risorsa BRANCH per ogni punto vendita fisico o sito operativo.
• System — una risorsa FISCAL_DEVICE che rappresenta il POS o il dispositivo fiscale che emette documenti.
• Record — un flusso fiscale in due parti che usa INTENTION e TRANSACTION invece di creare direttamente le fatture.

Flusso di integrazione

Passo	Cosa si fa	Perché esiste
1. Registrarsi su HUB	Crea il tuo account fiskaly su HUB	Questo è il punto di ingresso per configurare la propria organizzazione e le credenziali API.
2. Creare la prima organizzazione	Crea la prima Organization::GROUP su HUB	Rappresenta il fornitore POS o il commerciante al livello superiore. Dopo questo passaggio, crea una chiave API per quell’organizzazione su HUB.
3. Creare una chiave API	Genera una chiave API e un segreto per il gruppo su HUB	Queste credenziali sono necessarie per autenticarsi e continuare la configurazione.
4. Creare un token	Chiamare createToken	Questo token viene utilizzato per le richieste API successive.
5. Creare un’organizzazione UNIT	Creare una Organization::UNIT per contribuente	Sostituisce il vecchio concetto di organizzazione gestita.
6. Creare una chiave API soggetto	Chiamare createSubject con X-Scope-Identifier	Questo collega una chiave API alla corretta Organization::UNIT.
7. Creare un token con scope	Creare un secondo token per lo scope dell’unità	Questo token viene poi usato per le risorse a livello di contribuente e le risorse operative.
8. Creare il contribuente	Creare un Taxpayer::COMPANY o Taxpayer::INDIVIDUAL	Rappresenta l’entità legale che emette i documenti fiscali.
9. Creare la sede	Creare un Location::BRANCH per ogni negozio o sito operativo	Questo rende esplicita ogni sede aziendale nel modello.
10. Creare il sistema	Creare un System::FISCAL_DEVICE e i relativi sistemi POS	Sostituisce la configurazione di signer e client.
11. Creare il record fiscale	Creare l’operazione fiscale come record	Sostituisce il flusso orientato alle fatture di SIGN ES.

Traduzione pratica

Per un’integrazione SIGN ES esistente, il modo più chiaro di tradurre il modello è:

• managed organization diventa Organization::UNIT
• taxpayer avrà una o più risorse Location::BRANCH collegate, a seconda del numero di sedi aziendali
• signer è gestito automaticamente dal flusso Unified API
• client diventa System::FISCAL_DEVICE
• invoice diventa un Record

Comportamento delle risorse

Una differenza importante rispetto a SIGN ES riguarda come le risorse operative diventano utilizzabili.

In SIGN ES, le risorse chiave sono in genere pronte all’uso immediatamente dopo la creazione.

In SIGN PT, risorse come Taxpayer, Location e System seguono un ciclo di vita:

• vengono prima create nello stato ACQUIRED
• devono poi essere aggiornate a COMMISSIONED
• solo dopo sono pronte per l’uso operativo

Ciò significa che il flusso di configurazione include un passaggio di attivazione esplicito per le risorse immediatamente utilizzabili in SIGN ES.

Stati e modalità del Record

Un Record attraversa diversi stati e modalità durante il suo ciclo di vita. Alcuni cambiamenti avvengono quando si chiama l’API, altri avvengono automaticamente mentre il sistema elabora il Record.

SIGN PT

Stati

Stato UAPI	Significato	Equivalente SIGN ES
Accepted	Il Record è stato ricevuto correttamente ed è in elaborazione	Fattura creata con successo (ISSUED) e pronta per la trasmissione — equivalente a una risposta 200 OK in SIGN ES.
Rejected	Il Record è fallito e non sarà elaborato ulteriormente	La creazione della fattura fallisce, nessuna fattura viene memorizzata — equivalente a una risposta di errore 400 o 500 in SIGN ES.
Completed	Il Record è stato elaborato con successo dall’autorità competente	Fattura accettata dall’autorità fiscale — equivalente allo stato di registrazione REGISTERED in SIGN ES.
Failed	Il Record non ha potuto essere elaborato dall’autorità competente	Fattura inviata ma rifiutata o accettata con errori dall’autorità fiscale — equivalente allo stato di registrazione REQUIRES_INSPECTION o REQUIRES_CORRECTION in SIGN ES.

Modalità

Modalità UAPI	Significato	Equivalente SIGN ES
Processing	Il Record è in elaborazione (tra la creazione e qualsiasi stato finale)	Fattura ISSUED in attesa di risposta dall’agenzia fiscale — equivalente allo stato di registrazione PENDING in SIGN ES.
Finished	L’elaborazione è completa; lo stato è ora Completed, Failed o Rejected	La fattura ha uno stato di registrazione finale: REGISTERED, REQUIRES_CORRECTING o REQUIRES_INSPECTION.