cswine
/
point-of-sales
1
1
Fork 0
Code Issues 2 Pull Requests Packages Projects 1 Releases Wiki Activity
point-of-sales/py-kivy/API.md

8.4 KiB
Raw Permalink Blame History

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

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