Integración de Servicios Externos en Mall-Cook: Pagos y Logística

Implementación de Funcionalidades Críticas en E-commerce

Mall-Cook se destaca como una solución low-code para la construcción visual de comercios electrónicos en múltiples plataformas, incluyendo H5 y mini-programas. Sin embargo, para operar un negocio real, es indispensable conectar servicios externos especializados. Este documento técnico detalla la metodología para integrar pasarelas de pago y sistemas de seguimiento logístico dentro de la arquitectura del platforma.

Necesidad de Conectividad Externa

Aunque la generación visual de interfaces simplifica el desarrollo frontend, los procesos transaccionales y de envío requieren infraestructura backend robusta. Las integraciones prioritarias incluyen:

Pasarelas de Pago: Procesamiento seguro mediante WeChat Pay, Alipay o银联.
Rastreo Logístico: Conexión con proveedores como SF Express, YTO o ZTO.
Notiifcaciones: Servicios SMS para validación y estados de orden.
Geolocalización: Mapas para cálculo de rutas y direcciones.

Estructura Interna del Proyecto

Para modificar o extender las capacidades de Mall-Cook, es crucial comprender la organización del código fuente. Los puntos de extensión principales son:

Editor Visual: Ubicado en packages/mall-cook-platform/src/components/.
Capa de Servicios: Definiciones de API en packages/mall-cook-platform/src/api/.
Gestión de Configuración: Archivos centrales en packages/mall-cook-platform/src/config/.
Plantillas Personalizadas: Esquemas extendibles en packages/mall-cook-platform/src/custom-schema-template/.

Estrategia de Integración de Pagos

1. Configuración de WeChat Pay

Para habilitar transacciones en mini-programas y web móvil, se deben definir las credenciales específicas. En lugar de hardcodear, se recomienda estructurar los datos de la siguiente manera:

// Configuración de credenciales de pago
const gatewaySettings = {
  providerId: 'wx_identifier_code',
  merchantCode: 'mch_identifier_code',
  secretKey: 'secure_api_key_value',
  callbackEndpoint: 'https://api.dominio.com/hooks/payment'
}

Posteriormente, se debe generar un componente Schema en packages/mall-cook-platform/src/custom-schema-template/components/, por ejemplo, TransactionHandler.vue.

La lógica de comunicación con el backend se encapsula en packages/mall-cook-platform/src/api/payment.js:

// Servicio de transacción
export const submitOrderTransaction = async (orderInfo) => {
  // Solicitud al servidor de pagos
  return request({ 
    url: "gateway/process", 
    method: "POST", 
    payload: orderInfo 
  })
}

2. Implementación de Alipay

Para entornos H5, Alipay es una opción estándar. Los requisitos incluyen la gestión de claves privadas, la configuración de URLs de notificación asíncrona y la integración del SDK oficial o llamadas directas a la API REST.

Conexión con Proveedores Logísticos

1. Uso de API de Kuainiao

Este agregador permite consultar estados de más de 100 compañías de envío. El flujo de trabajo implica:

Obtener las credenciales API (Key y Secret) desde el panel del proveedor.
Desarrollar un componente de rastreo dentro de Mall-Cook.
Implementar la capa de abstracción para las consultas de estado.

Se sugiere crear ShipmentTracker.vue en el directorio de componentes del template para visualizar el progreso del envío en tiempo real.

2. Integración Directa con SF Express

Para servicios premium, la conexión directa ofrece mayor control. La configuración básica requiere:

// Parámetros de conexión logística
const logisticsProvider = {
  partnerCode: 'client_identifier',
  verificationToken: 'security_token',
  endpointUrl: 'https://api.logistics-provider.com/v1'
}

Gestión Centralizada de Configuraciones

Archivo Unificado de Servicios

Para mantener la consistencia, todos los secretos y endpoints deben residir en un archivo maestro, por ejemplo, externalServices.config.js dentro de la carpeta de configuración:

export default {
  // Módulos de pago
  billing: {
    wechat: {
      active: true,
      credentials: { id: '', key: '' }
    },
    alipay: {
      active: true,
      credentials: { app: '', secret: '' }
    }
  },
  // Módulos de envío
  shipping: {
    aggregator: {
      active: true,
      keys: { appKey: '', appSecret: '' }
    },
    direct: {
      active: false,
      auth: { code: '', token: '' }
    }
  }
}

Variables de Entorno

Es vital separar las configuraciones de desarrollo y producción mediante archivos .env:

# .env.production
VUE_APP_PAY_CLIENT_ID=prod_id_value
VUE_APP_PAY_SECRET=prod_secret_value
VUE_APP_LOGISTICS_KEY=prod_logistics_key

Ejemplo Práctico: Componente de Acción de Pago

Paso 1: Desarrollo del Componente Vue

En packages/mall-cook-platform/src/custom-schema-template/components/, cree CheckoutAction.vue:

<template>
  <button 
    :class="uiClass" 
    @click="processCheckout"
  >
    {{ buttonLabel }}
  </button>
</template>

<script>
export default {
  name: 'CheckoutAction',
  props: {
    settings: {
      type: Object,
      default: () => ({})
    }
  },
  methods: {
    async processCheckout() {
      // Ejecutar lógica de transacción
      const response = await this.$api.billing.submit(this.settings.cartInfo)
      // Gestionar respuesta del servidor
    }
  }
}
</script>

Paso 2: Registro en el Sistema Schema

El componente debe ser declarado en el archivo de inicialización correspondiente para que el editor visual lo reconozca:

// CheckoutAction/initializing.js
export default {
  label: 'Botón de Pago',
  componentRef: 'CheckoutAction',
  defaults: {
    uiClass: 'btn-primary',
    buttonLabel: 'Finalizar Compra',
    cartInfo: {}
  }
}

Adaptación Multiplataforma

La integración debe considerar las restricciones de cada entorno:

Entorno Web (H5): Utiliza APIs estándar del navegador, permite redirecciones completas para pagos y consultas logísticas externas.
Mini-programas: Requiere el uso de SDKs nativos del host (ej. WeChat), priorizando sus métodos de pago integrados y componentes de mapa nativos para la logística.

Consideraciones de Seguridad y Rendimiento

Al manejar datos financieros y de usuarios, se deben aplicar las siguientes prácticas:

Protección de Secretos: Nunca exponer API Keys en el código frontend compilado.
Validación de Firmas: Implementar verificación de firma en todas las callbacks entrantes.
Gestión de Errores: Registrar fallos de transacción y reintentos de red de manera asíncrona.
Caché de Consultas: Almacenar temporalmente los estados de envío para minimizar llamadas a APIs de terceros.
Monitoreo: Configurar alertas para tiempos de respuesta elevados en servicios externos.

Etiquetas: mall-cook vue.js e-commerce api-integration low-code

Publicado el 8-18 11:18

Friki Work