Skip to main content

Rutas de Redirección

Endpoints para manejo de redirecciones de Bridge tras completar procesos.

1. Éxito en Bridge​

GET /bridge/success

Redirección exitosa después de firmar ToS en Bridge.

Query Parameters:

  • signed_agreement_id (string): ID del acuerdo firmado
  • user_token (string): Token de usuario

Ejemplo de URL:

GET /bridge/success?signed_agreement_id=agr_123&user_token=uuid-token-123

Comportamiento: Redirección automática a:

https://tu-frontend.com/registro-exitoso?customer_id=bridge_customer_123

2. Fallo en Bridge​

GET /bridge/failed

Redirección de fallo en Bridge.

Query Parameters (opcionales):

  • error (string): Código de error
  • message (string): Mensaje de error

Ejemplo de URL:

GET /bridge/failed?error=verification_failed&message=Documents rejected

Comportamiento: Redirección automática a:

https://tu-frontend.com/error?reason=bridge_verification_failed

🔄 Flujo de Redirección​

Proceso Exitoso​

  1. Usuario firma ToS en portal de Bridge
  2. Bridge redirecciona a /bridge/success con parámetros
  3. Backend procesa la información y actualiza estado
  4. Redirección final al frontend con datos del customer

Proceso Fallido​

  1. Error en Bridge (documentos rechazados, etc.)
  2. Bridge redirecciona a /bridge/failed con error
  3. Backend registra el fallo en logs
  4. Redirección final al frontend con mensaje de error

📋 Parámetros de Éxito​

signed_agreement_id​

  • Tipo: String
  • Descripción: ID único del acuerdo firmado
  • Ejemplo: agr_abc123def456
  • Uso: Verificar que el acuerdo se firmó correctamente

user_token​

  • Tipo: String (UUID)
  • Descripción: Token temporal del usuario
  • Ejemplo: 550e8400-e29b-41d4-a716-446655440000
  • Uso: Identificar al usuario y vincular con customer

📋 Parámetros de Error​

error​

  • Tipo: String
  • Valores comunes:
    • verification_failed - Verificación KYC fallida
    • documents_rejected - Documentos rechazados
    • invalid_data - Datos inválidos
    • timeout - Tiempo de sesión agotado

message​

  • Tipo: String
  • Descripción: Mensaje descriptivo del error
  • Ejemplo: "Documents do not meet verification requirements"

🏠 URLs de Frontend​

Configuración por Ambiente​

Producción​

const FRONTEND_URLS = {
  success: 'https://app.swapbits.com/onboarding/success',
  error: 'https://app.swapbits.com/onboarding/error'
};

Staging​

const FRONTEND_URLS = {
  success: 'https://staging.swapbits.com/onboarding/success',
  error: 'https://staging.swapbits.com/onboarding/error'
};

Desarrollo​

const FRONTEND_URLS = {
  success: 'http://localhost:3000/onboarding/success',
  error: 'http://localhost:3000/onboarding/error'
};

🔍 Procesamiento Backend​

Éxito - /bridge/success​

app.get('/bridge/success', async (req, res) => {
  try {
    const { signed_agreement_id, user_token } = req.query;
    
    // 1. Validar parámetros
    if (!signed_agreement_id || !user_token) {
      return res.redirect(`${FRONTEND_URL}/error?reason=invalid_params`);
    }
    
    // 2. Buscar usuario por token
    const user = await findUserByToken(user_token);
    if (!user) {
      return res.redirect(`${FRONTEND_URL}/error?reason=user_not_found`);
    }
    
    // 3. Obtener datos del customer en Bridge
    const customer = await bridge.getCustomerByAgreement(signed_agreement_id);
    
    // 4. Actualizar base de datos
    await updateUserBridgeCustomer(user.id, customer.id);
    
    // 5. Redireccionar al frontend
    res.redirect(`${FRONTEND_URL}/success?customer_id=${customer.id}`);
    
  } catch (error) {
    logger.error('Bridge success redirect failed:', error);
    res.redirect(`${FRONTEND_URL}/error?reason=processing_error`);
  }
});

Error - /bridge/failed​

app.get('/bridge/failed', (req, res) => {
  const { error, message } = req.query;
  
  // Log del error para debugging
  logger.warn('Bridge redirect failed:', { error, message });
  
  // Redireccionar con información del error
  const params = new URLSearchParams({
    reason: 'bridge_verification_failed',
    error_code: error || 'unknown',
    error_message: message || 'Verification failed'
  });
  
  res.redirect(`${FRONTEND_URL}/error?${params.toString()}`);
});

📱 Manejo en Frontend​

Página de Éxito​

// /onboarding/success
useEffect(() => {
  const urlParams = new URLSearchParams(window.location.search);
  const customerId = urlParams.get('customer_id');
  
  if (customerId) {
    // Actualizar estado de usuario
    setUserVerificationStatus('verified');
    
    // Mostrar mensaje de éxito
    showSuccessMessage('¡Verificación completada exitosamente!');
    
    // Redireccionar al dashboard
    setTimeout(() => {
      navigate('/dashboard');
    }, 3000);
  }
}, []);

Página de Error​

// /onboarding/error
useEffect(() => {
  const urlParams = new URLSearchParams(window.location.search);
  const reason = urlParams.get('reason');
  const errorCode = urlParams.get('error_code');
  
  // Mostrar mensaje de error específico
  const errorMessages = {
    verification_failed: 'No se pudo verificar tu identidad',
    documents_rejected: 'Los documentos fueron rechazados',
    timeout: 'El tiempo de verificación ha expirado'
  };
  
  showErrorMessage(errorMessages[errorCode] || 'Error en la verificación');
}, []);

⚠️ Errores Comunes​

Parámetros Faltantes​

  • Problema: URLs sin parámetros requeridos
  • Solución: Validar parámetros y redireccionar con error

Tokens Expirados​

  • Problema: user_token no válido o expirado
  • Solución: Generar nuevo ToS link

Customer No Encontrado​

  • Problema: signed_agreement_id inválido
  • Solución: Verificar configuración de Bridge

📝 Notas Importantes​

  • Las redirecciones son GET requests sin autenticación
  • Los tokens son de un solo uso y expiran
  • Siempre validar parámetros antes de procesar
  • Logs detallados para debugging de problemas
  • URLs de frontend configurables por ambiente