point-of-sales/py-kivy/API.md

# 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 <access_token>
```

## 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 |