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
    A[API v1] --> B[Authentication]
    A --> C[Items]
    A --> D[Orders]
    A --> E[Users]

    B --> B1["POST /token"]

    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"]

    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"]

    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"]

    class A main;
    class B auth;
    class C items;
    class D orders;
    class E users;
```