# POS System API Documentation ## Base URL All URLs referenced in the documentation have the following base: ``` http://localhost:8000/api/v1 ``` ## Authentication Most endpoints require authentication. Use the following endpoint to obtain a JWT token: ### Login for Access Token ``` POST /token ``` **Request Body:** ```json { "username": "string", "password": "string" } ``` **Response:** ```json { "access_token": "string", "token_type": "bearer" } ``` Use the received token in the Authorization header for subsequent requests: ``` Authorization: Bearer ``` ## Items ### Create a new item ``` POST /items ``` **Request Body:** ```json { "name": "string", "price": 0, "quantity": 0, "unit": "string", "related_items": ["string"] } ``` **Response:** ```json { "id": "string", "name": "string", "price": 0, "quantity": 0, "unit": "string", "related_items": ["string"] } ``` ### Get all items ``` GET /items ``` **Query Parameters:** - `skip` (optional): number of items to skip - `limit` (optional): maximum number of items to return **Response:** ```json [ { "id": "string", "name": "string", "price": 0, "quantity": 0, "unit": "string", "related_items": ["string"] } ] ``` ### Get a specific item ``` GET /items/{item_id} ``` **Response:** ```json { "id": "string", "name": "string", "price": 0, "quantity": 0, "unit": "string", "related_items": ["string"] } ``` ### Update an item ``` PUT /items/{item_id} ``` **Request Body:** ```json { "name": "string", "price": 0, "quantity": 0, "unit": "string", "related_items": ["string"] } ``` **Response:** ```json { "id": "string", "name": "string", "price": 0, "quantity": 0, "unit": "string", "related_items": ["string"] } ``` ### Delete an item ``` DELETE /items/{item_id} ``` **Response:** ```json { "message": "Item successfully deleted" } ``` ## Orders ### Create a new order ``` POST /orders ``` **Request Body:** ```json { "user_id": "string", "items": [ { "item_id": "string", "quantity": 0, "price_at_order": 0 } ], "total_amount": 0, "payment_method": "string", "notes": "string" } ``` **Response:** ```json { "id": "string", "user_id": "string", "items": [ { "item_id": "string", "quantity": 0, "price_at_order": 0 } ], "total_amount": 0, "payment_method": "string", "payment_status": "string", "order_status": "string", "created_at": "string", "updated_at": "string", "discount_applied": 0, "notes": "string" } ``` ### Get all orders ``` GET /orders ``` **Query Parameters:** - `skip` (optional): number of orders to skip - `limit` (optional): maximum number of orders to return **Response:** ```json [ { "id": "string", "user_id": "string", "items": [ { "item_id": "string", "quantity": 0, "price_at_order": 0 } ], "total_amount": 0, "payment_method": "string", "payment_status": "string", "order_status": "string", "created_at": "string", "updated_at": "string", "discount_applied": 0, "notes": "string" } ] ``` ### Get a specific order ``` GET /orders/{order_id} ``` **Response:** ```json { "id": "string", "user_id": "string", "items": [ { "item_id": "string", "quantity": 0, "price_at_order": 0 } ], "total_amount": 0, "payment_method": "string", "payment_status": "string", "order_status": "string", "created_at": "string", "updated_at": "string", "discount_applied": 0, "notes": "string" } ``` ### Update an order ``` PUT /orders/{order_id} ``` **Request Body:** ```json { "items": [ { "item_id": "string", "quantity": 0, "price_at_order": 0 } ], "total_amount": 0, "payment_method": "string", "payment_status": "string", "order_status": "string", "discount_applied": 0, "notes": "string" } ``` **Response:** ```json { "id": "string", "user_id": "string", "items": [ { "item_id": "string", "quantity": 0, "price_at_order": 0 } ], "total_amount": 0, "payment_method": "string", "payment_status": "string", "order_status": "string", "created_at": "string", "updated_at": "string", "discount_applied": 0, "notes": "string" } ``` ### Delete an order ``` DELETE /orders/{order_id} ``` **Response:** ```json { "message": "Order successfully deleted" } ``` ### Process payment for an order ``` POST /orders/{order_id}/process_payment ``` **Request Body:** ```json { "payment_method": "string" } ``` **Response:** ```json { "message": "Payment processed successfully" } ``` ### Apply discount to an order ``` POST /orders/{order_id}/apply_discount ``` **Request Body:** ```json { "discount_percentage": 0 } ``` **Response:** ```json { "id": "string", "total_amount": 0, "discount_applied": 0 } ``` ## Users ### Register a new user ``` POST /users ``` **Request Body:** ```json { "username": "string", "email": "string", "full_name": "string", "password": "string" } ``` **Response:** ```json { "id": "string", "username": "string", "email": "string", "full_name": "string", "is_active": true, "is_superuser": false } ``` ### Get current user ``` GET /users/me ``` **Response:** ```json { "id": "string", "username": "string", "email": "string", "full_name": "string", "is_active": true, "is_superuser": false } ``` ### Get all users ``` GET /users ``` **Query Parameters:** - `skip` (optional): number of users to skip - `limit` (optional): maximum number of users to return **Response:** ```json [ { "id": "string", "username": "string", "email": "string", "full_name": "string", "is_active": true, "is_superuser": false } ] ``` ### Update a user ``` PUT /users/{user_id} ``` **Request Body:** ```json { "email": "string", "full_name": "string", "password": "string", "is_active": true, "is_superuser": false } ``` **Response:** ```json { "id": "string", "username": "string", "email": "string", "full_name": "string", "is_active": true, "is_superuser": false } ``` ### Delete a user ``` DELETE /users/{user_id} ``` **Response:** ```json { "message": "User successfully deleted" } ``` ## Error Responses All endpoints can return the following error responses: - 400 Bad Request - 401 Unauthorized - 403 Forbidden - 404 Not Found - 422 Unprocessable Entity - 500 Internal Server Error Error response body: ```json { "detail": "Error message" } ``` ```mermaid graph TD subgraph Authentication B[Authentication] B --> B1["POST /token"] end subgraph Items C[Items] C --> C1["POST /items"] C --> C2["GET /items"] C --> C3["GET /items/:item_id"] C --> C4["PUT /items/:item_id"] C --> C5["DELETE /items/:item_id"] end subgraph Orders D[Orders] D --> D1["POST /orders"] D --> D2["GET /orders"] D --> D3["GET /orders/:order_id"] D --> D4["PUT /orders/:order_id"] D --> D5["DELETE /orders/:order_id"] D --> D6["POST /orders/:order_id/process_payment"] D --> D7["POST /orders/:order_id/apply_discount"] end subgraph Users E[Users] E --> E1["POST /users"] E --> E2["GET /users/me"] E --> E3["GET /users"] E --> E4["PUT /users/:user_id"] E --> E5["DELETE /users/:user_id"] end class A main; class B auth; class C items; class D orders; class E users; ``` | Category | Method | Route | Description | |----------|--------|-------|-------------| | **Authentication** | POST | `/token` | Obtain JWT access token | | **Items** | POST | `/items` | Create a new item | | | GET | `/items` | Get all items | | | GET | `/items/{item_id}` | Get a specific item | | | PUT | `/items/{item_id}` | Update an item | | | DELETE | `/items/{item_id}` | Delete an item | | **Orders** | POST | `/orders` | Create a new order | | | GET | `/orders` | Get all orders | | | GET | `/orders/{order_id}` | Get a specific order | | | PUT | `/orders/{order_id}` | Update an order | | | DELETE | `/orders/{order_id}` | Delete an order | | | POST | `/orders/{order_id}/process_payment` | Process payment for an order | | | POST | `/orders/{order_id}/apply_discount` | Apply discount to an order | | **Users** | POST | `/users` | Register a new user | | | GET | `/users/me` | Get current user | | | GET | `/users` | Get all users | | | PUT | `/users/{user_id}` | Update a user | | | DELETE | `/users/{user_id}` | Delete a user |