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:

{
  "username": "string",
  "password": "string"
}

Response:

{
  "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:

{
  "name": "string",
  "price": 0,
  "quantity": 0,
  "unit": "string",
  "related_items": ["string"]
}

Response:

{
  "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:

[
  {
    "id": "string",
    "name": "string",
    "price": 0,
    "quantity": 0,
    "unit": "string",
    "related_items": ["string"]
  }
]

Get a specific item

GET /items/{item_id}

Response:

{
  "id": "string",
  "name": "string",
  "price": 0,
  "quantity": 0,
  "unit": "string",
  "related_items": ["string"]
}

Update an item

PUT /items/{item_id}

Request Body:

{
  "name": "string",
  "price": 0,
  "quantity": 0,
  "unit": "string",
  "related_items": ["string"]
}

Response:

{
  "id": "string",
  "name": "string",
  "price": 0,
  "quantity": 0,
  "unit": "string",
  "related_items": ["string"]
}

Delete an item

DELETE /items/{item_id}

Response:

{
  "message": "Item successfully deleted"
}

Orders

Create a new order

POST /orders

Request Body:

{
  "user_id": "string",
  "items": [
    {
      "item_id": "string",
      "quantity": 0,
      "price_at_order": 0
    }
  ],
  "total_amount": 0,
  "payment_method": "string",
  "notes": "string"
}

Response:

{
  "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:

[
  {
    "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:

{
  "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:

{
  "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:

{
  "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:

{
  "message": "Order successfully deleted"
}

Process payment for an order

POST /orders/{order_id}/process_payment

Request Body:

{
  "payment_method": "string"
}

Response:

{
  "message": "Payment processed successfully"
}

Apply discount to an order

POST /orders/{order_id}/apply_discount

Request Body:

{
  "discount_percentage": 0
}

Response:

{
  "id": "string",
  "total_amount": 0,
  "discount_applied": 0
}

Users

Register a new user

POST /users

Request Body:

{
  "username": "string",
  "email": "string",
  "full_name": "string",
  "password": "string"
}

Response:

{
  "id": "string",
  "username": "string",
  "email": "string",
  "full_name": "string",
  "is_active": true,
  "is_superuser": false
}

Get current user

GET /users/me

Response:

{
  "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:

[
  {
    "id": "string",
    "username": "string",
    "email": "string",
    "full_name": "string",
    "is_active": true,
    "is_superuser": false
  }
]

Update a user

PUT /users/{user_id}

Request Body:

{
  "email": "string",
  "full_name": "string",
  "password": "string",
  "is_active": true,
  "is_superuser": false
}

Response:

{
  "id": "string",
  "username": "string",
  "email": "string",
  "full_name": "string",
  "is_active": true,
  "is_superuser": false
}

Delete a user

DELETE /users/{user_id}

Response:

{
  "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:

{
  "detail": "Error message"
}