Add status filter query parameter to GET /api/v1/invoices/ endpoint

README.md

@@ -77,6 +77,7 @@ This is a FastAPI application for generating and managing invoices. It allows yo
     - `skip`: Number of records to skip (default: 0)
     - `limit`: Maximum number of records to return (default: 100)
     - `fields`: Comma-separated list of fields to include in the response (e.g., "id,invoice_number,total_amount")
+    - `status`: Filter invoices by status (e.g., "PENDING", "PAID", "CANCELLED")
 - `GET /api/v1/invoices/{invoice_id}`: Get a specific invoice by ID
   - Query parameters:
     - `fields`: Comma-separated list of fields to include in the response (e.g., "id,invoice_number,total_amount")
@@ -138,16 +139,18 @@ Invoices are automatically assigned a unique invoice number with the format:
   - `YYYYMM` is the year and month (e.g., 202307 for July 2023)
   - `XXXXXX` is a random alphanumeric string
 
-## Field Filtering
+## Query Parameters
+
+### Field Filtering
 
 The API supports field filtering for GET operations. This allows clients to request only the specific fields they need, which can improve performance and reduce bandwidth usage.
 
-### How to Use Field Filtering:
+#### How to Use Field Filtering:
 
 1. Add a `fields` query parameter to GET requests
 2. Specify a comma-separated list of field names to include in the response
 
-### Example:
+#### Example:
 
 To get only the ID, invoice number, and total amount of invoices:
 ```
@@ -170,6 +173,27 @@ This would return:
 ]
 ```
 
+### Status Filtering
+
+The API supports filtering invoices by their status (PENDING, PAID, CANCELLED).
+
+#### How to Use Status Filtering:
+
+1. Add a `status` query parameter to the GET request
+2. Specify one of the allowed status values: "PENDING", "PAID", or "CANCELLED"
+
+#### Example:
+
+To get only paid invoices:
+```
+GET /api/v1/invoices?status=PAID
+```
+
+To combine with other parameters:
+```
+GET /api/v1/invoices?status=PENDING&fields=id,invoice_number,total_amount&limit=5
+```
+
 ### Available Fields:
 
 Invoices have the following fields that can be filtered:

app/api/routes/invoices.py

@@ -74,6 +74,7 @@ def get_invoices(
     skip: int = 0, 
     limit: int = 100, 
     fields: Optional[str] = None,
+    status: Optional[str] = None,
     db: Session = Depends(get_db)
 ):
     """
@@ -84,8 +85,27 @@ def get_invoices(
     - limit: Maximum number of records to return
     - fields: Comma-separated list of fields to include in the response (e.g., "id,invoice_number,total_amount")
              If not provided, all fields will be returned.
+    - status: Filter invoices by status (e.g., "PENDING", "PAID", "CANCELLED")
+             If not provided, all invoices regardless of status will be returned.
     """
-    invoices = db.query(Invoice).offset(skip).limit(limit).all()
+    # Build the query with filters
+    query = db.query(Invoice)
+    
+    # Apply status filter if provided
+    if status:
+        # Validate the status value
+        allowed_statuses = ["PENDING", "PAID", "CANCELLED"]
+        if status not in allowed_statuses:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Status must be one of {', '.join(allowed_statuses)}"
+            )
+        
+        # Apply the filter
+        query = query.filter(Invoice.status == status)
+    
+    # Apply pagination
+    invoices = query.offset(skip).limit(limit).all()
     
     # If fields parameter is provided, filter the response
     if fields: