Integrazione passo dopo passo

⚠️Anteprima

SIGN ES (Unified API) è attualmente disponibile nell’ambiente di test per lo sviluppo e i test iniziali, sebbene in questa fase sia possibile testare solo un set limitato di opzioni. La produzione non è ancora attivata. Per l’uso in produzione, utilizzate l’ API Specializzata SIGN ES.

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 SIGN ES (Unified API).

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 la SIGN ES (Unified API).

   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.

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 Spagna.

   Utilizzate l’endpoint createTaxpayer per creare la rappresentazione di un contribuente come segue:

   • Impostate il contribuente come tipo Company (persona giuridica) o Individual (persona fisica).
   • Fornite il NIF (Número de Identificación Fiscal) spagnolo del contribuente.
   • Il territorio fiscale del contribuente determina se si applica Verifactu, SII o TicketBAI — consultate l’introduzione a SIGN ES per capire come queste normative si applicano ai territori spagnoli.

   Una volta creato un Taxpayer, 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 al momento della creazione del Taxpayer e condivide lo stesso UUID del Taxpayer. 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’abstrazione di ogni Sistema di Registrazione Elettronica 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.

   📘Nota sulla fatturazione

   Per la maggior parte dei contratti, i System sono le unità utilizzate per la fatturazione con fiskaly. Un System diventa rilevante ai fini della fatturazione non appena il suo stato passa da ACQUIRED a COMMISSIONED nell’ambiente LIVE. Le risorse nell’ambiente TEST non vengono fatturate. Per le condizioni di fatturazione esatte, fare riferimento al proprio contratto con fiskaly.

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 contiene i dati della transazione, che vengono poi firmati e trasmessi in base alla normativa applicabile al contribuente (Verifactu, SII o TicketBAI).

   📘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.