Buone Pratiche per Agenti

Questa guida descrive l’approccio consigliato per gli agenti IA che integrano le API di fiskaly — dalla scoperta fino al deployment in produzione. Evidenzia gli errori comuni e le sfumature per paese che complicano le integrazioni automatizzate.

Flusso di integrazione consigliato

1. Scoprire

   Recuperare /products.json per identificare il prodotto corretto per il paese di destinazione. Verificare apiArchitecture per determinare se si lavora con un’API specializzata o unificata.

2. Autenticare

   POST /auth con la chiave API e il segreto forniti dall’utente. Mettere in cache il token di accesso (TTL 24h) — non autenticarsi di nuovo per ogni richiesta.

3. Effettuare il provisioning

   Creare l’infrastruttura di firma per il paese di destinazione: TSS + Client (DE), Taxpayer + Location + System (FR/IT) o equivalente. Verificare /human-interventions.json per i passaggi che richiedono input umano.

4. Effettuare transazioni

   Firmare le transazioni attraverso l’endpoint appropriato. SIGN DE utilizza un pattern PUT a due chiamate (ACTIVE → FINISHED). SIGN FR e SIGN IT utilizzano un pattern POST a due chiamate (Intention → Transaction).

Azioni automatizzabili vs. che richiedono umano

Non ogni passaggio in un’integrazione fiskaly può essere automatizzato. Prima di costruire un flusso di lavoro per agenti, verificare quali azioni richiedono un umano:

Categoria	Numero	Esempi
Completamente automatizzabile	11	Autenticazione, creazione TSS, firma di transazioni
Parzialmente automatizzabile	2	Inserimento dati del contribuente (l’umano fornisce il codice fiscale, l’agente effettua la chiamata API)
Richiede umano	7	Creazione account, generazione chiave API, go-live

Progettare l’agente per mettere in pausa e richiedere l’input dell’utente nei passaggi che richiedono umano, quindi riprendere l’automazione. Vedere il Registro degli Interventi Umani completo per i dettagli.

💡Tip

La versione leggibile dalle macchine in /human-interventions.json può essere interrogata in fase di esecuzione per adattare dinamicamente il flusso di lavoro dell’agente.

Antipattern comuni

Codificare in modo fisso gli URL base

Gli URL base differiscono tra gli ambienti TEST e LIVE e tra le API specializzate e unificate. Recuperarli sempre da /products.json invece di codificarli in modo fisso.

// Non fare così
const BASE_URL = "https://kassensichv-middleware.fiskaly.com/api/v2";

// Fare così — leggere da products.json
const product = products.find(p => p.id === "sign-de");
const baseUrl = product.baseUrls.test;

Autenticarsi di nuovo per ogni richiesta

Il token di accesso è valido per 24 ore. Metterlo in cache e autenticarsi nuovamente solo in risposta a errori 401. Autenticarsi di nuovo per ogni richiesta spreca tempo e può attivare limiti di frequenza.

Saltare l’ambiente TEST

Sviluppare e testare sempre prima nell’ambiente TEST (sandbox). TEST è gratuito, utilizza la stessa superficie API di LIVE e consente di iterare senza influire sui dati fiscali reali.

Riutilizzare UUID

Per le API specializzate (SIGN DE, SIGN AT, SIGN ES), gli ID delle risorse sono UUID generati dal client. Generare sempre UUID nuovi — riutilizzare un UUID causa un 409 Conflict.

Ignorare le chiavi di idempotenza

Per le API unificate (SIGN FR, SIGN IT), le richieste POST e PATCH richiedono un header X-Idempotency-Key. Generare un UUID nuovo per ogni operazione univoca. I tentativi ripetuti della stessa operazione devono riutilizzare la stessa chiave.

Interrogare esportazioni in modo sincrono

Le esportazioni DSFinV-K e altre operazioni di esportazione sono asincrone. Avviare l’esportazione, quindi verificarne il completamento — non bloccarsi sulla richiesta iniziale.

Particolarità per paese

Germania (SIGN DE)

⚠️PIN amministratore richiesto

L’inizializzazione del TSS richiede l’impostazione di un PIN amministratore tramite PATCH /tss/{id} prima di cambiare lo stato in INITIALIZED. Il PIN deve essere conservato in modo sicuro — perderlo richiede la sostituzione del TSS.

• Macchina a stati del TSS: UNINITIALIZED → INITIALIZED → DISABLED
• UUID generati dal client per tutti gli ID delle risorse
• Le transazioni utilizzano un modello di revisioni: revisione 1 (ACTIVE) → revisione 2 (FINISHED)
• L’esportazione DSFinV-K è obbligatoria per legge per gli audit

Francia (SIGN FR)

• Richiede una gerarchia organizzativa: Organization GROUP → Organization UNIT → Subject → Taxpayer → Location → System → Record
• La creazione del contribuente necessita di un numero SIREN reale (fornito dall’umano)
• Pattern di record a due chiamate: Intention (type: INTENTION) → Transaction (type: TRANSACTION)
• Header obbligatori in ogni richiesta: X-Api-Version, X-Idempotency-Key, X-Scope-Identifier

Italia (SIGN IT)

• Stessa architettura API unificata della Francia
• Il contribuente ha bisogno delle credenziali dell’Agenzia delle Entrate (AdE) — fornite dall’umano
• Supporta la Lotteria degli Scontrini — includere lottery_code nei record quando il cliente ne fornisce uno
• Il reporting in tempo reale all’AdE significa che la firma delle transazioni non è sicura da ripetere senza chiavi di idempotenza

Austria (SIGN AT)

• Regolamento RKSV con integrazione FinanzOnline
• URL base separato: rksv-middleware.fiskaly.com/api/v1
• Esportazione DEP (Datenerfassungsprotokoll) per la traccia di audit

Spagna (SIGN ES)

• Regolamenti TicketBAI e Verifactu
• Firma e trasmissione di fatture in XML (non JSON come altri prodotti)
• Variazioni regionali tra comunità autonome

Script di avvio rapido

Sono disponibili script di avvio rapido end-to-end per i test automatizzati:

• scripts/sign-de-quickstart.mjs — Flusso completo SIGN DE: autenticazione → TSS → client → transazione
• scripts/sign-fr-quickstart.mjs — Flusso completo SIGN FR: autenticazione → org → contribuente → ubicazione → sistema → record

Questi script dimostrano il percorso felice completo e possono servire come implementazioni di riferimento per integrazioni costruite dagli agenti.