# Postman Testing Guide for BuySellService API

## 📥 How to Import the Collection

1. **Open Postman**
2. Click **Import** button (top left)
3. Select **File** tab
4. Choose `BuySellService_API.postman_collection.json`
5. Click **Import**

The collection will appear in your Postman sidebar with all endpoints organized by category.

## 🚀 Quick Start Testing

### Step 1: Create a User (Required First Step)

Before creating listings or locations, you need to create a user:

1. Go to **Users** → **Create User**
2. The request body is pre-filled with the UUID from your error: `aaf295cb-a19e-4179-a2df-31c0c64ea9f4`
3. Click **Send**
4. You should get a 201 response with the created user

**Request Body:**
```json
{
    "id": "aaf295cb-a19e-4179-a2df-31c0c64ea9f4",
    "name": "Test User",
    "phone_number": "+919876543210",
    "avatar_url": null,
    "language": "en",
    "timezone": "Asia/Kolkata",
    "country_code": "+91"
}
```

### Step 2: Get Species and Breeds

Before creating a listing, you need to know the UUIDs of species and breeds:

1. Go to **Listings** → **Get Species**
2. Click **Send** - This will show you all available species with their UUIDs
3. Copy a species UUID
4. Go to **Listings** → **Get Breeds**
5. Add the species UUID as a query parameter: `?species_id=your-species-uuid`
6. Click **Send** - This will show breeds for that species
7. Copy a breed UUID

### Step 3: Create a Location (Optional)

1. Go to **Locations** → **Create Location**
2. Update the `user_id` in the request body to your user UUID
3. Modify other fields as needed
4. Click **Send**

### Step 4: Create a Listing

1. Go to **Listings** → **Create Listing**
2. Update the request body:
   - `seller_id`: Use your user UUID
   - `species_id`: Use the species UUID from Step 2
   - `breed_id`: Use the breed UUID from Step 2
3. Click **Send**

## 📋 Endpoint Categories

### 👤 Users
- **Create User** - Create a new user (with optional UUID)
- **Get All Users** - List all users
- **Get User by ID** - Get specific user details
- **Update User** - Update user information

### 📋 Listings
- **Get All Listings** - List all active listings
- **Get Listing by ID** - Get specific listing with full details
- **Create Listing** - Create a new listing with animal details
- **Update Listing** - Update listing information
- **Search Listings** - Search by text query
- **Near Me Search** - Find listings near coordinates
- **Get Species** - Get all available species
- **Get Breeds** - Get all breeds (optionally filtered by species)

### 📍 Locations
- **Create Location** - Create a location (user_id optional for captured locations)
- **Get User Locations** - Get all locations for a user
- **Get Location by ID** - Get specific location
- **Update Location** - Update location information

### 💬 Chat
- **Create/Get Conversation** - Create or get existing conversation
- **Get User Conversations** - Get all conversations for a user
- **Get Messages** - Get messages in a conversation
- **Send Message** - Send a message

## 🔧 Important Notes

### UUIDs Required
- All IDs in this API are **UUIDs**, not integers
- Make sure to use valid UUID format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

### User ID Requirements
- **For Listings**: `seller_id` must exist in users table
- **For Locations**: 
  - `user_id` is **optional** if `is_saved_address = false` (captured location)
  - `user_id` is **required** if `is_saved_address = true` (saved address)

### Testing Order
1. ✅ Create User first
2. ✅ Get Species and Breeds
3. ✅ Create Location (optional)
4. ✅ Create Listing

## 🐛 Common Errors

### "User does not exist"
- **Solution**: Create the user first using the **Create User** endpoint

### "Invalid input syntax for type uuid"
- **Solution**: Make sure you're using UUIDs, not integers. Check species_id and breed_id are UUIDs.

### "Foreign key constraint violation"
- **Solution**: Ensure all referenced IDs (user_id, species_id, breed_id) exist in their respective tables

## 💡 Tips

1. **Use Environment Variables**: Create a Postman environment with:
   - `baseUrl`: `http://localhost:3200`
   - `userId`: Your user UUID
   - `speciesId`: A species UUID
   - `breedId`: A breed UUID

2. **Save Responses**: After creating resources, save the returned UUIDs for use in other requests

3. **Test in Order**: Follow the testing order above to avoid foreign key errors

4. **Check Server**: Make sure your server is running on port 3200 before testing

## 🔗 Base URL

All endpoints use: `http://localhost:3200`

If your server runs on a different port, update the base URL in the collection variables.