Loomix
DocumentaciónGuía para DesarrolladoresFuncionalidades Locales y Pasarelas Regionales

🇮🇷 Guía Completa de Características Regionales y Locales (Iran Features)

El proyecto Next-Strapi-Medusa ofrece soporte integrado de nivel empresarial para infraestructuras comerciales locales. Al habilitar la variable ENABLE_IRAN_FEATURES=true, se activan el acceso mediante número móvil y SMS OTP, pasarelas bancarias locales (Zarinpal), cálculo de tarifas de envío en tiempo real y conversión de precios a moneda local sin alterar el núcleo de Medusa.

Soporte Nativo sin Modificar el Núcleo de Medusa
Todos los módulos locales (pasarela de pago, SMS OTP y envíos postales) están diseñados como módulos aislados según los estándares de Medusa v2, garantizando actualizaciones limpias sin incompatibilidades.

1. Bandera Global ENABLE_IRAN_FEATURES

Para activar todas las características regionales en todo el stack (Medusa backend, Strapi CMS y Next.js Storefront), define las siguientes variables en tus archivos .env y docker-compose.yml:

.env
env
ENABLE_IRAN_FEATURES=true
NEXT_PUBLIC_ENABLE_IRAN_FEATURES=true
DEFAULT_REGION=IR
DEFAULT_LOCALE=fa-IR

2. Acceso con Número Móvil y SMS OTP (Phone Auth & OTP)

El módulo dedicado de autenticación telefónica se implementa en store-admin/src/modules/auth/providers/otp. Normaliza números de teléfono, genera códigos temporales seguros de 4 a 6 dígitos e incorpora limitación de tasa.

  • Soporte multiformato: Acepta automáticamente 0912xxxxxxx y +98912xxxxxxx.
  • Temporizador de cuenta regresiva y rate limiting: Previene solicitudes repetidas de SMS con un enfriamiento de 120 segundos.
  • Registro Automático: Crea automáticamente una cuenta de cliente para nuevos números verificados.
store-admin/medusa-config.ts (sección phone-auth)
typescript
{
  resolve: "./src/modules/auth/providers/otp",
  id: "phone-auth",
  options: {
    jwtSecret: process.env.JWT_SECRET,
  },
}

3. Pasarelas de SMS (Kavenegar & SMS.ir)

El servicio de envío de SMS admite patrones rápidos por webhook para entregar códigos en menos de 5 segundos:

.env (Configuración de Pasarela SMS)
env
# Proveedor: sms-ir o kavenegar
SMS_PROVIDER=sms-ir
SMS_API_KEY=tu_clave_api_sms
SMS_OTP_TEMPLATE_ID=100000 # ID plantilla de código de verificación
SMS_ORDER_PLACED_TEMPLATE_ID=200000 # ID plantilla de confirmación de pedido

4. Pasarela de Pago Online Zarinpal

El módulo Zarinpal se integra directamente con el sistema de sesiones de pago de Medusa, permitiendo transacciones bancarias seguras con soporte para modo de pruebas (Sandbox):

.env (Ajustes de Zarinpal)
env
ZARINPAL_MERCHANT_ID=tu-merchant-id-xxxx-xxxx
ZARINPAL_SANDBOX=false # Configura en true en desarrollo

5. Cálculo de Envíos en Tiempo Real (Fulfillment)

El plugin medusa-fulfillment-iran-post calcula tarifas de envío estándar y exprés durante el checkout según origen, destino y peso del paquete, admitiendo códigos de seguimiento de 24 dígitos en el panel de pedidos.

store-admin/medusa-config.ts (sección módulo de envíos)
typescript
{
  resolve: "./src/modules/fulfillment/providers/iran-post",
  id: "iran-post",
  options: {
    originProvince: "تهران",
    originCity: "تهران",
    defaultPackagingWeight: 150, // گرم
  },
}

6. Conversión Inteligente de Moneda (convertToToman)

Los precios se almacenan en la unidad mínima en la base de datos. En Strapi, al activar la opción convertToToman en Storefront Settings, el frontend elimina un cero y formatea los números con separadores de miles.

Conversión de precios en frontend (store/src/lib/util/prices.ts)
typescript
export function formatPrice(amount: number, currencyCode: string, convertToToman = false) {
  if (currencyCode.toLowerCase() === 'irr' && convertToToman) {
    const tomanAmount = Math.round(amount / 10);
    return `${new Intl.NumberFormat('fa-IR').format(tomanAmount)} تومان`;
  }
  return new Intl.NumberFormat('fa-IR', { style: 'currency', currency: currencyCode }).format(amount);
}