Workflow Mode

Integrirajte Visiono u vanjske tijekove rada sa sigurnim potpisanim URL-ovima.

Pregled

Workflow Mode omogućuje vanjskim sustavima da besprijekorno ugrade Visiono prikupljanje fotografija u svoje procese. Korisnici se preusmjeravaju iz vanjskih sustava (poput Zendesk tiketa ili CRM zapisa) na Visiono, dovršavaju učitavanja fotografija i automatski se preusmjeravaju natrag s verificiranim podacima.

Ključne značajke

Značajka	Opis
Potpisani URL-ovi	HMAC-SHA256 potpis sprječava neovlaštene izmjene
Automatsko preusmjeravanje	Povratak u vanjski sustav nakon završetka
Skrivena polja	Prethodno popunjeni podaci nisu vidljivi korisnicima
Praćenje po slanju	Vanjski izvor i referenca se pohranjuju
Verifikacija potpisa	Provjerite da podaci preusmjeravanja nisu modificirani

Kako funkcionira

sequenceDiagram
    participant E as Vanjski sustav
    participant V as Visiono
    participant U as Korisnik

    E->>E: Generiraj potpisani URL
    E->>U: Pošalji link korisniku
    U->>V: Otvori potpisani URL
    V->>V: Validiraj potpis
    V->>U: Prikaži učitavanje fotografija
    U->>V: Učitaj fotografije
    V->>E: Preusmjeri s potpisom
    E->>E: Validiraj povratni potpis

Konfiguracija

1. Omogući Workflow Mode

1. Navigirajte do vašeg Trajnog linka
2. Kliknite Uredi
3. Proširite odjeljak Workflow Mode
4. Omogućite prekidač Workflow Mode
5. Konfigurirajte URL preusmjeravanja
6. Kopirajte Workflow Secret

2. Konfigurirajte URL preusmjeravanja

Postavite URL na koji se korisnici vraćaju nakon dovršetka učitavanja:

https://vas-sustav.com/gotovo?id={submission_id}&ref={reference}&sig={signature}

Dostupna rezervirana mjesta

Rezervirano mjesto	Opis	Primjer
{submission_id}	Visiono ID slanja	pls_123
{unique_value}	Proslijeđena vrijednost jedinstvenog polja	ABC123
{reference}	Proslijeđena vanjska referenca	tiket-456
{photo_count}	Broj učitanih fotografija	5
{timestamp}	Unix vremenska oznaka	1705500000
{signature}	HMAC potpis za verifikaciju	abc123...

Generiranje potpisanih URL-ova

URL parametri

Param	Puni naziv	Opis	Obavezno
uv	unique_value	Jedinstveni identifikator	Da
src	source	Izvorni sustav	Da
ref	reference	Vanjska referenca	Da
ts	timestamp	Unix vremenska oznaka	Da
sig	signature	HMAC-SHA256 potpis	Da

Algoritam potpisa

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

PHP primjer

<?php

$workflowSecret = 'vas-workflow-secret';
$slug = 'izvjestaj-ostecenja';

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

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

// Izgradi 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/izvjestaj-ostecenja?uv=ABC123&src=zendesk&ref=tiket-456&ts=1705500000&sig=abc123...

JavaScript primjer

const crypto = require('crypto');

const workflowSecret = 'vas-workflow-secret';
const slug = 'izvjestaj-ostecenja';

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

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

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

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

Python primjer

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

workflow_secret = 'vas-workflow-secret'
slug = 'izvjestaj-ostecenja'

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

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

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

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

Validacija povratnog potpisa

Kada se korisnici preusmjere natrag, verificirajte potpis kako biste osigurali integritet podataka.

Primjer povratnog URL-a

https://vas-sustav.com/gotovo?sub=pls_123&ref=tiket-456&cnt=5&ts=1705500100&sig=def456...

Verifikacija potpisa

Povratni potpis se izračunava kao:

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

PHP verifikacija

<?php

$workflowSecret = 'vas-workflow-secret';

// Dohvati parametre iz preusmjeravanja
$submissionId = $_GET['sub'];
$uniqueValue = $_GET['uv'];
$reference = $_GET['ref'];
$photoCount = $_GET['cnt'];
$timestamp = $_GET['ts'];
$receivedSignature = $_GET['sig'];

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

if (hash_equals($expectedSignature, $receivedSignature)) {
    // Potpis valjan - obradi slanje
    echo "Fotografije uspješno poslane!";
} else {
    // Potpis nevažeći - odbij
    http_response_code(400);
    echo "Nevažeći potpis";
}

Istek linka

Potpisani URL-ovi istječu nakon 1 sat prema zadanim postavkama. Ovo sprječava:

• Ponovno korištenje starih linkova
• Replay napade
• Zastarjele podatke

Ako korisnik otvori istekli link, vidi stranicu greške "Link istekao".

Najbolje sigurnosne prakse

Zaštitite svoju tajnu

• Sigurno pohranite workflow secret
• Nikad ga ne izlažite u klijentskom kodu
• Periodički rotirajte tajne
• Koristite varijable okruženja

Validirajte vremenske oznake

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

Koristite HTTPS

Uvijek koristite HTTPS za:

• Vaše URL-ove preusmjeravanja
• Sve API pozive
• Webhook krajnje točke

Stranice grešaka

Korisnici mogu vidjeti stranice grešaka za:

Greška	Uzrok	Rješenje
Nedostaju parametri	URL-u nedostaju obavezni parametri	Provjerite generiranje URL-a
Nevažeći potpis	Potpis se ne podudara	Provjerite tajnu i algoritam
Link istekao	Vremenska oznaka > 1 sat stara	Generirajte novi link

Webhook integracija

Workflow Mode radi s webhooksima. Događaj submission.created uključuje:

{
  "event": "submission.created",
  "data": {
    "photo_request": {
      "id": "pr_123",
      "custom_slug": "izvjestaj-ostecenja"
    },
    "permanent_link_submission": {
      "id": "pls_456",
      "unique_field_value": "ABC123",
      "external_source": "zendesk",
      "external_reference": "tiket-456"
    }
  }
}

Slučajevi korištenja

Zendesk fotografije tiketa

1. Agent šalje korisniku potpisani link
2. Korisnik učitava fotografije oštećenja
3. Korisnik se preusmjerava natrag na tiket
4. Webhook ažurira tiket s fotografijama

Osigurateljni zahtjevi

1. Sustav zahtjeva generira potpisani link
2. Osiguranik dokumentira štetu
3. Preusmjerava se na potvrdu zahtjeva
4. Fotografije se automatski povezuju sa zahtjevom

Terenska služba

1. Tehničar prima radni nalog
2. Otvara potpisani link s mobitela
3. Dokumentira dovršeni posao
4. Preusmjerava se na stranicu završetka posla

Rješavanje problema

Nepodudaranje potpisa

1. Provjerite da tajna točno odgovara
2. Provjerite kodiranje parametara
3. Potvrdite format vremenske oznake
4. Osigurajte da je redoslijed payloada ispravan

Preusmjeravanje ne radi

1. Provjerite da je URL preusmjeravanja konfiguriran
2. Provjerite sintaksu rezerviranih mjesta
3. Potvrdite da je URL ispravno kodiran

Link istekao odmah

1. Provjerite sinkronizaciju vremena poslužitelja
2. Provjerite da je vremenska oznaka u Unix formatu
3. Osigurajte da je vremenska oznaka trenutna

Povezani resursi

• Trajni linkovi - Konfiguracija linkova
• Webhooks - Obavijesti o događajima
• API referenca - Potpuna API dokumentacija