Modalità Workflow

Integra Visiono in workflow esterni con URL firmati sicuri.

Panoramica

La Modalità Workflow permette ai sistemi esterni di incorporare la raccolta foto Visiono senza soluzione di continuità nei loro processi. Gli utenti vengono reindirizzati da sistemi esterni (come ticket Zendesk o record CRM) a Visiono, completano il caricamento foto e vengono automaticamente reindirizzati con dati verificati.

Funzionalità Principali

Funzionalità	Descrizione
URL Firmati	Firma HMAC-SHA256 previene manomissioni
Auto-redirect	Ritorno al sistema esterno dopo completamento
Campi Nascosti	Dati pre-compilati non visibili agli utenti
Tracciamento Per-invio	Sorgente esterna e riferimento archiviati
Verifica Firma	Verifica che i dati di ritorno non siano stati modificati

Come Funziona

sequenceDiagram
    participant E as Sistema Esterno
    participant V as Visiono
    participant U as Utente

    E->>E: Genera URL firmato
    E->>U: Invia link all'utente
    U->>V: Apre URL firmato
    V->>V: Valida firma
    V->>U: Mostra caricamento foto
    U->>V: Carica foto
    V->>E: Redirect con firma
    E->>E: Valida firma di ritorno

Configurazione

1. Abilitare Modalità Workflow

1. Naviga al tuo Link Permanente
2. Clicca Modifica
3. Espandi sezione Modalità Workflow
4. Abilita toggle Modalità Workflow
5. Configura URL di redirect
6. Copia il Workflow Secret

2. Configurare URL di Redirect

Imposta l'URL a cui gli utenti tornano dopo aver completato i caricamenti:

https://tuo-sistema.com/fatto?id={submission_id}&ref={reference}&sig={signature}

Segnaposto Disponibili

Segnaposto	Descrizione	Esempio
{submission_id}	ID invio Visiono	pls_123
{unique_value}	Valore campo univoco passato	ABC123
{reference}	Riferimento esterno passato	ticket-456
{photo_count}	Numero foto caricate	5
{timestamp}	Timestamp Unix	1705500000
{signature}	Firma HMAC per verifica	abc123...

Generare URL Firmati

Parametri URL

Param	Nome Lungo	Descrizione	Obbligatorio
uv	unique_value	Identificatore univoco	Sì
src	source	Sistema sorgente	Sì
ref	reference	Riferimento esterno	Sì
ts	timestamp	Timestamp Unix	Sì
sig	signature	Firma HMAC-SHA256	Sì

Algoritmo Firma

payload = "{unique_value}|{source}|{reference}|{timestamp}"
signature = HMAC-SHA256(payload, workflow_secret)

Esempio PHP

<?php

$workflowSecret = 'your-workflow-secret';
$slug = 'report-danni';

// Dati
$uniqueValue = 'ABC123';
$source = 'zendesk';
$reference = 'ticket-456';
$timestamp = time();

// Genera firma
$payload = "{$uniqueValue}|{$source}|{$reference}|{$timestamp}";
$signature = hash_hmac('sha256', $payload, $workflowSecret);

// Costruisci URL
$baseUrl = "https://visiono.io/s/{$slug}";
$params = http_build_query([
    'uv' => $uniqueValue,
    'src' => $source,
    'ref' => $reference,
    'ts' => $timestamp,
    'sig' => $signature,
]);

$url = "{$baseUrl}?{$params}";
// https://visiono.io/s/report-danni?uv=ABC123&src=zendesk&ref=ticket-456&ts=1705500000&sig=abc123...

Esempio JavaScript

const crypto = require('crypto');

const workflowSecret = 'your-workflow-secret';
const slug = 'report-danni';

// Dati
const uniqueValue = 'ABC123';
const source = 'zendesk';
const reference = 'ticket-456';
const timestamp = Math.floor(Date.now() / 1000);

// Genera firma
const payload = `${uniqueValue}|${source}|${reference}|${timestamp}`;
const signature = crypto
  .createHmac('sha256', workflowSecret)
  .update(payload)
  .digest('hex');

// Costruisci URL
const params = new URLSearchParams({
  uv: uniqueValue,
  src: source,
  ref: reference,
  ts: timestamp,
  sig: signature,
});

const url = `https://visiono.io/s/${slug}?${params}`;

Esempio Python

import hmac
import hashlib
import time
from urllib.parse import urlencode

workflow_secret = 'your-workflow-secret'
slug = 'report-danni'

# Dati
unique_value = 'ABC123'
source = 'zendesk'
reference = 'ticket-456'
timestamp = int(time.time())

# Genera firma
payload = f"{unique_value}|{source}|{reference}|{timestamp}"
signature = hmac.new(
    workflow_secret.encode(),
    payload.encode(),
    hashlib.sha256
).hexdigest()

# Costruisci URL
params = urlencode({
    'uv': unique_value,
    'src': source,
    'ref': reference,
    'ts': timestamp,
    'sig': signature,
})

url = f"https://visiono.io/s/{slug}?{params}"

Validare Firma di Redirect

Quando gli utenti vengono reindirizzati, verifica la firma per garantire l'integrità dei dati.

Esempio URL di Ritorno

https://tuo-sistema.com/fatto?sub=pls_123&ref=ticket-456&cnt=5&ts=1705500100&sig=def456...

Verifica Firma

La firma di ritorno è calcolata come:

payload = "{submission_id}|{unique_value}|{reference}|{photo_count}|{timestamp}"
expected_signature = HMAC-SHA256(payload, workflow_secret)

Verifica PHP

<?php

$workflowSecret = 'your-workflow-secret';

// Ottieni parametri dal redirect
$submissionId = $_GET['sub'];
$uniqueValue = $_GET['uv'];
$reference = $_GET['ref'];
$photoCount = $_GET['cnt'];
$timestamp = $_GET['ts'];
$receivedSignature = $_GET['sig'];

// Verifica firma
$payload = "{$submissionId}|{$uniqueValue}|{$reference}|{$photoCount}|{$timestamp}";
$expectedSignature = hash_hmac('sha256', $payload, $workflowSecret);

if (hash_equals($expectedSignature, $receivedSignature)) {
    // Firma valida - elabora l'invio
    echo "Foto inviate con successo!";
} else {
    // Firma non valida - rifiuta
    http_response_code(400);
    echo "Firma non valida";
}

Scadenza Link

Gli URL firmati scadono dopo 1 ora di default. Questo previene:

• Il riutilizzo di vecchi link
• Attacchi replay
• Dati obsoleti

Se un utente apre un link scaduto, vede una pagina errore "Link Scaduto".

Best Practice Sicurezza

Proteggi il Tuo Secret

• Conserva il workflow secret in modo sicuro
• Non esporlo mai nel codice client-side
• Ruota i secret periodicamente
• Usa variabili d'ambiente

Valida i Timestamp

$maxAge = 3600; // 1 ora
if (time() - $timestamp > $maxAge) {
    // Link scaduto
    return false;
}

Usa HTTPS

Usa sempre HTTPS per:

• I tuoi URL di redirect
• Qualsiasi chiamata API
• Endpoint webhook

Pagine Errore

Gli utenti potrebbero vedere pagine errore per:

Errore	Causa	Soluzione
Parametri Mancanti	URL senza parametri richiesti	Controlla generazione URL
Firma Non Valida	Firma non corrisponde	Verifica secret e algoritmo
Link Scaduto	Timestamp > 1 ora	Genera nuovo link

Integrazione Webhook

La Modalità Workflow funziona con i webhook. L'evento submission.created include:

{
  "event": "submission.created",
  "data": {
    "photo_request": {
      "id": "pr_123",
      "custom_slug": "report-danni"
    },
    "permanent_link_submission": {
      "id": "pls_456",
      "unique_field_value": "ABC123",
      "external_source": "zendesk",
      "external_reference": "ticket-456"
    }
  }
}

Casi d'Uso

Foto Ticket Zendesk

1. L'agente invia link firmato al cliente
2. Il cliente carica foto danni
3. Il cliente viene reindirizzato al ticket
4. Il webhook aggiorna il ticket con le foto

Sinistri Assicurativi

1. Il sistema sinistri genera link firmato
2. L'assicurato documenta i danni
3. Reindirizzato alla conferma sinistro
4. Le foto vengono collegate automaticamente al sinistro

Assistenza Sul Campo

1. Il tecnico riceve ordine di lavoro
2. Apre link firmato da mobile
3. Documenta lavoro completato
4. Reindirizzato alla pagina completamento lavoro

Risoluzione Problemi

Mismatch Firma

1. Verifica che il secret corrisponda esattamente
2. Controlla encoding parametri
3. Conferma formato timestamp
4. Assicura ordine payload corretto

Redirect Non Funziona

1. Verifica che URL redirect sia configurato
2. Controlla sintassi segnaposto
3. Conferma che URL sia correttamente codificato

Link Scade Immediatamente

1. Controlla sincronizzazione orario server
2. Verifica che timestamp sia formato Unix
3. Assicura che timestamp sia attuale

Risorse Correlate

• Link Permanenti - Configurazione link
• Webhook - Notifiche eventi
• Riferimento API - Documentazione API completa