diff --git a/README.md b/README.md index 96a21af..da18bdf 100644 --- a/README.md +++ b/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: diff --git a/app/api/routes/invoices.py b/app/api/routes/invoices.py index 72ba538..e2b111a 100644 --- a/app/api/routes/invoices.py +++ b/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: