Integrazione Claude Code

Migliora il tuo workflow di sviluppo con assistenza AI-powered per l'integrazione API Visiono.

Panoramica

Claude Code è lo strumento CLI ufficiale di Anthropic per Claude AI. Il plugin Visiono fornisce aiuto context-aware con Richieste Foto, Link Permanenti, setup webhook e generazione codice in più linguaggi.

Prerequisiti

• Claude Code installato
• Account Visiono con accesso API
• Accesso terminale

Installare il Plugin

Dal Marketplace

Aggiungi il repository plugin Visiono:

/plugin marketplace add visiono-io/visiono-claude-plugin

Installa il plugin:

/plugin install visiono-api@visiono

Verifica

Conferma installazione:

/plugin list

Dovresti vedere visiono-api nella lista plugin installati.

Cosa Fornisce il Plugin

Il plugin Visiono dà a Claude conoscenza completa su:

Contesto	Descrizione
API Richieste Foto	Crea link raccolta foto con scadenza e QR code
API Link Permanenti	Costruisci workflow raccolta foto permanenti
Webhook	Tipi evento, strutture payload e verifica firma
URL Download	Accedi foto inviate con URL firmati time-limited
Esempi Codice	Snippet pronti all'uso in PHP, JavaScript e Python
Best Practice	Uso QR code, sicurezza webhook, pattern polling

Usare il Plugin

Una volta installato, il plugin si attiva automaticamente quando menzioni Visiono o chiedi di workflow raccolta foto.

Aiuto Integrazione API

Chiedi a Claude guida implementazione specifica:

Come creo una Richiesta Foto con link con scadenza?

Mostrami come creare un Link Permanente per ispezioni veicoli

Come ottengo il QR code per una richiesta foto?

Generazione Codice

Richiedi esempi specifici per linguaggio:

Genera una funzione PHP per creare una Richiesta Foto con GPS obbligatorio

Crea un gestore webhook JavaScript con verifica firma

Scrivi uno script Python per scaricare tutte le foto da un invio

Integrazione Webhook

Ottieni aiuto implementazione webhook:

Come verifico le firme webhook Visiono in Node.js?

Mostrami la struttura payload per evento photo_submission.created

Crea un controller Laravel per gestire webhook Visiono

Conversazioni di Esempio

Creare una Richiesta Foto

User: Come creo una Richiesta Foto con scadenza 48 ore?

Claude: Ecco come creare una Richiesta Foto usando l'API Visiono:

curl -X POST "https://www.visiono.iohttps://www.visiono.io/it/docs/api/v1/photo-requests" \
  -H "X-API-Key: vsk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Carica le tue foto documento",
    "recipient_email": "[email protected]",
    "expires_in_hours": 48,
    "require_gps": false,
    "items": [
      {"instructions": "Fronte documento", "is_required": true},
      {"instructions": "Retro documento", "is_required": true}
    ]
  }'

La risposta include:
- unique_code: Il codice breve (es. "ABC123")
- request_url: Link diretto (https://tenant.visio.now/ABC123)
- qrcode_url: Ottieni via endpoint /photo-requests/{id}/qrcode

Creare un Link Permanente

User: Crea un Link Permanente per ispezioni flotta veicoli

Claude: Ecco un setup Link Permanente per ispezioni flotta:

curl -X POST "https://www.visiono.iohttps://www.visiono.io/it/docs/api/v1/smart-links" \
  -H "X-API-Key: vsk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Foto ispezione veicolo",
    "custom_slug": "ispezione-flotta",
    "unique_field_label": "Targa",
    "show_full_name_field": true,
    "full_name_required": true,
    "require_gps": true,
    "tags": ["flotta", "ispezione"],
    "items": [
      {"instructions": "Vista frontale", "is_required": true},
      {"instructions": "Lato sinistro", "is_required": true},
      {"instructions": "Lato destro", "is_required": true},
      {"instructions": "Danni (se presenti)", "is_required": false}
    ]
  }'

Il link sarà permanente a: https://tenant.visio.now/ispezione-flotta

Integrazione Webhook

User: Crea un gestore webhook per invii foto in Node.js

Claude: Ecco un gestore webhook sicuro con verifica firma:

const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = process.env.VISIONO_WEBHOOK_SECRET;

app.post('/webhooks/visiono', express.json(), (req, res) => {
  // Verifica firma (CRITICO per sicurezza)
  const signature = req.headers['x-visiono-signature'];
  const payload = JSON.stringify(req.body);
  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Firma non valida');
  }

  // Gestisci eventi
  const { event, timestamp, data } = req.body;

  switch (event) {
    case 'photo_submission.created':
      console.log('Nuova foto inviata:', {
        photo_request_id: data.photo_request.id,
        submission_id: data.submission.id,
        has_gps: data.submission.has_gps_data
      });
      break;

    case 'photo_request.submitted':
      console.log('Tutte le foto inviate:', {
        request_id: data.photo_request.id,
        total_photos: data.photo_request.submissions_count
      });
      // Recupera URL download
      break;
  }

  res.status(200).send('OK');
});

app.listen(3000);

Come Funziona

Il plugin è context-aware e si attiva automaticamente quando:

• Menzioni "Visiono" nella conversazione
• Chiedi di raccolta foto, Richieste Foto o Link Permanenti
• Stai lavorando su codice integrazione webhook
• Riferisci l'API Visiono

Non servono comandi speciali - chiedi naturalmente dell'integrazione Visiono.

Funzionalità Chiave

Documentazione API Accurata

Il plugin fornisce dettagli endpoint esatti, inclusi:

• Nomi campi corretti (unique_code, request_url, expires_in_hours)
• Header autenticazione appropriati (X-API-Key)
• Strutture risposta con prefissi ID (pr_, sl_, ps_)
• Informazioni rate limiting

Best Practice Sicurezza

Claude ti guiderà su:

• Verifica firma webhook (HMAC-SHA256)
• Storage secret sicuro
• Funzioni comparazione timing-safe
• Requisiti HTTPS

Esempi Codice

Ottieni codice production-ready in:

• PHP - Laravel, Symfony, PHP vanilla
• JavaScript - Node.js, Express, Next.js
• Python - Flask, Django, FastAPI

Configurazione

Setup Chiave API

Configura la tua chiave API per testing:

export VISIONO_API_KEY="your-api-key"

Webhook Secret

Configura verifica webhook:

export VISIONO_WEBHOOK_SECRET="your-secret"

Best Practice

Prompt Efficaci

Sii specifico su cosa ti serve:

• Buono: "Crea una funzione PHP per verificare firme webhook Visiono"
• Meglio: "Crea un middleware Laravel per verificare firme webhook Visiono con gestione errori"

Condividere Contesto

Condividi contesto rilevante:

Sto usando Next.js 14 con App Router.
Crea un route handler API per webhook Visiono.

Sviluppo Iterativo

Costruisci incrementalmente:

1. Inizia con integrazione base
2. Aggiungi gestione errori
3. Aggiungi logging
4. Aggiungi logica retry

Risoluzione Problemi

Plugin Non Trovato

Se installazione fallisce:

1. Aggiorna Claude Code all'ultima versione
2. Verifica connessione internet
3. Controlla che repository marketplace sia aggiunto:

   /plugin marketplace list

Plugin Non Si Attiva

Se Claude non sembra usare la conoscenza plugin:

1. Menziona esplicitamente "Visiono" o "Richiesta Foto" nel prompt
2. Fai domande specifiche sull'API
3. Reinstalla il plugin:

   /plugin uninstall visiono-api@visiono
   /plugin install visiono-api@visiono

Informazioni Obsolete

Il plugin recupera dall'ultima specifica OpenAPI. Se noti discrepanze:

1. Segnalale al supporto Visiono
2. Controlla la documentazione API ufficiale: https://www.visiono.io/it/docs/api/v1

Aggiornare il Plugin

Gli aggiornamenti plugin avvengono automaticamente quando il repository è aggiornato. Per aggiornare manualmente:

/plugin update visiono-api@visiono

Disinstallazione

Rimuovi il plugin:

/plugin uninstall visiono-api@visiono

Rimuovi il repository marketplace (opzionale):

/plugin marketplace remove visiono-io/visiono-claude-plugin

Risorse Correlate

• Riferimento API - Documentazione API completa
• Webhook - Configurazione eventi
• Chiavi API - Setup autenticazione