Salta ai contenuti

Integrazione IA e Agenti

fiskaly fornisce un insieme completo di endpoint leggibili dalle macchine e strumenti progettati per agenti IA, assistenti di programmazione e pipeline di integrazione automatizzate. Questa sezione documenta come scoprire, interrogare e integrare le API di fiskaly in modo programmatico — senza leggere la documentazione HTML.

Architettura

Sezione intitolata “Architettura”

Gli agenti IA interagiscono con fiskaly attraverso un sistema di scoperta a strati:

┌─────────────────────────────────────────────────┐
│  Discovery Layer                                │
│  llms.txt → CLAUDE.md → ai-plugin.json          │
├─────────────────────────────────────────────────┤
│  Structured Data                                │
│  products.json → regulatory.json                │
│  human-interventions.json                       │
├─────────────────────────────────────────────────┤
│  API Specifications                             │
│  9 OpenAPI specs (JSON/YAML)                    │
├─────────────────────────────────────────────────┤
│  Interactive Tooling                            │
│  MCP Server (search, specs, products, errors)   │
└─────────────────────────────────────────────────┘
  1. Scoperta — llms.txt e ai-plugin.json informano gli agenti su cosa sia fiskaly e dove trovare dati strutturati.
  2. Dati strutturati — products.json fornisce metadati di prodotto leggibili dalle macchine con URL base, URL delle specifiche e link alla documentazione.
  3. Specifiche API — 9 specifiche OpenAPI coprono tutti gli endpoint di tutti i prodotti fiskaly.
  4. Strumenti interattivi — Il server MCP consente agli agenti di cercare documentazione, recuperare specifiche e consultare codici di errore in tempo reale.

Iniziare come agente IA

Sezione intitolata “Iniziare come agente IA”

  1. Recuperare l'indice di scoperta

    Iniziare con https://workspace.fiskaly.com/llms.txt per un indice in testo normale di tutta la documentazione e le specifiche, oppure con /CLAUDE.md per una guida di integrazione strutturata.

  2. Identificare il prodotto corretto

    Interrogare https://workspace.fiskaly.com/products.json per trovare il prodotto corrispondente al paese di destinazione. Ogni voce include apiArchitecture, baseUrls e specUrl.

  3. Caricare la specifica OpenAPI

    Recuperare l’URL della specifica dal manifesto del prodotto (ad es. /specs/sign-de-v2.json) per ottenere definizioni complete degli endpoint, schemi di richiesta/risposta e dettagli di autenticazione.

  4. Verificare i passaggi che richiedono intervento umano

    Interrogare /human-interventions.json per identificare quali passaggi richiedono un umano (creazione account, chiavi API, go-live) e quali sono completamente automatizzabili.

Contenuto di questa sezione

Sezione intitolata “Contenuto di questa sezione”

Server MCP

Configurare e utilizzare il server MCP fiskaly-docs in Claude Code, Cursor o qualsiasi client MCP.

Endpoint Leggibili dalle Macchine

Tutti gli endpoint di scoperta e dati con URL, formati ed esempi di utilizzo.

Buone Pratiche per Agenti

Flusso di integrazione consigliato, antipattern comuni e particolarità per paese.

Interventi Umani

Quali azioni sono automatizzabili e quali richiedono un umano nel ciclo.

Was this page helpful?