Modo Workflow

Integra Visiono en flujos de trabajo externos con URLs firmadas seguras.

Descripción General

El Modo Workflow permite que sistemas externos integren la recolección de fotos de Visiono sin problemas en sus procesos. Los usuarios son redirigidos desde sistemas externos (como tickets de Zendesk o registros de CRM) a Visiono, completan la subida de fotos y son automáticamente redirigidos de vuelta con datos verificados.

Características Clave

Característica	Descripción
URLs Firmadas	Firma HMAC-SHA256 previene manipulación
Redirección Automática	Regreso al sistema externo después de completar
Campos Ocultos	Datos prellenados no visibles para usuarios
Seguimiento por Envío	Fuente externa y referencia almacenadas
Verificación de Firma	Verificar que datos de redirección no fueron modificados

Cómo Funciona

sequenceDiagram
    participant E as Sistema Externo
    participant V as Visiono
    participant U as Usuario

    E->>E: Generar URL firmada
    E->>U: Enviar enlace al usuario
    U->>V: Abrir URL firmada
    V->>V: Validar firma
    V->>U: Mostrar subida de fotos
    U->>V: Subir fotos
    V->>E: Redirigir con firma
    E->>E: Validar firma de retorno

Configuración

1. Habilitar Modo Workflow

1. Navega a tu Enlace Permanente
2. Haz clic en Editar
3. Expande la sección Modo Workflow
4. Habilita el interruptor Modo Workflow
5. Configura URL de redirección
6. Copia el Secreto de Workflow

2. Configurar URL de Redirección

Establece la URL a la que regresan los usuarios después de completar las subidas:

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

Marcadores Disponibles

Marcador	Descripción	Ejemplo
{submission_id}	ID de envío de Visiono	pls_123
{unique_value}	Valor de campo único pasado	ABC123
{reference}	Referencia externa pasada	ticket-456
{photo_count}	Número de fotos subidas	5
{timestamp}	Marca de tiempo Unix	1705500000
{signature}	Firma HMAC para verificación	abc123...

Generar URLs Firmadas

Parámetros de URL

Param	Nombre Largo	Descripción	Requerido
uv	unique_value	Identificador único	Sí
src	source	Sistema de origen	Sí
ref	reference	Referencia externa	Sí
ts	timestamp	Marca de tiempo Unix	Sí
sig	signature	Firma HMAC-SHA256	Sí

Algoritmo de Firma

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

Ejemplo PHP

<?php

$workflowSecret = 'tu-secreto-workflow';
$slug = 'reporte-daños';

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

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

// Construir 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/reporte-daños?uv=ABC123&src=zendesk&ref=ticket-456&ts=1705500000&sig=abc123...

Ejemplo JavaScript

const crypto = require('crypto');

const workflowSecret = 'tu-secreto-workflow';
const slug = 'reporte-daños';

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

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

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

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

Ejemplo Python

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

workflow_secret = 'tu-secreto-workflow'
slug = 'reporte-daños'

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

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

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

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

Validar Firma de Redirección

Cuando los usuarios son redirigidos de vuelta, verifica la firma para asegurar la integridad de los datos.

Ejemplo de URL de Retorno

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

Verificación de Firma

La firma de retorno se calcula como:

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

Verificación PHP

<?php

$workflowSecret = 'tu-secreto-workflow';

// Obtener parámetros de la redirección
$submissionId = $_GET['sub'];
$uniqueValue = $_GET['uv'];
$reference = $_GET['ref'];
$photoCount = $_GET['cnt'];
$timestamp = $_GET['ts'];
$receivedSignature = $_GET['sig'];

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

if (hash_equals($expectedSignature, $receivedSignature)) {
    // Firma válida - procesar el envío
    echo "¡Fotos enviadas exitosamente!";
} else {
    // Firma inválida - rechazar
    http_response_code(400);
    echo "Firma inválida";
}

Expiración del Enlace

Las URLs firmadas expiran después de 1 hora por defecto. Esto previene:

• Que enlaces antiguos sean reutilizados
• Ataques de repetición
• Datos obsoletos

Si un usuario abre un enlace expirado, ve una página de error "Enlace Expirado".

Mejores Prácticas de Seguridad

Protege Tu Secreto

• Almacena el secreto de workflow de forma segura
• Nunca lo expongas en código del lado del cliente
• Rota secretos periódicamente
• Usa variables de entorno

Valida Marcas de Tiempo

$maxAge = 3600; // 1 hora
if (time() - $timestamp > $maxAge) {
    // Enlace expirado
    return false;
}

Usa HTTPS

Siempre usa HTTPS para:

• Tus URLs de redirección
• Cualquier llamada API
• Endpoints de webhook

Páginas de Error

Los usuarios pueden ver páginas de error por:

Error	Causa	Solución
Parámetros Faltantes	URL carece de params requeridos	Verifica generación de URL
Firma Inválida	Firma no coincide	Verifica secreto y algoritmo
Enlace Expirado	Marca de tiempo > 1 hora	Genera nuevo enlace

Integración con Webhooks

El Modo Workflow funciona con webhooks. El evento submission.created incluye:

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

Casos de Uso

Fotos de Ticket de Zendesk

1. El agente envía enlace firmado al cliente
2. El cliente sube fotos de daños
3. El cliente es redirigido de vuelta al ticket
4. El webhook actualiza el ticket con fotos

Reclamos de Seguros

1. El sistema de reclamos genera enlace firmado
2. El asegurado documenta daños
3. Redirigido a confirmación de reclamo
4. Las fotos se vinculan automáticamente al reclamo

Servicio de Campo

1. El técnico recibe orden de trabajo
2. Abre enlace firmado desde móvil
3. Documenta trabajo completado
4. Redirigido a página de completar trabajo

Solución de Problemas

Discrepancia de Firma

1. Verifica que el secreto coincida exactamente
2. Comprueba la codificación de parámetros
3. Confirma formato de marca de tiempo
4. Asegura que el orden del payload sea correcto

Redirección No Funciona

1. Verifica que la URL de redirección esté configurada
2. Comprueba sintaxis de marcadores
3. Confirma que la URL esté correctamente codificada

Enlace Expiró Inmediatamente

1. Verifica sincronización de hora del servidor
2. Verifica que la marca de tiempo esté en formato Unix
3. Asegura que la marca de tiempo sea actual

Recursos Relacionados

• Enlaces Permanentes - Configuración de enlaces
• Webhooks - Notificaciones de eventos
• Referencia de API - Documentación completa de API