# POS (Point of Sale) API

## POS Session Management

### Open POS Session

**Endpoint:** `POST https://api.quick.myquickapp.com/sales`

#### Request Headers

```
Authorization: Bearer {api_key}
Content-Type: application/json
language: en
```

#### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "session",
  "type": "create",
  "pos_id": "POS-1",
  "cash_float": 1000.00
}
```

#### Response

```json
{
  "statusCode": 200,
  "headers": {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Headers": "*",
    "Access-Control-Allow-Methods": "GET,POST,OPTIONS"
  },
  "body": {
    "message": "Session opened",
    "session": {
      "id": 50001,
      "orgid": 12345,
      "userid": 123,
      "pos_id": "POS-1",
      "pos_status": "open",
      "opened_at": "2024-03-10T10:00:00",
      "closed_at": null,
      "cash_float": 1000.00,
      "total_sales": 0.00,
      "total_cash": 1000.00,
      "total_card": 0.00,
      "total_other": 0.00,
      "orders_count": 0
    }
  }
}
```

### List POS Sessions

#### Request Body

```json
{
  "org_id": "12345",
  "action": "session",
  "type": "list",
  "status_filter": "all",
  "search_query": "",
  "pos_id": ""
}
```

#### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "sessions": [
      {
        "id": 50001,
        "orgid": 12345,
        "pos_id": "POS-1",
        "pos_status": "open",
        "opened_at": "2024-03-10T10:00:00",
        "closed_at": null,
        "cash_float": 1000.00,
        "total_sales": 1150.00,
        "total_cash": 850.00,
        "total_card": 300.00,
        "orders_count": 2
      },
      {
        "id": 50002,
        "orgid": 12345,
        "pos_id": "POS-1",
        "pos_status": "closed",
        "opened_at": "2024-03-09T09:00:00",
        "closed_at": "2024-03-09T18:00:00",
        "cash_float": 1000.00,
        "total_sales": 2300.00,
        "total_cash": 1500.00,
        "total_card": 800.00,
        "orders_count": 5
      }
    ],
    "total_count": 2,
    "filtered_count": 2
  }
}
```

### Close POS Session

#### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "session",
  "type": "close",
  "session_id": 50001
}
```

#### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Session closed"
  }
}
```

---

## POS Orders

### Create POS Order

#### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "order",
  "type": "create",
  "session_id": 50001,
  "customer_id": 917013,
  "salesperson_id": 123,
  "warehouse_id": "wh_1",
  "location_id": "loc_1",
  "sales_journal_id": "journal_1",
  "payment_journal_id": "journal_2",
  "coa_account_id": "receivable_101",
  "items": [
    {
      "product_id": 201,
      "product_name": "Product Name",
      "description": "Product description",
      "quantity": 2,
      "price": 100.00,
      "discount": 0,
      "tax_rate": 15.0,
      "tax_included": true
    },
    {
      "product_id": 202,
      "product_name": "Another Product",
      "description": "Another description",
      "quantity": 1,
      "price": 50.00,
      "discount": 10,
      "tax_rate": 15.0,
      "tax_included": true
    }
  ],
  "payments": [
    {
      "method": "cash",
      "amount": 230.00,
      "reference": ""
    },
    {
      "method": "card",
      "amount": 0.00,
      "reference": "AUTH123"
    }
  ],
  "idempotency_key": "idem_1234567890abcdef",
  "amount_tendered": 230.00
}
```

#### Response - Success (200)

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Order processed successfully",
    "order": {
      "id": 60001,
      "orgid": 12345,
      "session_id": 50001,
      "customer_id": 917013,
      "pos_status": "completed",
      "subtotal": 250.00,
      "tax_total": 37.50,
      "discount_total": 5.00,
      "total": 282.50,
      "payment_pos_status": "paid",
      "total_paid": 282.50,
      "amount_tendered": 282.50,
      "change": 0.00,
      "payments": [
        {
          "method": "cash",
          "amount": 230.00
        },
        {
          "method": "card",
          "amount": 52.50,
          "reference": "AUTH123"
        }
      ]
    },
    "order_id": 60001,
    "order_number": "POS-60001",
    "receipt_number": "POS-60001"
  }
}
```

#### Response - Duplicate Detected

```json
{
  "statusCode": 200,
  "headers": {
    "X-Idempotency-Hit": "true"
  },
  "body": {
    "message": "Order already exists (duplicate detected)",
    "order": {
      "id": 60001,
      "orgid": 12345,
      ...
    },
    "duplicate_detected": true
  }
}
```

### List POS Orders

#### Request Body

```json
{
  "org_id": "12345",
  "action": "session",
  "type": "get",
  "session_id": 50001,
  "order_status_filter": "all",
  "include_line_items": true
}
```

#### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "session": {
      "id": 50001,
      "orgid": 12345,
      "pos_status": "open",
      ...
    },
    "total_orders": 2,
    "orders": [
      {
        "id": 60001,
        "orgid": 12345,
        "session_id": 50001,
        "customer_id": 917013,
        "pos_status": "completed",
        "total": 282.50,
        "created_at": "2024-03-10T10:30:00",
        "line_items": [
          {
            "id": 70001,
            "order_id": 60001,
            "product_id": 201,
            "description": "Product Name",
            "quantity": 2,
            "price": 100.00,
            "discount": 0,
            "tax_rate": 15.0,
            "total": 230.00
          },
          {
            "id": 70002,
            "order_id": 60001,
            "product_id": 202,
            "description": "Another Product",
            "quantity": 1,
            "price": 50.00,
            "discount": 10,
            "tax_rate": 15.0,
            "total": 52.50
          }
        ]
      }
    ]
  }
}
```

---

## POS Payment

### Process Payment

#### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "payment",
  "order_id": 60001,
  "payments": [
    {
      "method": "cash",
      "amount": 282.50
    }
  ],
  "payment_acquirer": "stripe"
}
```

#### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Payment processed successfully",
    "payment": {
      "id": 80001,
      "order_id": 60001,
      "amount": 282.50,
      "method": "cash",
      "status": "completed",
      "reference": "CASH-123"
    }
  }
}
```

---

## POS Product Lookup

### Get POS Products

#### Request Body

```json
{
  "org_id": "12345",
  "action": "load",
  "type": "products",
  "search": "",
  "category_id": ""
}
```

#### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "products": [
      {
        "id": 201,
        "name": "Product Name",
        "price": 100.00,
        "cost": 50.00,
        "stock": 100,
        "category": "Electronics",
        "sku": "PROD-001",
        "barcode": "1234567890123"
      }
    ]
  }
}
```

---

## POS Reports

### Get POS Dashboard Data

#### Request Body

```json
{
  "org_id": "12345",
  "action": "dashboard",
  "type": "summary",
  "date_from": "2024-03-01",
  "date_to": "2024-03-10",
  "pos_id": ""
}
```

#### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "summary": {
      "total_sales": 5000.00,
      "total_orders": 25,
      "total_cash": 3000.00,
      "total_card": 2000.00,
      "avg_order_value": 200.00,
      "total_tax": 750.00,
      "total_discount": 125.00
    },
    "by_pos": [
      {
        "pos_id": "POS-1",
        "sales": 3000.00,
        "orders": 15
      },
      {
        "pos_id": "POS-2",
        "sales": 2000.00,
        "orders": 10
      }
    ],
    "by_payment_method": [
      {
        "method": "cash",
        "amount": 3000.00,
        "count": 15
      },
      {
        "method": "card",
        "amount": 2000.00,
        "count": 10
      }
    ]
  }
}
```

---

## POS Config

### Get POS Config

#### Request Body

```json
{
  "org_id": "12345",
  "action": "config",
  "type": "get"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "config": {
      "pos_id": "POS-1",
      "org_id": 12345,
      "cashier_name": "John Doe",
      "receipt_printer": "local",
      "receipt_template": "classic",
      "auto_send_receipt": true,
      "auto_print_receipt": true,
      "allow_out_of_stock_sales": true,
      "require_manager_for_out_of_stock": false,
      "print_after_payment": true,
      "show_discount_field": true,
      "show_customer_field": true
    }
  }
}
```

### Update POS Config

#### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "config",
  "type": "update",
  "config": {
    "auto_send_receipt": false,
    "auto_print_receipt": true,
    "print_after_payment": true
  }
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Config updated successfully"
  }
}
```

---

## POS Cashup

### Create Cashup

#### Request Body

```json
{
  "org_id": "12345",
  "userid": "123",
  "action": "cashup",
  "type": "create",
  "session_id": 50001,
  "cash_expected": 1500.00,
  "cash_actual": 1500.00,
  "card_expected": 500.00,
  "card_actual": 500.00,
  "notes": "Daily cashup"
}
```

### Response

```json
{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "message": "Cashup created successfully",
    "cashup": {
      "id": 90001,
      "session_id": 50001,
      "cash_expected": 1500.00,
      "cash_actual": 1500.00,
      "card_expected": 500.00,
      "card_actual": 500.00,
      "difference": 0.00,
      "status": "completed"
    }
  }
}
```