Integrazione passo dopo passo

Per avviare 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 l’integrazione.

Per l’integrazione, dovrete utilizzare il fiskaly HUB, la Management API e la SIGN AT API.

Prima di iniziare la configurazione, ecco cosa configurerete:

🏢

Organizzazione

La vostra entità di livello superiore in fiskaly. Le organizzazioni gestite rappresentano singoli commercianti.

🔑

Chiave API e Secret

Credenziali generate in HUB, utilizzate per autenticare tutte le successive richieste all'API SIGN AT.

🇦🇹

Autenticazione FON

Credenziali FinanzOnline fornite dal contribuente per abilitare la sincronizzazione con l'autorità fiscale austriaca.

🛡️

SCU (Signature Creation Unit)

Il componente centrale di firma. Una SCU per organizzazione gestita gestisce la firma crittografica delle ricevute.

💻

Registratore di cassa

Rappresenta un registratore di cassa fisico o virtuale. Deve essere registrato presso FinanzOnline e inizializzato.

🧾

Ricevuta

Un documento fiscale firmato conforme alla RKSV contenente i dati del codice QR e i metadati della ricevuta.

Prerequisiti

📘Prima di iniziare

È necessario disporre di un account fiskaly e dell’accesso al fiskaly HUB. Se non avete ancora un account, registratevi qui.

Sarà necessario anche uno strumento per effettuare richieste HTTP — ad esempio cURL (riga di comando), Postman o il codice della propria applicazione. Potete scaricare la nostra raccolta Postman, che può facilitare l’integrazione.

Flusso di lavoro dell’integrazione

Il diagramma seguente illustra il flusso di lavoro e mette in evidenza i passaggi essenziali necessari per completare con successo l’integrazione. Ogni riquadro rimanda direttamente al corrispondente passaggio di configurazione qui sotto.

Configurazione passo dopo passo

1. Registrarsi nel Dashboard

   Iniziate registrandovi nel fiskaly HUB. La creazione di un account è il primo passo, dopodiché potrete procedere con la configurazione della struttura organizzativa della vostra azienda nel nostro sistema.

   💡Iniziate rapidamente

   HUB offre un flusso di onboarding guidato che vi accompagna attraverso la creazione dell’account e la configurazione iniziale.

2. Creare la prima organizzazione

   Procedete con la creazione della vostra prima organizzazione tramite HUB. Questa organizzazione rappresenterà il fornitore POS o il commerciante con il proprio sistema POS. È necessario includere l’indirizzo di fatturazione in questa fase. Questo indirizzo sarà utilizzato esclusivamente per i fini di fatturazione di fiskaly.

   💡Non siete ancora pronti per la produzione?

   Per scopi di test, non è necessario compilare tutti i campi. Potete lasciare l’indirizzo di fatturazione vuoto e completarlo in seguito.

3. Creare organizzazioni gestite

   Dopo aver stabilito la prima organizzazione, procederete alla creazione di organizzazioni gestite. Ogni organizzazione gestita rappresenta un commerciante, consentendovi di gestirli separatamente. Se state pensando di automatizzare il vostro processo, vi consigliamo di utilizzare l’endpoint createOrganization della Management API.

   💡Automatizzate su larga scala

   Se gestite molti commercianti, utilizzate la Management API per creare organizzazioni gestite in modo programmatico invece di farlo manualmente tramite HUB.

4. Creare una chiave API

   Il passo successivo consiste nel generare una chiave API all’interno di ciascuna organizzazione gestita. Questo può essere fatto tramite HUB o l’endpoint createApiKey della Management API. Questa coppia di chiave API e secret è necessaria per generare un token di accesso, utilizzato per tutte le successive chiamate API.

   ⚠️Conservate le credenziali in modo sicuro

   L’API Secret viene mostrato una sola volta. Assicuratevi di copiarlo e conservarlo in un luogo sicuro prima di chiudere la finestra di dialogo.

   📘TEST vs. LIVE

   Le chiavi API generate nell’ambiente TEST creeranno risorse TEST, mentre quelle dell’ambiente LIVE creeranno risorse LIVE. Per ulteriori dettagli, consultate il nostro articolo sugli ambienti TEST e LIVE.

   A partire dal passo successivo, utilizzerete la SIGN AT API.

   Autenticarsi con l’API

   Utilizzate la vostra chiave API e il secret per ottenere un token di accesso. Questo token è necessario per tutte le successive richieste.

   cURLJavaScript

   curl -X POST https://rksv.fiskaly.com/api/v1/auth \
     -H "Content-Type: application/json" \
     -d '{
       "api_key": "your_api_key",
       "api_secret": "your_api_secret"
     }'

   const response = await fetch(
     "https://rksv.fiskaly.com/api/v1/auth",
     {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         api_key: "your_api_key",
         api_secret: "your_api_secret",
       }),
     }
   );
   
   const { access_token } = await response.json();

   La risposta contiene un access_token che dovete includere come token Bearer nell’intestazione Authorization di tutte le richieste successive.

5. Autenticare FON

   Dopo l’autenticazione con la coppia di chiave API e secret generata in precedenza, è necessario chiamare l’endpoint authenticateFon una volta per contribuente.

   Per abilitare la sincronizzazione con FinanzOnline, il contribuente deve prima creare l‘“Utente del Servizio Web Registratore di Cassa” direttamente in FinanzOnline e fornirvi le credenziali di questo utente.

   📘Le credenziali FON sono separate

   Le credenziali non corrispondono alle credenziali generali di FinanzOnline. Corrispondono alle credenziali dell’Utente del Servizio Web Registratore di Cassa dedicato creato dal contribuente.

   cURLJavaScript

   curl -X POST https://rksv.fiskaly.com/api/v1/fon/auth \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "fon_participant_id": "your_fon_participant_id",
       "fon_user_id": "your_fon_user_id",
       "fon_user_pin": "your_fon_user_pin"
     }'

   const fonResponse = await fetch(
     "https://rksv.fiskaly.com/api/v1/fon/auth",
     {
       method: "POST",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         fon_participant_id: "your_fon_participant_id",
         fon_user_id: "your_fon_user_id",
         fon_user_pin: "your_fon_user_pin",
       }),
     }
   );

6. Creare la SCU

   Procedete con la creazione di una SCU tramite l’endpoint createSignatureCreationUnit. Per ogni organizzazione gestita, è necessario creare una sola SCU. Una volta creata, lo stato di una SCU sarà CREATED.

   cURLJavaScript

   SCU_ID=$(uuidgen)
   
   curl -X PUT "https://rksv.fiskaly.com/api/v1/signature-creation-unit/${SCU_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "legal_entity_id": {
         "vat_id": "ATU12345678"
       }
     }'

   const scuId = crypto.randomUUID();
   
   const scuResponse = await fetch(
     `https://rksv.fiskaly.com/api/v1/signature-creation-unit/${scuId}`,
     {
       method: "PUT",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         legal_entity_id: {
           vat_id: "ATU12345678",
         },
       }),
     }
   );

   📘Note

   Sostituite ATU12345678 con il numero di partita IVA effettivo del contribuente.
7. Creare il/i registratore/i di cassa

   Procedete con la creazione di almeno un registratore di cassa tramite l’endpoint createCashRegister. Il numero di registratori di cassa deve corrispondere al numero di registratori di cassa utilizzati in un determinato negozio o punto vendita. La creazione di un registratore di cassa imposta lo stato su CREATED.

   cURLJavaScript

   CASH_REGISTER_ID=$(uuidgen)
   
   curl -X PUT "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "description": "Main POS Terminal"
     }'

   const cashRegisterId = crypto.randomUUID();
   
   const crResponse = await fetch(
     `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
     {
       method: "PUT",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         description: "Main POS Terminal",
       }),
     }
   );

8. Aggiornare la SCU a INITIALIZED

   Per la firma delle ricevute, sia la SCU che il/i registratore/i di cassa devono essere aggiornati a INITIALIZED. Chiamate l’endpoint updateSignatureCreationUnit e transizionate allo stato INITIALIZED. Questa transizione di stato registra automaticamente la SCU nel portale FinanzOnline.

   cURLJavaScript

   curl -X PATCH "https://rksv.fiskaly.com/api/v1/signature-creation-unit/${SCU_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "state": "INITIALIZED"
     }'

   await fetch(
     `https://rksv.fiskaly.com/api/v1/signature-creation-unit/${scuId}`,
     {
       method: "PATCH",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         state: "INITIALIZED",
       }),
     }
   );

9. Aggiornare il/i registratore/i di cassa

   A differenza dell’aggiornamento della SCU, il/i registratore/i di cassa deve/devono essere aggiornato/i due volte tramite updateCashRegister:

   a) Registrare il registratore di cassa

   Prima, cambiate lo stato del registratore di cassa a REGISTERED. Questa transizione di stato registra automaticamente il registratore di cassa nel portale FinanzOnline.

   cURLJavaScript

   curl -X PATCH "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "state": "REGISTERED"
     }'

   await fetch(
     `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
     {
       method: "PATCH",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         state: "REGISTERED",
       }),
     }
   );

   b) Inizializzare il registratore di cassa

   Poi, in una seconda chiamata, cambiate lo stato a INITIALIZED. Questa transizione di stato innesca la creazione e la validazione della ricevuta iniziale nel portale FinanzOnline.

   cURLJavaScript

   curl -X PATCH "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "state": "INITIALIZED"
     }'

   await fetch(
     `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
     {
       method: "PATCH",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         state: "INITIALIZED",
       }),
     }
   );

   Sia la SCU che il registratore di cassa sono ora pronti per firmare le ricevute.

10. Firmare le ricevute

    Con tutti i passaggi precedenti completati, siete ora pronti per firmare le ricevute tramite l’endpoint signReceipt.

    cURLJavaScript

    RECEIPT_ID=$(uuidgen)
    
    curl -X PUT "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}/receipt/${RECEIPT_ID}" \
      -H "Authorization: Bearer ${ACCESS_TOKEN}" \
      -H "Content-Type: application/json" \
      -d '{
        "receipt_type": "NORMAL",
        "schema": {
          "standard_v1": {
            "receipt": {
              "amounts_per_vat_rate": [
                {
                  "vat_rate": "STANDARD",
                  "amount": "12.00"
                }
              ],
              "amounts_per_payment_type": [
                {
                  "payment_type": "CASH",
                  "amount": "12.00"
                }
              ]
            }
          }
        }
      }'

    const receiptId = crypto.randomUUID();
    
    const receiptResponse = await fetch(
      `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}/receipt/${receiptId}`,
      {
        method: "PUT",
        headers: {
          "Authorization": `Bearer ${accessToken}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          receipt_type: "NORMAL",
          schema: {
            standard_v1: {
              receipt: {
                amounts_per_vat_rate: [
                  { vat_rate: "STANDARD", amount: "12.00" },
                ],
                amounts_per_payment_type: [
                  { payment_type: "CASH", amount: "12.00" },
                ],
              },
            },
          },
        }),
      }
    );
    
    const signedReceipt = await receiptResponse.json();

    SIGN AT garantisce che tutte le ricevute siano conformi alla RKSV. La risposta contiene tutte le informazioni necessarie per completare la ricevuta finale consegnata al cliente:

    • qr_code_data — contiene i dati per il codice QR RKSV da visualizzare in forma grafica
    • receipt_number, time_signature e cash_register_serial_number — informazioni da visualizzare in forma testuale
    • Tutti gli importi lordi grezzi

    💡Automatizzare la configurazione

    Questa intera sequenza di richieste può essere integrata in una soluzione di provisioning “con un clic” che non richiede alcuna interazione manuale da parte dell’utente. I dettagli di implementazione dipendono da voi.

Passi successivi

Documentazione API SIGN AT

Documentazione completa dell'API per l'endpoint RKSV v1 — tutte le risorse, i parametri e le risposte.

Dati ricevuta

Riferimento dettagliato per i campi della ricevuta, le aliquote IVA e i tipi di pagamento supportati da SIGN AT.

Glossario

Termini chiave e definizioni per il sistema di conformità fiscale austriaco RKSV.

Guida HUB

Scoprite come gestire organizzazioni, chiavi API e risorse tramite fiskaly HUB.