Endpoint Leggibili dalle Macchine

fiskaly pubblica un insieme di endpoint leggibili dalle macchine accanto al sito di documentazione leggibile dall’uomo. Questi endpoint sono progettati per agenti IA, crawler LLM e pipeline di automazione che necessitano di accesso strutturato a metadati di prodotto, specifiche API e dati normativi.

Riferimento degli endpoint

Endpoint	Formato	Scopo
/llms.txt	Testo normale	Indice di scoperta LLM — elenca tutte le pagine di documentazione e gli URL delle specifiche
/llms-full.txt	Testo normale	Dump completo della documentazione per l’ingestione del contesto LLM
/products.json	JSON	Manifesto dei prodotti con metadati, URL base e URL delle specifiche per tutti i 14 prodotti
/human-interventions.json	JSON	Registro delle azioni automatizzabili vs. che richiedono umano con conteggi riassuntivi
/regulatory.json	JSON	Requisiti normativi e dettagli di conformità per paese
/.well-known/ai-plugin.json	JSON	Manifesto del plugin IA (formato di specifica del plugin OpenAI)
/CLAUDE.md	Markdown	Guida di integrazione per agenti con autenticazione, pattern e riferimento per paese
/specs/sign-de-v2.json	JSON	Specifica OpenAPI di SIGN DE v2
/specs/spec-sign-at.json	JSON	Specifica OpenAPI di SIGN AT (RKSV)
/specs/fiskaly.sign-fr.2026-02-03.yaml	YAML	Specifica OpenAPI di SIGN FR (API Unificata)
/specs/fiskaly.sign-it.2026-02-03.yaml	YAML	Specifica OpenAPI di SIGN IT (API Unificata)
/specs/fiskaly.e-invoice-be.2026-02-03.yaml	YAML	Specifica OpenAPI di E-INVOICE BE (API Unificata)
/specs/fiskaly.e-invoice-de.2026-02-03.yaml	YAML	Specifica OpenAPI di E-INVOICE DE (API Unificata)
/specs/spec-sign-es.yaml	YAML	Specifica OpenAPI di SIGN ES
/specs/spec-dsfinvk.json	JSON	Specifica OpenAPI di DSFinV-K
/specs/spec-ereceipt.json	JSON	Specifica OpenAPI di eReceipt
/specs/spec-merchant.json	JSON	Specifica OpenAPI della Management API
/specs/spec-obono.json	JSON	Specifica OpenAPI di obono (SIGN AT SaaS)

Tutti gli endpoint sono serviti da https://workspace.fiskaly.com.

Flusso di scoperta

Un tipico flusso di scoperta di un agente si presenta così:

1. Recuperare /llms.txt
   → Ottenere un indice di tutta la documentazione e le specifiche disponibili

2. Recuperare /products.json
   → Trovare il prodotto corrispondente al paese di destinazione
   → Estrarre baseUrls, specUrl e docsUrl

3. Recuperare /specs/{product-spec}
   → Caricare la specifica OpenAPI completa per il prodotto scelto

4. Recuperare /human-interventions.json
   → Identificare quali passaggi sono automatizzabili vs. che richiedono umano

products.json

Il manifesto dei prodotti è il principale endpoint di dati strutturati. Ogni voce di prodotto include:

{
  "id": "sign-de",
  "name": "SIGN DE",
  "description": "German fiscal signing (KassenSichV)",
  "country": "DE",
  "apiArchitecture": "specialized",
  "baseUrls": {
    "test": "https://kassensichv-middleware.fiskaly.com/api/v2",
    "live": "https://kassensichv.fiskaly.com/api/v2"
  },
  "specUrl": "/specs/sign-de-v2.json",
  "docsUrl": "/countries/germany",
  "apiReferenceUrl": "/api/sign-de"
}

Utilizzare apiArchitecture per determinare il pattern di integrazione:

• specialized — URL base per paese, UUID generati dal client, Management API separata
• unified — URL base condivisi, ID generati dal server, header obbligatori (X-Api-Version, X-Idempotency-Key, X-Scope-Identifier)
• platform — servizi trasversali ai prodotti (DSFinV-K, eReceipt, Management API)

human-interventions.json

Restituisce tutte le azioni di integrazione categorizzate per livello di automazione:

{
  "summary": {
    "fullyAutomatable": 11,
    "partiallyAutomatable": 2,
    "requiresHuman": 7
  },
  "interventions": [
    {
      "action": "Authenticate (get token)",
      "product": "All",
      "automatable": "yes",
      "reason": "Standard API call",
      "whatToDo": "POST /auth with api_key + api_secret"
    }
  ]
}

Vedere il Registro degli Interventi Umani per il riferimento completo leggibile dall’uomo.

ai-plugin.json

Il manifesto del plugin IA segue il formato di specifica del plugin OpenAI:

{
  "schema_version": "v1",
  "name_for_model": "fiskaly",
  "description_for_model": "fiskaly provides fiscal compliance APIs...",
  "api": {
    "type": "openapi",
    "url": "https://workspace.fiskaly.com/specs/sign-de-v2.json"
  }
}

Accesso dei crawler

La configurazione di robots.txt consente ai crawler LLM di accedere a tutti gli endpoint di documentazione e leggibili dalle macchine. I crawler web standard hanno il permesso di accedere alle pagine di documentazione, ai file delle specifiche e agli endpoint di dati strutturati.

💡Tip

Preferire il server MCP rispetto al recupero HTTP diretto quando si lavora in Claude Code o Cursor. Il server MCP fornisce gli stessi dati attraverso chiamate di strumenti strutturate con ricerca e filtro integrati. Vedere la guida al server MCP.