Mode Workflow

Intégrez Visiono dans des workflows externes avec des URLs signées sécurisées.

Aperçu

Le Mode Workflow permet aux systèmes externes d'intégrer de manière transparente la collecte de photos Visiono dans leurs processus. Les utilisateurs sont redirigés depuis des systèmes externes (comme des tickets Zendesk ou des enregistrements CRM) vers Visiono, complètent leurs uploads de photos, et sont automatiquement redirigés avec des données vérifiées.

Fonctionnalités clés

Fonctionnalité	Description
URLs signées	Signature HMAC-SHA256 empêche la falsification
Redirection automatique	Retour au système externe après complétion
Champs cachés	Données pré-remplies non visibles par les utilisateurs
Suivi par soumission	Source externe et référence stockées
Vérification de signature	Vérifier que les données de redirection n'ont pas été modifiées

Comment ça fonctionne

sequenceDiagram
    participant E as Système externe
    participant V as Visiono
    participant U as Utilisateur

    E->>E: Générer URL signée
    E->>U: Envoyer lien à l'utilisateur
    U->>V: Ouvrir URL signée
    V->>V: Valider signature
    V->>U: Afficher upload de photos
    U->>V: Télécharger photos
    V->>E: Rediriger avec signature
    E->>E: Valider signature de retour

Configuration

1. Activer le Mode Workflow

1. Naviguez vers votre Lien permanent
2. Cliquez sur Modifier
3. Développez la section Mode Workflow
4. Activez le toggle Mode Workflow
5. Configurez l'URL de redirection
6. Copiez le Secret Workflow

2. Configurer l'URL de redirection

Définissez l'URL vers laquelle les utilisateurs retournent après avoir complété les uploads :

https://votre-systeme.com/termine?id={submission_id}&ref={reference}&sig={signature}

Placeholders disponibles

Placeholder	Description	Exemple
{submission_id}	ID de soumission Visiono	pls_123
{unique_value}	Valeur du champ unique passée	ABC123
{reference}	Référence externe passée	ticket-456
{photo_count}	Nombre de photos téléchargées	5
{timestamp}	Timestamp Unix	1705500000
{signature}	Signature HMAC pour vérification	abc123...

Génération d'URLs signées

Paramètres URL

Param	Nom long	Description	Requis
uv	unique_value	Identifiant unique	Oui
src	source	Système source	Oui
ref	reference	Référence externe	Oui
ts	timestamp	Timestamp Unix	Oui
sig	signature	Signature HMAC-SHA256	Oui

Algorithme de signature

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

Exemple PHP

<?php

$workflowSecret = 'votre-secret-workflow';
$slug = 'rapport-dommages';

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

// Générer la signature
$payload = "{$uniqueValue}|{$source}|{$reference}|{$timestamp}";
$signature = hash_hmac('sha256', $payload, $workflowSecret);

// Construire l'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/rapport-dommages?uv=ABC123&src=zendesk&ref=ticket-456&ts=1705500000&sig=abc123...

Exemple JavaScript

const crypto = require('crypto');

const workflowSecret = 'votre-secret-workflow';
const slug = 'rapport-dommages';

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

// Générer la signature
const payload = `${uniqueValue}|${source}|${reference}|${timestamp}`;
const signature = crypto
  .createHmac('sha256', workflowSecret)
  .update(payload)
  .digest('hex');

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

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

Exemple Python

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

workflow_secret = 'votre-secret-workflow'
slug = 'rapport-dommages'

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

# Générer la signature
payload = f"{unique_value}|{source}|{reference}|{timestamp}"
signature = hmac.new(
    workflow_secret.encode(),
    payload.encode(),
    hashlib.sha256
).hexdigest()

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

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

Validation de la signature de retour

Quand les utilisateurs sont redirigés, vérifiez la signature pour assurer l'intégrité des données.

Exemple d'URL de retour

https://votre-systeme.com/termine?sub=pls_123&ref=ticket-456&cnt=5&ts=1705500100&sig=def456...

Vérification de signature

La signature de retour est calculée comme :

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

Vérification PHP

<?php

$workflowSecret = 'votre-secret-workflow';

// Obtenir les paramètres de la redirection
$submissionId = $_GET['sub'];
$uniqueValue = $_GET['uv'];
$reference = $_GET['ref'];
$photoCount = $_GET['cnt'];
$timestamp = $_GET['ts'];
$receivedSignature = $_GET['sig'];

// Vérifier la signature
$payload = "{$submissionId}|{$uniqueValue}|{$reference}|{$photoCount}|{$timestamp}";
$expectedSignature = hash_hmac('sha256', $payload, $workflowSecret);

if (hash_equals($expectedSignature, $receivedSignature)) {
    // Signature valide - traiter la soumission
    echo "Photos soumises avec succès !";
} else {
    // Signature invalide - rejeter
    http_response_code(400);
    echo "Signature invalide";
}

Expiration des liens

Les URLs signées expirent après 1 heure par défaut. Cela empêche :

• La réutilisation d'anciens liens
• Les attaques par rejeu
• Les données périmées

Si un utilisateur ouvre un lien expiré, il voit une page d'erreur "Lien expiré".

Bonnes pratiques de sécurité

Protéger votre secret

• Stockez le secret workflow de manière sécurisée
• Ne l'exposez jamais dans le code côté client
• Effectuez une rotation des secrets périodiquement
• Utilisez des variables d'environnement

Valider les timestamps

$maxAge = 3600; // 1 heure
if (time() - $timestamp > $maxAge) {
    // Lien expiré
    return false;
}

Utiliser HTTPS

Utilisez toujours HTTPS pour :

• Vos URLs de redirection
• Tous les appels API
• Les points de terminaison webhook

Pages d'erreur

Les utilisateurs peuvent voir des pages d'erreur pour :

Erreur	Cause	Solution
Paramètres manquants	L'URL manque de paramètres requis	Vérifiez la génération d'URL
Signature invalide	La signature ne correspond pas	Vérifiez le secret et l'algorithme
Lien expiré	Timestamp > 1 heure	Générez un nouveau lien

Intégration Webhook

Le Mode Workflow fonctionne avec les webhooks. L'événement submission.created inclut :

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

Cas d'usage

Photos de tickets Zendesk

1. L'agent envoie au client un lien signé
2. Le client télécharge des photos de dommages
3. Le client est redirigé vers le ticket
4. Le webhook met à jour le ticket avec les photos

Réclamations d'assurance

1. Le système de réclamation génère un lien signé
2. L'assuré documente les dommages
3. Redirigé vers la confirmation de réclamation
4. Les photos sont automatiquement liées à la réclamation

Service terrain

1. Le technicien reçoit un ordre de travail
2. Ouvre le lien signé depuis mobile
3. Documente le travail complété
4. Redirigé vers la page de complétion du travail

Dépannage

Discordance de signature

1. Vérifiez que le secret correspond exactement
2. Vérifiez l'encodage des paramètres
3. Confirmez le format du timestamp
4. Assurez-vous que l'ordre du payload est correct

La redirection ne fonctionne pas

1. Vérifiez que l'URL de redirection est configurée
2. Vérifiez la syntaxe des placeholders
3. Confirmez que l'URL est correctement encodée

Lien expiré immédiatement

1. Vérifiez la synchronisation de l'heure du serveur
2. Vérifiez que le timestamp est au format Unix
3. Assurez-vous que le timestamp est actuel

Ressources connexes

• Liens permanents - Configuration des liens
• Webhooks - Notifications d'événements
• Référence API - Documentation API complète