# API Documentation

## Base URL

```
https://your-domain.com/api/v1
```

## Authentication

All API requests require authentication via Bearer token:

```bash
curl -H "Authorization: Bearer {your-token}" \
     -H "Content-Type: application/json" \
     https://your-domain.com/api/v1/endpoint
```

### Login

```http
POST /api/v1/login
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "password"
}
```

**Response:**
```json
{
    "success": true,
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "user": {
            "id": 1,
            "name": "Admin User",
            "email": "user@example.com"
        }
    }
}
```

### Logout

```http
POST /api/v1/logout
Authorization: Bearer {token}
```

## Dashboard

### Get Dashboard Statistics

```http
GET /api/v1/dashboard/stats
Authorization: Bearer {token}
```

**Response:**
```json
{
    "success": true,
    "data": {
        "total_orders": 1250,
        "pending_orders": 45,
        "total_revenue": 1250000.00,
        "monthly_revenue": 125000.00,
        "active_customers": 320,
        "pending_invoices": 28
    }
}
```

## Orders

### List Orders

```http
GET /api/v1/orders?page=1&per_page=15&status=pending
Authorization: Bearer {token}
```

**Parameters:**
- `page` (integer): Page number
- `per_page` (integer): Items per page (max 100)
- `status` (string): Filter by status (pending, processing, shipped, delivered, cancelled)
- `search` (string): Search by order number or customer name
- `sort` (string): Sort field (created_at, order_number, total_amount)
- `order` (string): Sort direction (asc, desc)

**Response:**
```json
{
    "success": true,
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "order_number": "ORD-2025-00001",
                "customer_id": 15,
                "customer_name": "ABC Corporation",
                "status": "pending",
                "total_amount": 25000.00,
                "currency": "USD",
                "created_at": "2025-01-15T10:30:00Z"
            }
        ],
        "total": 1250,
        "per_page": 15
    }
}
```

### Get Order

```http
GET /api/v1/orders/{id}
Authorization: Bearer {token}
```

**Response:**
```json
{
    "success": true,
    "data": {
        "id": 1,
        "order_number": "ORD-2025-00001",
        "customer": {
            "id": 15,
            "name": "ABC Corporation",
            "email": "abc@corporation.com"
        },
        "items": [
            {
                "id": 1,
                "product_id": 10,
                "product_name": "Industrial Widget",
                "quantity": 100,
                "unit_price": 250.00,
                "total": 25000.00
            }
        ],
        "status": "pending",
        "total_amount": 25000.00,
        "notes": "Urgent delivery required",
        "created_at": "2025-01-15T10:30:00Z"
    }
}
```

### Create Order

```http
POST /api/v1/orders
Authorization: Bearer {token}
Content-Type: application/json

{
    "customer_id": 15,
    "items": [
        {
            "product_id": 10,
            "quantity": 100,
            "unit_price": 250.00
        }
    ],
    "notes": "Urgent delivery required"
}
```

**Response:**
```json
{
    "success": true,
    "data": {
        "id": 2,
        "order_number": "ORD-2025-00002",
        "status": "pending",
        "total_amount": 25000.00
    },
    "message": "Order created successfully"
}
```

### Update Order

```http
PUT /api/v1/orders/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
    "status": "processing",
    "notes": "Updated notes"
}
```

### Delete Order

```http
DELETE /api/v1/orders/{id}
Authorization: Bearer {token}
```

## Invoices

### List Invoices

```http
GET /api/v1/invoices?page=1&per_page=15&status=unpaid
Authorization: Bearer {token}
```

### Get Invoice

```http
GET /api/v1/invoices/{id}
Authorization: Bearer {token}
```

### Create Invoice

```http
POST /api/v1/invoices
Authorization: Bearer {token}
Content-Type: application/json

{
    "order_id": 1,
    "due_date": "2025-02-15",
    "items": [
        {
            "description": "Product shipment",
            "amount": 25000.00
        }
    ]
}
```

### Send Invoice

```http
POST /api/v1/invoices/{id}/send
Authorization: Bearer {token}
```

### Mark Invoice as Paid

```http
POST /api/v1/invoices/{id}/pay
Authorization: Bearer {token}
Content-Type: application/json

{
    "payment_method": "bank_transfer",
    "payment_date": "2025-01-20",
    "reference_number": "TXN-123456"
}
```

## Products

### List Products

```http
GET /api/v1/products?page=1&per_page=15&category=electronics
Authorization: Bearer {token}
```

### Get Product

```http
GET /api/v1/products/{id}
Authorization: Bearer {token}
```

### Create Product

```http
POST /api/v1/products
Authorization: Bearer {token}
Content-Type: application/json

{
    "name": "Industrial Widget",
    "sku": "IW-001",
    "description": "High-quality industrial widget",
    "category": "electronics",
    "price": 250.00,
    "currency": "USD",
    "stock_quantity": 500,
    "unit": "piece"
}
```

### Update Product

```http
PUT /api/v1/products/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
    "price": 275.00,
    "stock_quantity": 450
}
```

### Delete Product

```http
DELETE /api/v1/products/{id}
Authorization: Bearer {token}
```

## Customers

### List Customers

```http
GET /api/v1/customers?page=1&per_page=15&search=abc
Authorization: Bearer {token}
```

### Get Customer

```http
GET /api/v1/customers/{id}
Authorization: Bearer {token}
```

### Create Customer

```http
POST /api/v1/customers
Authorization: Bearer {token}
Content-Type: application/json

{
    "name": "ABC Corporation",
    "email": "abc@corporation.com",
    "phone": "+1-555-0123",
    "address": {
        "street": "123 Main St",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "postal_code": "10001"
    },
    "tax_id": "US-123456789",
    "payment_terms": "net_30"
}
```

### Update Customer

```http
PUT /api/v1/customers/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
    "phone": "+1-555-0456",
    "payment_terms": "net_60"
}
```

### Delete Customer

```http
DELETE /api/v1/customers/{id}
Authorization: Bearer {token}
```

## Suppliers

### List Suppliers

```http
GET /api/v1/suppliers?page=1&per_page=15
Authorization: Bearer {token}
```

### Get Supplier

```http
GET /api/v1/suppliers/{id}
Authorization: Bearer {token}
```

### Create Supplier

```http
POST /api/v1/suppliers
Authorization: Bearer {token}
Content-Type: application/json

{
    "name": "Global Manufacturing Ltd",
    "email": "contact@globalmfg.com",
    "phone": "+86-10-12345678",
    "address": {
        "street": "456 Industrial Ave",
        "city": "Shanghai",
        "country": "CN",
        "postal_code": "200001"
    },
    "lead_time_days": 14,
    "payment_terms": "net_45"
}
```

## Shipping

### List Shipments

```http
GET /api/v1/shipments?page=1&per_page=15&status=in_transit
Authorization: Bearer {token}
```

### Get Shipment

```http
GET /api/v1/shipments/{id}
Authorization: Bearer {token}
```

### Create Shipment

```http
POST /api/v1/shipments
Authorization: Bearer {token}
Content-Type: application/json

{
    "order_id": 1,
    "carrier": "FedEx",
    "tracking_number": "FX123456789",
    "estimated_delivery": "2025-01-25",
    "items": [
        {
            "product_id": 10,
            "quantity": 100
        }
    ]
}
```

### Update Shipment Status

```http
PUT /api/v1/shipments/{id}/status
Authorization: Bearer {token}
Content-Type: application/json

{
    "status": "delivered",
    "actual_delivery": "2025-01-24",
    "notes": "Delivered to front desk"
}
```

## Documents

### List Documents

```http
GET /api/v1/documents?category=invoices&type=pdf
Authorization: Bearer {token}
```

### Upload Document

```http
POST /api/v1/documents
Authorization: Bearer {token}
Content-Type: multipart/form-data

{
    "file": [binary],
    "category": "invoices",
    "type": "pdf",
    "related_type": "App\\Models\\Invoice",
    "related_id": 1
}
```

### Download Document

```http
GET /api/v1/documents/{id}/download
Authorization: Bearer {token}
```

### Delete Document

```http
DELETE /api/v1/documents/{id}
Authorization: Bearer {token}
```

## Reports

### Sales Report

```http
GET /api/v1/reports/sales?start_date=2025-01-01&end_date=2025-01-31&group_by=day
Authorization: Bearer {token}
```

**Response:**
```json
{
    "success": true,
    "data": {
        "period": {
            "start": "2025-01-01",
            "end": "2025-01-31"
        },
        "total_sales": 500000.00,
        "total_orders": 150,
        "average_order_value": 3333.33,
        "data": [
            {
                "date": "2025-01-01",
                "sales": 25000.00,
                "orders": 8
            }
        ]
    }
}
```

### Inventory Report

```http
GET /api/v1/reports/inventory?category=electronics
Authorization: Bearer {token}
```

### Customer Report

```http
GET /api/v1/reports/customers?start_date=2025-01-01&end_date=2025-01-31
Authorization: Bearer {token}
```

### Financial Report

```http
GET /api/v1/reports/financial?period=monthly
Authorization: Bearer {token}
```

## Settings

### Get Settings

```http
GET /api/v1/settings
Authorization: Bearer {token}
```

### Update Settings

```http
PUT /api/v1/settings
Authorization: Bearer {token}
Content-Type: application/json

{
    "company_name": "EXIM ERP",
    "currency": "USD",
    "timezone": "America/New_York",
    "email_notifications": true
}
```

## Error Responses

### 400 Bad Request

```json
{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Validation failed",
        "details": {
            "email": ["The email field is required."],
            "password": ["The password must be at least 8 characters."]
        }
    }
}
```

### 401 Unauthorized

```json
{
    "success": false,
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Invalid or expired token"
    }
}
```

### 403 Forbidden

```json
{
    "success": false,
    "error": {
        "code": "FORBIDDEN",
        "message": "You do not have permission to perform this action"
    }
}
```

### 404 Not Found

```json
{
    "success": false,
    "error": {
        "code": "NOT_FOUND",
        "message": "Resource not found"
    }
}
```

### 422 Unprocessable Entity

```json
{
    "success": false,
    "error": {
        "code": "UNPROCESSABLE_ENTITY",
        "message": "The given data was invalid",
        "details": {
            "email": ["The email has already been taken."]
        }
    }
}
```

### 429 Too Many Requests

```json
{
    "success": false,
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests, please try again later"
    }
}
```

### 500 Internal Server Error

```json
{
    "success": false,
    "error": {
        "code": "SERVER_ERROR",
        "message": "An unexpected error occurred"
    }
}
```

## Rate Limiting

API requests are limited to:

- **Authenticated users**: 60 requests per minute
- **Unauthenticated users**: 30 requests per minute

Rate limit headers are included in responses:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995200
```

## Pagination

List endpoints support pagination:

```json
{
    "current_page": 1,
    "data": [...],
    "first_page_url": "https://your-domain.com/api/v1/orders?page=1",
    "from": 1,
    "last_page": 50,
    "last_page_url": "https://your-domain.com/api/v1/orders?page=50",
    "next_page_url": "https://your-domain.com/api/v1/orders?page=2",
    "path": "/api/v1/orders",
    "per_page": 15,
    "prev_page_url": null,
    "to": 15,
    "total": 750
}
```

## Filtering

Most list endpoints support filtering:

```bash
# Filter by status
GET /api/v1/orders?status=pending

# Search
GET /api/v1/orders?search=ORD-2025

# Date range
GET /api/v1/orders?start_date=2025-01-01&end_date=2025-01-31

# Multiple filters
GET /api/v1/orders?status=pending&customer_id=15&start_date=2025-01-01
```

## Sorting

```bash
# Sort by field
GET /api/v1/orders?sort=created_at&order=desc

# Sort by multiple fields
GET /api/v1/orders?sort=created_at,total_amount&order=desc,asc
```