🛒 Online Store API - Laravel

Complete REST API for an online store with categories, products, and invoicing system.

📋 Overview

A fully functional e-commerce API built with Laravel featuring:

• Hierarchical Categories - Unlimited parent/child category relationships
• Product Management - Complete CRUD with inventory tracking
• Invoice System - Automatic price calculation and stock management
• No Authentication - Direct API access (orders via WhatsApp as per requirements)

✨ Features

• ✅ RESTful API architecture
• ✅ Parent/Child category relationships
• ✅ Automatic inventory management
• ✅ Auto-generated invoice numbers
• ✅ Search and filtering
• ✅ Pagination support
• ✅ Comprehensive validation
• ✅ API Resources for clean responses
• ✅ Database seeding with sample data
• ✅ Complete Postman collection

🚀 Quick Start

Installation

# Install dependencies
composer install

# Run migrations
php artisan migrate

# Seed the database with sample data
php artisan db:seed

# Start the server
php artisan serve

The API will be available at: http://127.0.0.1:8000

📚 Documentation

• API Documentation - Complete API reference
• Quick Start Guide (Arabic) - دليل البدء السريع بالعربية
• cURL Examples - Ready-to-use cURL commands
• Postman Collection - Import into Postman

🗂️ Database Schema

Categories

- id
- name
- description
- parent_id (nullable, self-referencing)
- timestamps

Products

- id
- name
- description
- price
- amount (inventory)
- unit (piece, kg, liter, etc.)
- category_id
- image (nullable)
- is_active
- timestamps

Invoices

- id
- invoice_number (auto-generated: INV-YYYYMMDD-0001)
- customer_name
- customer_phone
- customer_address
- total_price (auto-calculated)
- notes
- status (pending, confirmed, completed, cancelled)
- invoice_date
- timestamps

Invoice Items

- id
- invoice_id
- product_id
- quantity
- unit_price
- total_price
- timestamps

🔌 API Endpoints

Categories

GET    /api/v1/categories          - List all categories
GET    /api/v1/categories/{id}     - Get single category
POST   /api/v1/categories          - Create category
PUT    /api/v1/categories/{id}     - Update category
DELETE /api/v1/categories/{id}     - Delete category

Products

GET    /api/v1/products                      - List all products
GET    /api/v1/products?category_id=1        - Filter by category
GET    /api/v1/products?search=phone         - Search products
GET    /api/v1/products?is_active=1          - Filter active products
GET    /api/v1/products/{id}                 - Get single product
POST   /api/v1/products                      - Create product
PUT    /api/v1/products/{id}                 - Update product
DELETE /api/v1/products/{id}                 - Delete product

Invoices

GET    /api/v1/invoices                      - List all invoices
GET    /api/v1/invoices?status=pending       - Filter by status
GET    /api/v1/invoices?date_from=2025-01-01 - Filter by date
GET    /api/v1/invoices?search=john          - Search invoices
GET    /api/v1/invoices/{id}                 - Get single invoice
POST   /api/v1/invoices                      - Create invoice
PUT    /api/v1/invoices/{id}                 - Update invoice
DELETE /api/v1/invoices/{id}                 - Delete invoice

📦 Sample Data

After running php artisan db:seed, you'll have:

Categories:

• Electronics (with Phones, Laptops, Accessories)
• Clothing (with Men, Women)
• Food & Beverages (with Snacks, Beverages)
• Home & Garden

Products:

• 12 products across different categories
• Including iPhones, Laptops, Clothing, Food items, etc.

🧪 Testing with Postman

1. Open Postman
2. Import postman_collection.json
3. All endpoints ready to test!

The collection includes:

• ✅ All CRUD operations
• ✅ Search and filtering examples
• ✅ Complete invoice creation workflow
• ✅ Pre-configured base URL

💡 Example Usage

Create an Invoice

POST /api/v1/invoices
Content-Type: application/json

{
    "customer_name": "John Doe",
    "customer_phone": "+1234567890",
    "customer_address": "123 Main St",
    "invoice_date": "2025-12-27",
    "items": [
        {
            "product_id": 1,
            "quantity": 2
        },
        {
            "product_id": 5,
            "quantity": 1
        }
    ]
}

What happens:

• ✅ Invoice number auto-generated (e.g., INV-20251227-0001)
• ✅ Prices calculated from product prices
• ✅ Total price calculated automatically
• ✅ Inventory reduced for each product
• ✅ Stock validation before processing

🔄 Inventory Management

Automatic Stock Updates

• Creating invoice: Stock is automatically reduced
• Deleting invoice: Stock is automatically restored
• Validation: Prevents orders exceeding available stock

🌟 Key Features Explained

Hierarchical Categories

Categories can have unlimited nested subcategories:

Electronics (parent)
├── Phones (child)
├── Laptops (child)
└── Accessories (child)

Auto-Generated Invoice Numbers

Format: INV-YYYYMMDD-XXXX

• Date-based numbering
• Auto-increments daily
• Unique per invoice

Smart Filtering

Products and invoices support multiple filters:

/api/v1/products?category_id=1&is_active=1&search=phone&per_page=20

🛠️ Technology Stack

• Framework: Laravel 11
• PHP: 8.2+
• Database: SQLite (easily changeable to MySQL/PostgreSQL)
• API: RESTful with JSON responses

📱 Integration Notes

As per requirements, this API is designed to work with:

• WhatsApp order forwarding
• No built-in authentication (can be added later)
• Direct API access from frontend/mobile apps

🤝 Contributing

Feel free to fork and contribute! This is an open-source project.

📄 License

This project is open-sourced software licensed under the MIT license.

---

Built with ❤️ using Laravel