tm_back/docs/examples/API_EXAMPLES.md

# API Examples

This document provides examples of how to interact with the Tender Management API using curl commands.

## Prerequisites

1. **Start MongoDB**:
   ```bash
   sudo systemctl start mongod
   ```

2. **Start the server**:
   ```bash
   make run
   ```

3. **Verify server is running**:
   ```bash
   curl http://localhost:8081/health
   ```

## Customer Management Examples

### 1. Register a New Customer (Admin Only)

```bash
curl -X POST http://localhost:8081/api/admin/customers/register \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "mobile": "+1234567890",
    "password": "securepassword123",
    "national_id": "123456789",
    "gender": "male",
    "birthdate": 631152000,
    "profile_image": "https://example.com/avatar.jpg"
  }'
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Customer registered successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "mobile": "+1234567890",
    "national_id": "123456789",
    "gender": "male",
    "birthdate": 631152000,
    "profile_image": "https://example.com/avatar.jpg",
    "status": "active",
    "is_verified": false,
    "created_at": 1703123456,
    "updated_at": 1703123456
  }
}
```

### 2. Customer Login

```bash
curl -X POST http://localhost:8081/api/customers/login \
  -H "Content-Type: application/json" \
  -d '{
    "email_or_mobile": "john@example.com",
    "password": "securepassword123"
  }'
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Login successful",
  "data": {
    "customer": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "full_name": "John Doe",
      "username": "johndoe",
      "email": "john@example.com",
      "mobile": "+1234567890",
      "national_id": "123456789",
      "gender": "male",
      "birthdate": 631152000,
      "profile_image": "https://example.com/avatar.jpg",
      "status": "active",
      "is_verified": false,
      "created_at": 1703123456,
      "updated_at": 1703123456
    },
    "access_token": "abc123def456",
    "refresh_token": "xyz789uvw012",
    "expires_at": 1703127056
  }
}
```

### 3. Get Customer Profile (Protected)

```bash
curl -X GET http://localhost:8081/api/customers/profile \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000"
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Profile retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "mobile": "+1234567890",
    "national_id": "123456789",
    "gender": "male",
    "birthdate": 631152000,
    "profile_image": "https://example.com/avatar.jpg",
    "status": "active",
    "is_verified": false,
    "created_at": 1703123456,
    "updated_at": 1703123456
  }
}
```

### 4. Update Customer Profile (Protected)

```bash
curl -X PUT http://localhost:8081/api/customers/profile \
  -H "Content-Type: application/json" \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "full_name": "John Smith",
    "profile_image": "https://example.com/new-avatar.jpg"
  }'
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Profile updated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "John Smith",
    "username": "johndoe",
    "email": "john@example.com",
    "mobile": "+1234567890",
    "national_id": "123456789",
    "gender": "male",
    "birthdate": 631152000,
    "profile_image": "https://example.com/new-avatar.jpg",
    "status": "active",
    "is_verified": false,
    "created_at": 1703123456,
    "updated_at": 1703123456
  }
}
```

### 5. Change Password (Protected)

```bash
curl -X PUT http://localhost:8081/api/customers/change-password \
  -H "Content-Type: application/json" \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "old_password": "securepassword123",
    "new_password": "newsecurepassword456"
  }'
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Password changed successfully",
  "data": null
}
```

### 6. Add Device Token (Protected)

```bash
curl -X POST http://localhost:8081/api/customers/device-token \
  -H "Content-Type: application/json" \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "device_token": "fcm_token_123456",
    "device_type": "android"
  }'
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Device token added successfully",
  "data": null
}
```

### 7. Remove Device Token (Protected)

```bash
curl -X DELETE http://localhost:8081/api/customers/device-token \
  -H "Content-Type: application/json" \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "device_token": "fcm_token_123456"
  }'
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Device token removed successfully",
  "data": null
}
```

### 8. Logout (Protected)

```bash
curl -X POST http://localhost:8081/api/customers/logout \
  -H "Content-Type: application/json" \
  -H "X-Customer-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "device_token": "fcm_token_123456"
  }'
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Logged out successfully",
  "data": null
}
```

## Admin Management Examples

### 9. List All Customers (Admin Only)

```bash
curl -X GET "http://localhost:8081/api/admin/customers?limit=10&offset=0&search=john&status=active" \
  -H "Content-Type: application/json"
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Customers retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "full_name": "John Smith",
      "username": "johndoe",
      "email": "john@example.com",
      "mobile": "+1234567890",
      "national_id": "123456789",
      "gender": "male",
      "birthdate": 631152000,
      "profile_image": "https://example.com/new-avatar.jpg",
      "status": "active",
      "is_verified": false,
      "created_at": 1703123456,
      "updated_at": 1703123456
    }
  ],
  "meta": {
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}
```

### 10. Get Customer by ID (Admin Only)

```bash
curl -X GET http://localhost:8081/api/admin/customers/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json"
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Customer retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "John Smith",
    "username": "johndoe",
    "email": "john@example.com",
    "mobile": "+1234567890",
    "national_id": "123456789",
    "gender": "male",
    "birthdate": 631152000,
    "profile_image": "https://example.com/new-avatar.jpg",
    "status": "active",
    "is_verified": false,
    "created_at": 1703123456,
    "updated_at": 1703123456
  }
}
```

### 11. Update Customer Status (Admin Only)

```bash
curl -X PUT http://localhost:8081/api/admin/customers/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Content-Type: application/json" \
  -d '{
    "status": "suspended"
  }'
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Customer status updated successfully",
  "data": null
}
```

### 12. Get All Device Tokens (Admin Only)

```bash
curl -X GET http://localhost:8081/api/admin/customers/device-tokens \
  -H "Content-Type: application/json"
```

**Expected Response**:
```json
{
  "success": true,
  "message": "Device tokens retrieved successfully",
  "data": [
    {
      "token": "fcm_token_123456",
      "device_type": "android",
      "customer_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}
```

## Error Examples

### 13. Invalid Email Format

```bash
curl -X POST http://localhost:8081/api/admin/customers/register \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "John Doe",
    "username": "johndoe",
    "email": "invalid-email",
    "mobile": "+1234567890",
    "password": "securepassword123"
  }'
```

**Expected Response**:
```json
{
  "success": false,
  "message": "Validation failed",
  "error": "Email: invalid-email does not validate as email"
}
```

### 14. Duplicate Email

```bash
curl -X POST http://localhost:8081/api/admin/customers/register \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Jane Doe",
    "username": "janedoe",
    "email": "john@example.com",
    "mobile": "+1234567891",
    "password": "securepassword123"
  }'
```

**Expected Response**:
```json
{
  "success": false,
  "message": "email already exists",
  "error": "email already exists"
}
```

### 15. Invalid Authentication

```bash
curl -X GET http://localhost:8081/api/customers/profile
```

**Expected Response**:
```json
{
  "success": false,
  "message": "Invalid authentication",
  "error": "Missing customer ID"
}
```

## Testing Script

You can use the following script to test all endpoints:

```bash
#!/bin/bash

BASE_URL="http://localhost:8081"

echo "Testing Tender Management API..."

# Test health endpoint
echo "1. Testing health endpoint..."
curl -s "$BASE_URL/health" | jq .

# Register a customer
echo "2. Registering a customer..."
CUSTOMER_RESPONSE=$(curl -s -X POST "$BASE_URL/api/admin/customers/register" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Test User",
    "username": "testuser",
    "email": "test@example.com",
    "mobile": "+1234567890",
    "password": "password123"
  }')

echo "$CUSTOMER_RESPONSE" | jq .

# Extract customer ID
CUSTOMER_ID=$(echo "$CUSTOMER_RESPONSE" | jq -r '.data.id')

if [ "$CUSTOMER_ID" != "null" ]; then
    echo "Customer ID: $CUSTOMER_ID"
    
    # Test login
    echo "3. Testing login..."
    curl -s -X POST "$BASE_URL/api/customers/login" \
      -H "Content-Type: application/json" \
      -d '{
        "email_or_mobile": "test@example.com",
        "password": "password123"
      }' | jq .
    
    # Test get profile
    echo "4. Testing get profile..."
    curl -s -X GET "$BASE_URL/api/customers/profile" \
      -H "X-Customer-ID: $CUSTOMER_ID" | jq .
    
    # Test list customers (admin)
    echo "5. Testing list customers..."
    curl -s -X GET "$BASE_URL/api/admin/customers" | jq .
fi

echo "Testing completed!"
```

## Notes

1. **Authentication**: Currently using a simple header-based authentication (`X-Customer-ID`). In production, this should be replaced with proper JWT token validation.

2. **Timestamps**: All timestamps are Unix timestamps (int64) for consistency.

3. **Validation**: All requests are validated using govalidator with custom validation rules.

4. **Error Handling**: All errors return consistent JSON responses with appropriate HTTP status codes.

5. **CORS**: The server is configured to allow all origins for development. Configure properly for production.