Način delovnega toka

Integrirajte Visiono v zunanje delovne tokove z varnimi podpisanimi URL-ji.

Pregled

Način delovnega toka omogoča zunanjim sistemom, da nemoteno vgradijo zbiranje fotografij Visiono v svoje procese. Uporabniki so preusmerjeni iz zunanjih sistemov (kot so Zendesk zahtevki ali CRM zapisi) v Visiono, dokončajo nalaganje fotografij in so samodejno preusmerjeni nazaj s preverjenimi podatki.

Ključne funkcije

Funkcija	Opis
Podpisani URL-ji	HMAC-SHA256 podpis preprečuje spreminjanje
Samodejna preusmeritev	Vrnitev v zunanji sistem po zaključku
Skrita polja	Vnaprej izpolnjeni podatki niso vidni uporabnikom
Sledenje po oddaji	Shranjen zunanji vir in referenca
Preverjanje podpisa	Preverite, da podatki preusmeritve niso bili spremenjeni

Kako deluje

sequenceDiagram
    participant E as Zunanji sistem
    participant V as Visiono
    participant U as Uporabnik

    E->>E: Ustvari podpisan URL
    E->>U: Pošlje povezavo uporabniku
    U->>V: Odpre podpisan URL
    V->>V: Preveri podpis
    V->>U: Prikaže nalaganje fotografij
    U->>V: Naloži fotografije
    V->>E: Preusmeritev s podpisom
    E->>E: Preveri povratni podpis

Konfiguracija

1. Omogočite način delovnega toka

1. Pojdite na svojo trajno povezavo
2. Kliknite Uredi
3. Razširite razdelek Način delovnega toka
4. Omogočite stikalo Način delovnega toka
5. Konfigurirajte URL preusmeritve
6. Kopirajte Skrivnost delovnega toka

2. Konfigurirajte URL preusmeritve

Nastavite URL, kamor se uporabniki vrnejo po zaključku nalaganja:

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

Razpoložljive označbe mest

Označba mesta	Opis	Primer
{submission_id}	Visiono ID oddaje	pls_123
{unique_value}	Vrednost edinstvenega polja	ABC123
{reference}	Zunanja referenca	ticket-456
{photo_count}	Število naloženih fotografij	5
{timestamp}	Unix časovni žig	1705500000
{signature}	HMAC podpis za preverjanje	abc123...

Generiranje podpisanih URL-jev

URL parametri

Param	Dolgo ime	Opis	Obvezno
uv	unique_value	Edinstveni identifikator	Da
src	source	Izvorni sistem	Da
ref	reference	Zunanja referenca	Da
ts	timestamp	Unix časovni žig	Da
sig	signature	HMAC-SHA256 podpis	Da

Algoritem podpisa

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

PHP primer

<?php

$workflowSecret = 'vasa-skrivnost-delovnega-toka';
$slug = 'porocilo-poskodbe';

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

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

// Sestavi 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/porocilo-poskodbe?uv=ABC123&src=zendesk&ref=ticket-456&ts=1705500000&sig=abc123...

JavaScript primer

const crypto = require('crypto');

const workflowSecret = 'vasa-skrivnost-delovnega-toka';
const slug = 'porocilo-poskodbe';

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

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

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

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

Python primer

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

workflow_secret = 'vasa-skrivnost-delovnega-toka'
slug = 'porocilo-poskodbe'

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

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

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

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

Preverjanje podpisa preusmeritve

Ko so uporabniki preusmerjeni nazaj, preverite podpis za zagotovitev celovitosti podatkov.

Primer povratnega URL-ja

https://vas-sistem.com/koncano?sub=pls_123&ref=ticket-456&cnt=5&ts=1705500100&sig=def456...

Preverjanje podpisa

Povratni podpis se izračuna kot:

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

PHP preverjanje

<?php

$workflowSecret = 'vasa-skrivnost-delovnega-toka';

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

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

if (hash_equals($expectedSignature, $receivedSignature)) {
    // Podpis veljaven - obdelaj oddajo
    echo "Fotografije uspešno oddane!";
} else {
    // Podpis neveljaven - zavrni
    http_response_code(400);
    echo "Neveljaven podpis";
}

Potek veljavnosti povezave

Podpisani URL-ji privzeto potečejo po 1 uri. To preprečuje:

• Ponovno uporabo starih povezav
• Napade s ponovitvijo
• Zastarele podatke

Če uporabnik odpre poteklo povezavo, vidi stran z napako "Povezava potekla".

Varnostne najboljše prakse

Zaščitite svojo skrivnost

• Varno shranite skrivnost delovnega toka
• Nikoli je ne izpostavljajte v kodi na strani odjemalca
• Periodično rotirajte skrivnosti
• Uporabite spremenljivke okolja

Preverjajte časovne žige

$maxAge = 3600; // 1 ura
if (time() - $timestamp > $maxAge) {
    // Povezava potekla
    return false;
}

Uporabite HTTPS

Vedno uporabljajte HTTPS za:

• Vaše URL-je preusmeritev
• Vse API klice
• Webhook naslove

Strani z napakami

Uporabniki lahko vidijo strani z napakami za:

Napaka	Vzrok	Rešitev
Manjkajoči parametri	URL nima obveznih parametrov	Preverite generiranje URL-ja
Neveljaven podpis	Podpis se ne ujema	Preverite skrivnost in algoritem
Povezava potekla	Časovni žig > 1 ura star	Ustvarite novo povezavo

Integracija z webhooks

Način delovnega toka deluje z webhooks. Dogodek submission.created vključuje:

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

Primeri uporabe

Zendesk fotografije zahtevkov

1. Agent pošlje stranki podpisano povezavo
2. Stranka naloži fotografije poškodbe
3. Stranka je preusmerjena nazaj na zahtevek
4. Webhook posodobi zahtevek s fotografijami

Zavarovalni zahtevki

1. Sistem zahtevkov ustvari podpisano povezavo
2. Zavarovanec dokumentira poškodbo
3. Preusmerjen na potrditev zahtevka
4. Fotografije samodejno povezane z zahtevkom

Terenska služba

1. Tehnik prejme delovni nalog
2. Odpre podpisano povezavo z mobilne naprave
3. Dokumentira opravljeno delo
4. Preusmerjen na stran zaključka dela

Odpravljanje težav

Neujemanje podpisa

1. Preverite, ali se skrivnost natančno ujema
2. Preverite kodiranje parametrov
3. Potrdite format časovnega žiga
4. Zagotovite, da je vrstni red vsebine pravilen

Preusmeritev ne deluje

1. Preverite, ali je URL preusmeritve konfiguriran
2. Preverite sintakso označb mest
3. Potrdite, da je URL pravilno kodiran

Povezava takoj poteče

1. Preverite sinhronizacijo časa strežnika
2. Preverite, ali je časovni žig v Unix formatu
3. Zagotovite, da je časovni žig aktualen

Povezani viri

• Trajne povezave - Konfiguracija povezave
• Webhooks - Obvestila o dogodkih
• API referenca - Celotna API dokumentacija