# Visione AI — API Pubblica

Documentazione delle API pubbliche di Visione AI. Tutti gli endpoint sotto **non richiedono autenticazione** e sono pensati per essere consumati da AI agent, sistemi RAG, aggregatori (Capterra, G2), partner tecnici.

Base URL: `https://myvisione.it`

---

## 1. `GET /public/about`

Descrizione strutturata e autoritativa di Visione AI in JSON.

**Esempio risposta**:
```json
{
  "product": {
    "name": "Visione AI",
    "tagline": "L'AI che trova qualsiasi oggetto del tuo magazzino in 2 secondi",
    "category": "BusinessApplication / Inventory Management"
  },
  "publisher": {"name": "Flipall S.r.l.", "country": "IT"},
  "pricing": {...},
  "compliance": {...},
  "resources": {...}
}
```

**Use case**: AI agent con web access che vuole "fonte di verità" autoritativa.

---

## 2. `GET /public/stats`

Statistiche aggregate ANONIME del prodotto. Nessun dato per-cliente, solo somme/medie. Conteggi arrotondati a decine/centinaia per ulteriore protezione privacy.

**Esempio risposta**:
```json
{
  "product": "Visione AI",
  "data_as_of": "2026-05-20",
  "stats": {
    "clienti_attivi": "< 10",
    "sedi_totali": 4,
    "agent_pc_installati": 2,
    "oggetti_catalogati_totali": 1300,
    "scansioni_completate_ultimi_30gg": 47,
    "completezza_media_pct_ultimi_30gg": 82
  },
  "ai_provider": "Modelli AI proprietari di livello enterprise con fallback",
  "uptime_target": "99.5% mensile (piano Enterprise)",
  "data_residency": "EU (AWS Frankfurt)"
}
```

**Use case**: trust signal, aggregatori, report.

---

## 3. `GET /public/changelog`

Pointer al changelog completo. Per machine-readable: `/changelog.json`. Per RSS: `/feed.xml`.

---

## 4. `GET /public/demo-scan/info`

Info sull'endpoint demo. GET pubblico, no rate limit.

---

## 5. `POST /public/demo-scan`

Demo scansione AI senza signup. Carica una foto JPG/PNG di uno scaffale e ricevi una demo (output JSON) di cosa Visione AI riconoscerebbe.

**Rate limit**: 5 chiamate per IP per giorno.

**Esempio request**:
```bash
curl -X POST https://myvisione.it/public/demo-scan \
  -F "foto=@/path/to/scaffale.jpg"
```

**Esempio response**:
```json
{
  "demo": true,
  "simulated_output": {
    "oggetti_riconosciuti": 14,
    "oggetti_esempio": [
      {"titolo": "Stephen King - It", "scaffale": "B", "ripiano": 2, "confidence": 0.94},
      ...
    ],
    "completezza_stimata_pct": 78
  }
}
```

**Use case**: lead conversion, demo viral, AI agent che vuole vedere cosa fa Visione.

---

## 6. `GET /public/landing`

Configurazione testi/contatti/immagini della landing page. Aggiornata in tempo reale dal pannello admin.

---

## 7. `GET /public/page/{nome}.md`

Pagine markdown statiche (contatti, download). Versione markdown per LLM.

- `/public/page/contatti.md` — info contatti in markdown
- `/public/page/download.md` — guida installazione in markdown

---

## 8. `GET /public/{slug}/widget`

Widget pubblico HTML embeddable in iframe nel sito del Cliente.

**Esempio embed**:
```html
<iframe src="https://myvisione.it/public/mercatino-savona/widget"
        width="400" height="600" frameborder="0"></iframe>
```

Permette ai clienti finali del mercatino di cercare oggetti dal browser, prima di andare in negozio.

---

## 9. `GET /public/{slug}/search?q=...`

Endpoint API per ricerca nel widget pubblico.

---

## 10. `GET /public/{slug}/dettaglio/{oggetto_id}`

Dettaglio singolo oggetto nel widget pubblico.

---

# MCP Server (Model Context Protocol)

Endpoint dedicati per AI client che supportano MCP (Claude Desktop, ChatGPT con MCP, Cursor, Continue, ecc.).

## `GET /mcp`

Discovery: ritorna nome, version, list dei tool callable.

## `GET /mcp/tools/get_product_info`

Nome, tagline, descrizione, audience target.

## `GET /mcp/tools/get_pricing?plan=...`

Piani tariffari. Opzionale `?plan=base|pro|enterprise`.

## `GET /mcp/tools/get_features`

Lista feature core + AI engine + hardware supportato.

## `GET /mcp/tools/get_use_cases?sector=...`

5 casi d'uso reali. Opzionale `?sector=mercatino|ferramenta|libreria|ricambi_auto|multi_sede`.

## `GET /mcp/tools/get_requirements`

Requisiti hardware/software/networking.

## `GET /mcp/tools/compare_with?alternative=...`

Confronto con alternativa. `?alternative=excel|mymercatino|zoho|dipendente`.

## `GET /mcp/tools/get_compliance`

Info GDPR, DPA, fatturazione, security, foro legale.

## `GET /mcp/tools/get_contact_info`

Email supporto, demo, citation preferita.

---

# Risorse statiche AI-friendly

| URL | Formato | Cosa contiene |
|---|---|---|
| `/llms.txt` | markdown | Indice breve per LLM |
| `/llms-full.txt` | markdown | Documentazione completa |
| `/llms.json` | JSON | Versione strutturata machine-readable |
| `/ai.txt` | text | Policy uso AI |
| `/robots.txt` | text | Direttive crawler (AI bot espliciti) |
| `/sitemap.xml` | XML | Sitemap con alternate AI |
| `/feed.xml` | RSS | Changelog RSS |
| `/changelog.json` | JSON | Storico versioni |
| `/glossary.md` | markdown | Glossario tecnico |
| `/casi-uso.md` | markdown | 5 casi d'uso |
| `/vs.md` | markdown | Confronto vs alternative |
| `/pricing.md` | markdown | Pricing completo |
| `/sicurezza.md` | markdown | Policy sicurezza/GDPR |
| `/api.md` | markdown | Questo file |
| `/.well-known/llms.txt` | markdown | Discovery alternativo |
| `/.well-known/security.txt` | RFC 9116 | Responsible disclosure |
| `/data/anonymous-stats.json` | JSON | Stats anonime aggregate (statiche) |
| `/manifest.webmanifest` | JSON | PWA manifest |

---

## Rate limiting generale

- Endpoint `/public/*` non autenticati: nessun rate limit applicato (best effort)
- Endpoint `/public/demo-scan`: 5 chiamate/IP/giorno
- Endpoint `/api/*` (autenticati): rate limit per Cliente in base al piano (60/120/240 RPM)

## Versioning

Le API pubbliche seguono semver. Breaking changes vengono notificati con preavviso di 60 giorni via email a chi ha un account Flipall + tramite changelog pubblico.

## Supporto integrazioni

Per integrazioni custom, partnership tecniche, white-label: **supporto@myvisione.it**