E-commerce Platform

​

Overview

​

Customer Shopping Flow

​

Product Catalog

​

Browsing Experience

// Search implementation uses fuzzy matching
filterProductsByQuery(products, searchQuery)

const categories = ['Todos', ...new Set(products.map(p => p.categoria))];

const [viewMode, setViewMode] = useState<'grid' | 'list'>(
  window.innerWidth < 768 ? 'list' : 'grid'
);

​

Product Information

• Product image gallery
• Name and variant (e.g., “10ml”, “30ml”)
• Price in Colombian Pesos (COP)
• Benefits and category
• Stock availability status
• “Add to Cart” or “Out of Stock” button

​

Shopping Cart

​

Cart Management

const addToCart = (product: Product, variant: Variant, quantity: number) => {
  // Validates stock availability
  // Updates cart state
  // Persists to localStorage
}

localStorage.setItem('kaiu_cart', JSON.stringify(cartItems));

​

Cart Visibility

• Item count badge
• Slide-out drawer with full cart contents
• Running total
• Quick access to checkout

​

Checkout Process

​

Form Validation

// Name validation
if (!/^[a-zA-ZñÑáéíóúÁÉÍÓÚ\s]+$/.test(value)) 
  return "Solo letras y espacios.";
if (value.trim().split(/\s+/).length < 2) 
  return "Ingresa Nombre y Apellido.";

// Phone validation (Colombian mobile)
if (!/^3\d{9}$/.test(value)) 
  return "Debe ser celular (3xx) de 10 dígitos.";

// Email validation
if (!/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(value)) 
  return "Email inválido";

​

Shipping Calculation

1. Customer selects city → System captures:
   • Department code
   • City code
   • Destination coordinates
2. API quote request → Sends:
   {
     "city_code": "11001",
     "subdivision_code": "11",
     "line_items": [
       {
         "unit_price": 50000,
         "quantity": 1,
         "weight": 0.2,
         "dimensions": { "height": 10, "width": 10, "length": 10 }
       }
     ],
     "payment_method_code": "COD"
   }
   
3. Receives shipping cost → Displays final total

​

Payment Methods

if (orderData.payment_method_code === 'COD') {
  await InventoryService.confirmSale(orderData.line_items);
  
  // Send COD confirmation email
  const mockTransaction = {
    id: `COD-${shipmentId}`,
    status: 'PENDING_PAYMENT_ON_DELIVERY',
    payment_method: { type: 'PAGO_CONTRA_ENTREGA' }
  };
  
  sendOrderConfirmation(emailOrderPayload, mockTransaction);
}

const signRes = await fetch('/api/wompi/sign', {
  method: 'POST',
  body: JSON.stringify({
    reference: `KAIU-${orderId}`,
    amount: amountInCents,
    currency: "COP"
  })
});

// Form auto-submitted to Wompi
form.submit();

​

Order Confirmation

1. Order ID generated → Readable PIN format (e.g., #1050)
2. Confirmation email sent → Includes:
   • Order details and items
   • Shipping address
   • Total breakdown
   • Tracking information (when available)
3. Success page displayed → Shows order number and next steps
4. Cart cleared → Ready for next purchase

​

Order Tracking

​

Customer Tracking Portal

• Order PIN (readable ID)
• Tracking number (from carrier)
• Database ID (UUID)

• Order status (Pending, Shipped, Delivered, etc.)
• Creation date
• Carrier name
• Tracking number with clickable link
• Order total

const translateStatus = (status: string) => {
  const map: Record<string, string> = {
    'PENDING': 'Pendiente',
    'APPROVED': 'Aprobado',
    'PREPARING': 'En Preparación',
    'SHIPPED': 'En Tránsito (Enviado)',
    'DELIVERED': 'Entregado',
    'CANCELLED': 'Cancelado'
  };
  return map[status?.toUpperCase()] || status;
};

​

Auto-tracking Links

https://kaiu.com.co/rastreo?guide=568139

• Email links that auto-search
• QR codes on shipping labels
• Customer support quick-links

​

Inventory Integration

​

Stock Reservation System

await InventoryService.reserveStock(orderData.line_items);

await InventoryService.releaseReserve(orderData.line_items);

​

Real-time Availability

• Frontend polls inventory status
• “Out of Stock” badges appear automatically
• Cart validation prevents checkout with unavailable items

​

Order Processing Backend

​

Complete Order Flow

1. Validation → Zod schema validation of all fields
2. Stock Check → Reserve inventory or fail fast
3. Database Entry → Create order record with PENDING status
4. Logistics API → Create shipment with carrier
5. Update Order → Add tracking info and external IDs
6. Payment Handling → Process based on method (COD vs Online)
7. Notifications → Send confirmation emails

try {
  shipmentData = await LogisticsManager.createShipment(payload);
} catch (logisticsError) {
  // Cancel order in database
  await prisma.order.update({
    where: { id: dbOrder.id },
    data: { status: 'CANCELLED' }
  });
  
  // Release reserved stock
  await InventoryService.releaseReserve(orderData.line_items);
  
  return res.status(502).json({ error: 'Error creating shipment' });
}

const logisticsPayload = {
  ...orderData,
  external_order_id: String(dbOrder.readableId)
};

​

Key Features

localStorage.setItem('kaiu_checkout_data', JSON.stringify(formData));

/catalogo?categoria=Aceites+Esenciales&q=lavanda

​

API Endpoints

​

Related Features