> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jethings.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Status API

> Retrieve status counts for stock, sales, and purchase operations

# Status API

The Status API allows you to retrieve status counts for different operational areas of your optical store. This endpoint provides aggregated counts for stock management, sales operations, and purchase operations.

## Endpoint Details

**Base URL:** `https://joptic.jethings.com`

### Required Headers

```
x-store-id: <store_id>
Authorization: Bearer <token>
```

***

## Get Status

### Endpoint

**Endpoint:** `GET /status/:type`

### Path Parameters

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `type`    | string | Yes      | Status type: stock, buy, or sell |

### Type Enum Values

The `type` parameter accepts one of the following values:

* `stock` - Returns counts for stock-related entities (items, item variants, brands, warehouses, products)
* `sell` - Returns counts for sales-related entities (customers, customer groups, sales invoices, price lists, item prices)
* `buy` - Returns counts for purchase-related entities (suppliers, supplier groups, purchase invoices, purchase orders, price lists, item prices)

<Note>
  The type parameter must be one of: stock, buy, or sell. Any other value will result in a validation error.
</Note>

***

## Get Status Examples

### Example 1: Get Stock Status

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://joptic.jethings.com/status/stock" \
    -H "x-store-id: your-store-id" \
    -H "Authorization: Bearer <token>"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://joptic.jethings.com/status/stock", {
    method: "GET",
    headers: {
      "x-store-id": "your-store-id",
      Authorization: "Bearer <token>",
    },
  })

  const result = await response.json()
  ```

  ```python Python theme={null}
  import requests

  url = "https://joptic.jethings.com/status/stock"

  response = requests.get(
      url,
      headers={
          "x-store-id": "your-store-id",
          "Authorization": "Bearer <token>"
      }
  )

  print(response.json())
  ```
</CodeGroup>

**Success Response:**

```json theme={null}
{
  "items": 150,
  "itemVariants": 450,
  "brands": 25,
  "warehouses": 3,
  "products": 120
}
```

***

### Example 2: Get Sales Status

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://joptic.jethings.com/status/sell" \
    -H "x-store-id: your-store-id" \
    -H "Authorization: Bearer <token>"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://joptic.jethings.com/status/sell", {
    method: "GET",
    headers: {
      "x-store-id": "your-store-id",
      Authorization: "Bearer <token>",
    },
  })

  const result = await response.json()
  ```

  ```python Python theme={null}
  import requests

  url = "https://joptic.jethings.com/status/sell"

  response = requests.get(
      url,
      headers={
          "x-store-id": "your-store-id",
          "Authorization": "Bearer <token>"
      }
  )

  print(response.json())
  ```
</CodeGroup>

**Success Response:**

```json theme={null}
{
  "customers": 320,
  "customerGroups": 5,
  "salesInvoices": 1250,
  "priceLists": 8,
  "itemPrices": 1200
}
```

***

### Example 3: Get Purchase Status

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://joptic.jethings.com/status/buy" \
    -H "x-store-id: your-store-id" \
    -H "Authorization: Bearer <token>"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://joptic.jethings.com/status/buy", {
    method: "GET",
    headers: {
      "x-store-id": "your-store-id",
      Authorization: "Bearer <token>",
    },
  })

  const result = await response.json()
  ```

  ```python Python theme={null}
  import requests

  url = "https://joptic.jethings.com/status/buy"

  response = requests.get(
      url,
      headers={
          "x-store-id": "your-store-id",
          "Authorization": "Bearer <token>"
      }
  )

  print(response.json())
  ```
</CodeGroup>

**Success Response:**

```json theme={null}
{
  "suppliers": 45,
  "supplierGroups": 6,
  "purchaseInvoices": 890,
  "purchaseOrders": 125,
  "priceLists": 5,
  "itemPrices": 800
}
```

***

## Response Structures

### Stock Status Response

Returns counts for stock-related entities:

| Field        | Type   | Description                                       |
| ------------ | ------ | ------------------------------------------------- |
| items        | number | Count of items for this store                     |
| itemVariants | number | Count of item variants for this store             |
| brands       | number | Count of active brands associated with this store |
| warehouses   | number | Count of active warehouses for this store         |
| products     | number | Count of products for this store                  |

**Response Example:**

```json theme={null}
{
  "items": 150,
  "itemVariants": 450,
  "brands": 25,
  "warehouses": 3,
  "products": 120
}
```

### Sales Status Response

Returns counts for sales-related entities:

| Field          | Type   | Description                                        |
| -------------- | ------ | -------------------------------------------------- |
| customers      | number | Count of customers associated with this store      |
| customerGroups | number | Count of customer groups                           |
| salesInvoices  | number | Count of sales invoices for this store             |
| priceLists     | number | Count of active selling price lists for this store |
| itemPrices     | number | Count of item prices for selling price lists       |

**Response Example:**

```json theme={null}
{
  "customers": 320,
  "customerGroups": 5,
  "salesInvoices": 1250,
  "priceLists": 8,
  "itemPrices": 1200
}
```

### Purchase Status Response

Returns counts for purchase-related entities:

| Field            | Type   | Description                                       |
| ---------------- | ------ | ------------------------------------------------- |
| suppliers        | number | Count of active suppliers for this store          |
| supplierGroups   | number | Count of active supplier groups for this store    |
| purchaseInvoices | number | Count of purchase invoices for this store         |
| purchaseOrders   | number | Count of purchase orders for this store           |
| priceLists       | number | Count of active buying price lists for this store |
| itemPrices       | number | Count of item prices for buying price lists       |

**Response Example:**

```json theme={null}
{
  "suppliers": 45,
  "supplierGroups": 6,
  "purchaseInvoices": 890,
  "purchaseOrders": 125,
  "priceLists": 5,
  "itemPrices": 800
}
```

***

## Error Responses

### 400 Bad Request

Invalid type parameter:

```json theme={null}
{
  "statusCode": 400,
  "message": ["type must be one of: stock, buy, sell"],
  "error": "Bad Request"
}
```

Missing type parameter:

```json theme={null}
{
  "statusCode": 400,
  "message": ["type should not be empty"],
  "error": "Bad Request"
}
```

### 403 Forbidden

```json theme={null}
{
  "statusCode": 403,
  "message": "You do not have access to this store",
  "error": "Forbidden"
}
```

### 500 Internal Server Error

```json theme={null}
{
  "statusCode": 500,
  "message": "Failed to retrieve status",
  "error": "Internal Server Error"
}
```

***

## Important Notes

### Store Association

* All counts are scoped to the store specified in the x-store-id header
* Only entities associated with the specified store are included in the counts
* The store ID is automatically extracted from the x-store-id header

### Active Status Filtering

* Brands, warehouses, and price lists are filtered to include only active entities
* Suppliers and supplier groups are filtered to include only active relationships
* Deleted entities are excluded from counts

### Stock Status Details

* **Items**: Counted via product association, excluding deleted items
* **Item Variants**: Counted via item to product association, excluding deleted variants
* **Brands**: Counted from active brand-store relations
* **Warehouses**: Counted for active, non-deleted warehouses
* **Products**: Counted for non-deleted products (item groups)

### Sales Status Details

* **Customers**: Counted from customer-store relations, excluding deleted customers
* **Customer Groups**: Global count (not store-specific)
* **Sales Invoices**: Counted for non-deleted invoices
* **Price Lists**: Counted for active selling price lists
* **Item Prices**: Counted for all item prices in selling price lists

### Purchase Status Details

* **Suppliers**: Counted from active supplier-store relations, excluding deleted suppliers
* **Supplier Groups**: Counted from active supplier group-store relations, excluding deleted groups
* **Purchase Invoices**: Counted for all purchase invoices
* **Purchase Orders**: Counted for all purchase orders
* **Price Lists**: Counted for active buying price lists
* **Item Prices**: Counted for all item prices in buying price lists

***

## Summary

1. **Authenticate** - Obtain JWT token and ensure store access
2. **Choose Status Type** - Select the type of status to retrieve: stock, sell, or buy
3. **Make Request** - GET request to /status/:type with x-store-id header
4. **Process Response** - Receive counts object with relevant metrics for the selected type

This API provides a quick way to monitor the health and activity of your optical store by retrieving aggregated counts for stock management, sales operations, and purchase operations.

***

<CardGroup cols={2}>
  <Card title="Item API" icon="package" href="/j-optic/item-api">
    Create and manage optical items
  </Card>

  <Card title="Customer API" icon="users" href="/j-optic/customer-api">
    Create and manage optical customers
  </Card>
</CardGroup>