Guida Rapida per Sviluppatori

Crea la tua prima richiesta foto via API in 5 minuti.

Prerequisiti

Prima di iniziare, assicurati di avere:

• Un account Visiono attivo con accesso API
• Una chiave API creata
• Un endpoint webhook pronto (o usa webhook.site per i test)

Passo 1: Creare una Richiesta Foto

Usa l'API per creare una richiesta foto una tantum:

curl -X POST "https://www.visiono.iohttps://www.visiono.io/it/docs/api/v1/photo-requests" \
  -H "X-API-Key: vsk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Per favore fotografa il pacco da tutti i lati",
    "expires_in_hours": 24
  }'

Risposta Attesa

{
  "data": {
    "id": "req_abc123",
    "unique_code": "ABC123",
    "status": "pending",
    "instructions": "Per favore fotografa il pacco da tutti i lati",
    "request_url": "https://visio.now/p/abc123",
    "code_entry_url": "https://visio.now/code",
    "expires_at": "2024-01-16T10:00:00Z",
    "created_at": "2024-01-15T10:00:00Z",
    "items": []
  }
}

Campi chiave nella risposta:

Campo	Descrizione
id	Identificatore univoco richiesta
request_url	Condividi questo link con il tuo cliente
unique_code	Codice breve per inserimento manuale su code_entry_url
expires_at	Quando la richiesta scade

Passo 2: Condividere il Link

Invia la request_url dalla risposta al tuo cliente via SMS, email o qualsiasi canale di messaggistica.

Quando il cliente apre il link:

1. Vede le tue istruzioni
2. La fotocamera si attiva (nessun accesso galleria)
3. Scatta le foto richieste
4. Le foto vengono inviate al tuo workspace

Solo Fotocamera

I clienti possono usare solo la fotocamera del dispositivo — nessun caricamento da galleria. Questo garantisce foto autentiche in tempo reale.

Passo 3: Ricevere il Webhook

Quando le foto vengono inviate, Visiono manda un webhook al tuo endpoint configurato.

Configurare il Gestore Webhook

Crea un semplice server Express per ricevere i webhook:

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

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

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

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

  // 2. Conferma immediatamente
  res.status(200).send('OK');

  // 3. Elabora l'evento
  const { event, data } = req.body;

  if (event === 'photo_request.submitted') {
    console.log('ID Richiesta:', data.id);
    console.log('Foto ricevute:');

    data.photos.forEach((photo, index) => {
      console.log(`  ${index + 1}. ${photo.url}`);
      if (photo.metadata?.gps_lat) {
        console.log(`     GPS: ${photo.metadata.gps_lat}, ${photo.metadata.gps_lng}`);
      }
    });
  }
});

app.listen(3000, () => {
  console.log('Server webhook in esecuzione sulla porta 3000');
});

Esempio Payload Webhook

{
  "event": "photo_request.submitted",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "req_abc123",
    "type": "one_time",
    "instructions": "Per favore fotografa il pacco da tutti i lati",
    "photos": [
      {
        "id": "photo_xyz789",
        "url": "https://storage.visiono.io/photos/xyz789.jpg",
        "metadata": {
          "gps_lat": 45.4642,
          "gps_lng": 9.1900,
          "captured_at": "2024-01-15T10:28:00Z"
        }
      }
    ],
    "submitted_at": "2024-01-15T10:30:00Z"
  }
}

Test Webhook

Usa webhook.site per ottenere un endpoint temporaneo per i test. Puoi vedere i payload in arrivo in tempo reale senza configurare un server.

Passo 4: Scaricare le Foto

Gli URL foto nel payload webhook sono link di download diretto:

# Scarica una foto
curl -O "https://storage.visiono.io/photos/xyz789.jpg"

O programmaticamente nel tuo gestore webhook:

const https = require('https');
const fs = require('fs');

function downloadPhoto(url, filename) {
  const file = fs.createWriteStream(filename);
  https.get(url, (response) => {
    response.pipe(file);
    file.on('finish', () => file.close());
  });
}

// Nel tuo gestore webhook
data.photos.forEach((photo, index) => {
  downloadPhoto(photo.url, `foto_${index + 1}.jpg`);
});

Testare la Configurazione

Usa questa checklist per verificare che tutto funzioni:

Test	Come Verificare
Chiave API funziona	GET https://www.visiono.io/it/docs/api/v1/ping restituisce 200 OK
Richiesta creata	La risposta contiene request_url e unique_code
Link accessibile	Apri request_url nel browser, la fotocamera si attiva
Webhook configurato	Crea webhook nella dashboard
Webhook riceve	L'evento test arriva al tuo endpoint
Firma valida	Il gestore restituisce 200, non 401

Test Rapido API

# Testa la tua chiave API
curl -X GET "https://www.visiono.iohttps://www.visiono.io/it/docs/api/v1/ping" \
  -H "X-API-Key: vsk_live_your_api_key_here"

Risposta attesa:

{
  "message": "pong",
  "timestamp": "2024-01-15T10:00:00Z"
}

Prossimi Passi

Ora che hai le basi funzionanti:

• Webhook — Configura tutti gli eventi disponibili
• Link Permanenti — Crea link riutilizzabili per raccolta continua
• Slot Foto — Richiedi foto specifiche con istruzioni
• Riferimento API — Documentazione completa endpoint

Hai bisogno di aiuto? Controlla il Riferimento API per documentazione dettagliata degli endpoint, o configura i Webhook per tutti gli eventi disponibili.