# domande.ch — AI Agent & Developer Integration Guide

> domande.ch è la piattaforma web di nuova generazione per creare, personalizzare ed analizzare sondaggi e moduli online con l'Intelligenza Artificiale (Google Gemini SDK).

## Core Capabilities for AI Agents & Developers
- **AI Form Generation**: Generazione automatica di moduli da un prompt in linguaggio naturale via API (`POST /api/v1/forms` con parametro `prompt`).
- **Universal Script Widget**: Incorporamento pop-up con 1 riga di codice (`<script src="https://domande.ch/widget.js" data-form-id="FORM_ID"></script>`).
- **Embedded iFrame**: Visualizzazione nativa e responsive via `https://domande.ch/f/{formId}/embed`.
- **Public REST API v1**: Gestione completa di form, campi, risposte ed analytics.
- **Model Context Protocol (MCP)**: Server MCP conforme JSON-RPC 2.0 disponibile su `https://domande.ch/api/mcp`.

## Quick Start Integration Examples

### 1. HTML / Script Widget Integration
Inserisci questo tag HTML in qualsiasi sito web per aggiungere un widget di feedback o un modulo pop-up:
```html
<script src="https://domande.ch/widget.js" data-form-id="YOUR_FORM_ID" data-button-text="Invia Feedback" data-position="bottom-right"></script>
```

### 2. React / Next.js iFrame Embed
```tsx
export function DomandeFormEmbed({ formId }: { formId: string }) {
  return (
    <iframe
      src={`https://domande.ch/f/${formId}/embed`}
      className="w-full h-[600px] border-0 rounded-2xl shadow-sm"
      title="domande.ch form"
      loading="lazy"
    />
  );
}
```

### 3. Create Form via REST API v1 (AI Prompt or Manual)
```bash
curl -X POST https://domande.ch/api/v1/forms \
  -H "Authorization: Bearer dom_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Crea un modulo di contatto per un'agenzia immobiliare con campi per nome, email, budget e tipo di immobile",
    "status": "published"
  }'
```

### 4. Submit Form Answer via REST API v1
```bash
curl -X POST https://domande.ch/api/v1/forms/FORM_ID/submissions \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "nome": "Mario Rossi",
      "email": "mario@example.com",
      "valutazione": 5
    }
  }'
```

### 5. Model Context Protocol (MCP) Server Endpoint
Endpoint POST: `https://domande.ch/api/mcp`
- Intestazione richiesta: `Authorization: Bearer dom_sk_YOUR_API_KEY`
- Supporta metodi JSON-RPC 2.0: `initialize`, `tools/list`, `tools/call` (es. `create_form`, `list_forms`, `get_form`, `get_submissions`).

## Available Documentation & Standards
- Full Extended Guide: https://domande.ch/llms-full.txt
- OpenAPI 3.1.0 Spec: https://domande.ch/.well-known/openapi.json
- AI Plugin Manifest: https://domande.ch/.well-known/ai-plugin.json
- AI Information API: https://domande.ch/api/ai-info
- AI Developer Portal: https://domande.ch/docs/ai