🛒 Toko API (Headless E-Commerce Backend)

Enterprise-grade, Headless E-Commerce API built with Laravel 12. Designed for high performance, strict type safety, and resilience using modern software architecture patterns.

---

🌟 Key Features

🏗️ Advanced Architecture

• Layered Pattern: Separation of concerns via Controllers, Actions, Services, and DTOs.
• Data Transfer Objects (DTO): Implemented via spatie/laravel-data for strict request validation and type safety.
• Decoupled Integrations: Payment and Shipping logic are isolated behind Interfaces, making vendor switching seamless (e.g., Midtrans -> Xendit).
• Static Analysis: Code quality enforced by Larastan (Level 5) and Laravel Pint.

💰 Commerce Engine

• Atomic Checkout: Uses DB::Transaction and lockForUpdate to prevent race conditions during high traffic.
• Payment Gateway: Seamless integration with Midtrans (Snap Token support).
• Dynamic Shipping: Integrated with RajaOngkir service.
• Discount System: Coupon engine supporting Fixed/Percentage logic with quota validation.
• Tiered Pricing: Special pricing rules for Agents and Partners.

🛡️ Resilience & Performance

• Circuit Breaker Pattern: Protects the application from crashing when external APIs (RajaOngkir/Midtrans) are down/slow.
• Redis Caching: High-performance caching for product listings and settings.
• Rate Limiting: Throttle protection for auth and high-risk endpoints.

📈 SEO & Engagement

• Auto Sitemap: Dynamic /sitemap.xml endpoint for search engines.
• Rich Meta Data: Products API includes meta_title, meta_description, og_image, and JSON-LD Schema.
• Verified Reviews: Anti-spam review system ensuring only paid customers can rate products.

---

🛠️ Tech Stack

• Framework: Laravel 12
• Language: PHP 8.2+
• Database: MySQL 8
• Queue Driver: Database (Default for Dev) / Redis (Production)
• Cache: File (Default for Dev) / Redis (Production)
• External Services:
  • Payment: Midtrans
  • Shipping: RajaOngkir
  • Mail: SMTP / Mailpit (Dev)

---

⚙️ Installation Guide

Prerequisites

• PHP >= 8.2
• Composer
• Redis Server
• MySQL

Setup

1. Clone Repository

   git clone https://github.com/Leuthra/toko-api.git
   cd toko-api

2. Install Dependencies

   composer install

3. Environment Config

   cp .env.example .env
   php artisan key:generate

4. Configure Database & Redis (.env)

   DB_CONNECTION=mysql
   DB_DATABASE=toko_db
   
   CACHE_STORE=redis
   REDIS_CLIENT=predis

5. Set API Keys (.env)

   # Midtrans
   MIDTRANS_SERVER_KEY=your-server-key
   MIDTRANS_IS_PRODUCTION=false
   
   # RajaOngkir
   RAJAONGKIR_API_KEY=your-api-key
   RAJAONGKIR_ORIGIN_CITY_ID=153  # Store Origin City ID

6. Migrate & Seed

   php artisan migrate --seed

7. Link Storage

   php artisan storage:link

8. Run Queue Worker (Crucial!) You must run this command in a separate terminal to process background emails.

   php artisan queue:work

9. Run Server

   php artisan serve

---

🧪 Testing The API

1. Check Shipping (Circuit Breaker Test)

Endpoint to check shipping costs securely.

POST /api/v1/shipping/cost
{
    "destination_city_id": 114, // Denpasar
    "weight": 1000,
    "courier": "jne"
}

2. Checkout Order (DTO Test)

Complete flow with coupon and payment token generation.

POST /api/v1/checkout
{
    "items": [
        { "product_id": 1, "qty": 1 }
    ],
    "shipping_courier": "jne",
    "shipping_service": "REG",
    "shipping_cost": 22000,
    "user_address_id": 1,
    "coupon_code": "MERDEKA45"
}

Note: After checkout, check your worker terminal. It should process

App\Mail\OrderInvoiceMail

---

🔒 Security

If you discover any security related issues, please email romidev20@gmail.com instead of using the issue tracker.

📝 License

The MIT License (MIT).