# Backstock Management Mobile API Documentation

## Overview

This document describes the mobile API endpoints for the Backstock Management system, including Seasonal Events, Team Notes, Reports & Analytics, and Bin Details functionality.

## Authentication

All endpoints require an `APIKey` parameter sent via POST request body.

```
POST /api/mobile/backstock/{typeNum}/...
Content-Type: application/x-www-form-urlencoded

APIKey=your_api_key&store=ou00&...other_params
```

**Parameters:**
- `APIKey` (required): Valid API key for authentication
- `store` (optional): Store identifier (defaults to `typeNum` from URL)

## Response Format

All responses are JSON with the following structure:

**Success Response:**
```json
{
  "success": true,
  "data": { ... }
}
```

**Error Response:**
```json
{
  "success": false,
  "error": "Error message description"
}
```

---

# Seasonal Events API

## Dashboard

### Get Events Dashboard
Get an overview of all seasonal events with summary statistics.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/dashboard`

**Response:**
```json
{
  "success": true,
  "dashboard": {
    "activeEvents": 3,
    "upcomingEvents": 2,
    "completedEvents": 15,
    "totalBinsPulled": 245,
    "totalBinsStored": 180,
    "unacknowledgedAlerts": 5
  }
}
```

---

## Events CRUD

### List All Events
Get a list of all seasonal events with optional filtering.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| status | string | No | Filter by status: `upcoming`, `active`, `completed` |
| limit | int | No | Max results (default: 50) |
| offset | int | No | Pagination offset (default: 0) |

**Response:**
```json
{
  "success": true,
  "events": [
    {
      "id": 1,
      "name": "Summer Clearance 2024",
      "startDate": "2024-06-01",
      "endDate": "2024-08-31",
      "status": "active",
      "targetBinCount": 100,
      "currentProgress": 75,
      "description": "Annual summer clearance event",
      "createdAt": "2024-05-15 10:30:00",
      "createdBy": 42,
      "createdByName": "John Smith"
    }
  ],
  "total": 20,
  "limit": 50,
  "offset": 0
}
```

---

### Get Single Event
Get detailed information about a specific event.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/{eventId}`

**Response:**
```json
{
  "success": true,
  "event": {
    "id": 1,
    "name": "Summer Clearance 2024",
    "startDate": "2024-06-01",
    "endDate": "2024-08-31",
    "status": "active",
    "targetBinCount": 100,
    "currentProgress": 75,
    "description": "Annual summer clearance event",
    "categories": [
      {"id": 5, "name": "Summer Clothing", "color": "FF6B6B"},
      {"id": 8, "name": "Swimwear", "color": "4ECDC4"}
    ],
    "locations": [
      {"id": 1, "name": "Warehouse A", "onSite": false},
      {"id": 2, "name": "Back Room", "onSite": true}
    ],
    "createdAt": "2024-05-15 10:30:00",
    "createdBy": 42,
    "createdByName": "John Smith"
  }
}
```

---

### Create Event
Create a new seasonal event.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/create`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | Yes | Event name |
| startDate | string | Yes | Start date (YYYY-MM-DD) |
| endDate | string | Yes | End date (YYYY-MM-DD) |
| description | string | No | Event description |
| targetBinCount | int | No | Target number of bins |
| categoryIds | string | No | Comma-separated category IDs |
| locationIds | string | No | Comma-separated location IDs |
| employeeId | int | Yes | ID of employee creating the event |

**Request Example:**
```
APIKey=xxx&name=Fall%20Sale&startDate=2024-09-01&endDate=2024-11-30&targetBinCount=50&employeeId=42
```

**Response:**
```json
{
  "success": true,
  "event": {
    "id": 25,
    "name": "Fall Sale",
    "startDate": "2024-09-01",
    "endDate": "2024-11-30",
    "status": "upcoming",
    "targetBinCount": 50
  }
}
```

---

### Update Event
Update an existing event.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/{eventId}/update`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | No | Event name |
| startDate | string | No | Start date (YYYY-MM-DD) |
| endDate | string | No | End date (YYYY-MM-DD) |
| description | string | No | Event description |
| targetBinCount | int | No | Target number of bins |
| status | string | No | Event status |
| categoryIds | string | No | Comma-separated category IDs |
| locationIds | string | No | Comma-separated location IDs |

**Response:**
```json
{
  "success": true,
  "event": {
    "id": 25,
    "name": "Fall Sale Updated",
    "startDate": "2024-09-01",
    "endDate": "2024-12-15",
    "status": "active"
  }
}
```

---

### Delete Event
Delete a seasonal event.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/{eventId}/delete`

**Response:**
```json
{
  "success": true,
  "message": "Event deleted successfully"
}
```

---

## Event Progress & Timeline

### Get Event Progress
Get detailed progress information for an event.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/{eventId}/progress`

**Response:**
```json
{
  "success": true,
  "progress": {
    "eventId": 1,
    "targetBinCount": 100,
    "binsPulled": 75,
    "binsStored": 60,
    "percentComplete": 75,
    "daysRemaining": 45,
    "estimatedCompletion": "2024-07-15",
    "dailyAverage": 2.5,
    "onTrack": true
  }
}
```

---

### Get Event Timeline
Get activity timeline for an event.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/{eventId}/timeline`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| limit | int | No | Max results (default: 50) |
| offset | int | No | Pagination offset |

**Response:**
```json
{
  "success": true,
  "timeline": [
    {
      "id": 1,
      "type": "bin_pulled",
      "binId": 456,
      "binName": "BIN-2024-0456",
      "employeeId": 42,
      "employeeName": "John Smith",
      "timestamp": "2024-06-15 14:30:00",
      "notes": "Pulled for summer display"
    },
    {
      "id": 2,
      "type": "bin_stored",
      "binId": 123,
      "binName": "BIN-2024-0123",
      "employeeId": 38,
      "employeeName": "Jane Doe",
      "timestamp": "2024-06-15 11:00:00",
      "notes": null
    }
  ],
  "total": 150
}
```

**Timeline Event Types:**
- `bin_pulled` - Bin was pulled from storage
- `bin_stored` - Bin was returned to storage
- `event_created` - Event was created
- `event_updated` - Event details were updated
- `alert_created` - Alert was generated
- `note_added` - Note was added to the event

---

## Alerts

### Get Event Alerts
Get all alerts for an event.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/{eventId}/alerts`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| includeAcknowledged | boolean | No | Include acknowledged alerts (default: false) |

**Response:**
```json
{
  "success": true,
  "alerts": [
    {
      "id": 1,
      "eventId": 1,
      "alertType": "deadline_approaching",
      "message": "Event ends in 7 days with 25 bins still to process",
      "binCount": 25,
      "acknowledged": false,
      "acknowledgedBy": null,
      "acknowledgedAt": null,
      "createdAt": "2024-08-24 09:00:00"
    }
  ]
}
```

**Alert Types:**
- `deadline_approaching` - Event deadline is approaching
- `target_reached` - Bin target has been reached
- `behind_schedule` - Progress is behind schedule
- `low_inventory` - Category inventory is low
- `action_required` - Manual action is needed

---

### Acknowledge Alert
Mark an alert as acknowledged.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/alerts/{alertId}/acknowledge`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| employeeId | int | Yes | ID of acknowledging employee |

**Response:**
```json
{
  "success": true,
  "alert": {
    "id": 1,
    "acknowledged": true,
    "acknowledgedBy": 42,
    "acknowledgedAt": "2024-08-24 10:30:00"
  }
}
```

---

### Get Unacknowledged Alerts
Get all unacknowledged alerts across all events.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/alerts/unacknowledged`

**Response:**
```json
{
  "success": true,
  "alerts": [
    {
      "id": 1,
      "eventId": 1,
      "eventName": "Summer Clearance 2024",
      "alertType": "deadline_approaching",
      "message": "Event ends in 7 days",
      "binCount": 25,
      "createdAt": "2024-08-24 09:00:00"
    }
  ],
  "count": 5
}
```

---

## Bins Management

### Get Bins to Pull
Get list of bins that should be pulled for an event.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/{eventId}/bins/to-pull`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| categoryId | int | No | Filter by category |
| locationId | int | No | Filter by location |
| limit | int | No | Max results (default: 50) |

**Response:**
```json
{
  "success": true,
  "bins": [
    {
      "id": 456,
      "name": "BIN-2024-0456",
      "generatedName": "Summer Tops - Mixed",
      "location": "Warehouse A",
      "locationId": 1,
      "category": "Summer Clothing",
      "categoryId": 5,
      "categoryColor": "FF6B6B",
      "age": 45,
      "itemCount": 35,
      "estimatedValue": 250.00,
      "lastAuditDate": "2024-06-01"
    }
  ],
  "total": 25
}
```

---

### Get Bins to Store
Get list of bins that need to be stored back after an event.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/{eventId}/bins/to-store`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| limit | int | No | Max results (default: 50) |

**Response:**
```json
{
  "success": true,
  "bins": [
    {
      "id": 123,
      "name": "BIN-2024-0123",
      "generatedName": "Fall Jackets",
      "pulledDate": "2024-06-15",
      "pulledBy": "John Smith",
      "daysSincePulled": 10,
      "category": "Outerwear",
      "categoryColor": "4A90A4"
    }
  ],
  "total": 15
}
```

---

### Pull Bin for Event
Mark a bin as pulled for an event.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/{eventId}/bins/{binId}/pull`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| employeeId | int | Yes | ID of employee pulling the bin |
| notes | string | No | Optional notes |

**Response:**
```json
{
  "success": true,
  "message": "Bin pulled successfully",
  "bin": {
    "id": 456,
    "name": "BIN-2024-0456",
    "pulledAt": "2024-06-15 14:30:00",
    "pulledBy": 42
  }
}
```

---

### Store Bin After Event
Mark a bin as stored back after an event.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/{eventId}/bins/{binId}/store`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| employeeId | int | Yes | ID of employee storing the bin |
| locationId | int | No | New location ID (optional) |
| notes | string | No | Optional notes |

**Response:**
```json
{
  "success": true,
  "message": "Bin stored successfully",
  "bin": {
    "id": 456,
    "name": "BIN-2024-0456",
    "storedAt": "2024-06-25 11:00:00",
    "storedBy": 42,
    "location": "Warehouse A"
  }
}
```

---

## Event Templates

### List Event Templates
Get saved event templates for quick creation.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/templates`

**Response:**
```json
{
  "success": true,
  "templates": [
    {
      "id": 1,
      "name": "Summer Clearance Template",
      "description": "Standard summer clearance settings",
      "targetBinCount": 100,
      "categories": [5, 8, 12],
      "locations": [1, 2],
      "createdAt": "2024-01-15"
    }
  ]
}
```

---

### Create Event from Template
Create a new event based on a template.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/events/templates/{templateId}/create`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | Yes | Event name |
| startDate | string | Yes | Start date (YYYY-MM-DD) |
| endDate | string | Yes | End date (YYYY-MM-DD) |
| employeeId | int | Yes | ID of employee creating |

**Response:**
```json
{
  "success": true,
  "event": {
    "id": 26,
    "name": "Summer Clearance 2025",
    "startDate": "2025-06-01",
    "endDate": "2025-08-31",
    "status": "upcoming"
  }
}
```

---

# Team Notes API

## Notes CRUD

### List Notes
Get team notes with optional filtering.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/notes`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| pinnedOnly | boolean | No | Only show pinned notes |
| employeeId | int | No | Filter by author |
| eventId | int | No | Filter by event |
| binId | int | No | Filter by bin |
| limit | int | No | Max results (default: 50) |
| offset | int | No | Pagination offset |

**Response:**
```json
{
  "success": true,
  "notes": [
    {
      "id": 1,
      "content": "Remember to check the summer bins in warehouse A before the sale starts",
      "authorId": 42,
      "authorName": "John Smith",
      "pinned": true,
      "eventId": 1,
      "eventName": "Summer Clearance 2024",
      "binId": null,
      "binName": null,
      "reactions": {
        "👍": 3,
        "❤️": 1
      },
      "commentCount": 2,
      "createdAt": "2024-06-10 09:00:00",
      "updatedAt": "2024-06-10 09:00:00"
    }
  ],
  "total": 25
}
```

---

### Get Single Note
Get detailed information about a specific note.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/notes/{noteId}`

**Response:**
```json
{
  "success": true,
  "note": {
    "id": 1,
    "content": "Remember to check the summer bins...",
    "authorId": 42,
    "authorName": "John Smith",
    "pinned": true,
    "eventId": 1,
    "eventName": "Summer Clearance 2024",
    "reactions": {
      "👍": [42, 38, 55],
      "❤️": [38]
    },
    "comments": [
      {
        "id": 1,
        "content": "Will do!",
        "authorId": 38,
        "authorName": "Jane Doe",
        "createdAt": "2024-06-10 10:00:00"
      }
    ],
    "createdAt": "2024-06-10 09:00:00"
  }
}
```

---

### Create Note
Create a new team note.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/notes/create`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| content | string | Yes | Note content |
| employeeId | int | Yes | Author employee ID |
| pinned | boolean | No | Pin the note (default: false) |
| eventId | int | No | Associated event ID |
| binId | int | No | Associated bin ID |

**Response:**
```json
{
  "success": true,
  "note": {
    "id": 15,
    "content": "New note content",
    "authorId": 42,
    "pinned": false,
    "createdAt": "2024-06-15 14:30:00"
  }
}
```

---

### Update Note
Update an existing note.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/notes/{noteId}/update`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| content | string | No | Updated content |
| pinned | boolean | No | Update pin status |
| employeeId | int | Yes | Employee making the update |

**Response:**
```json
{
  "success": true,
  "note": {
    "id": 15,
    "content": "Updated note content",
    "pinned": true,
    "updatedAt": "2024-06-15 15:00:00"
  }
}
```

---

### Delete Note
Delete a team note.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/notes/{noteId}/delete`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| employeeId | int | Yes | Employee ID (for authorization) |

**Response:**
```json
{
  "success": true,
  "message": "Note deleted successfully"
}
```

---

## Reactions

### Add Reaction
Add a reaction to a note.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/notes/{noteId}/react`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| employeeId | int | Yes | Employee adding reaction |
| reaction | string | Yes | Emoji reaction (👍, ❤️, 😀, etc.) |

**Response:**
```json
{
  "success": true,
  "reactions": {
    "👍": 4,
    "❤️": 1
  }
}
```

---

### Remove Reaction
Remove a reaction from a note.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/notes/{noteId}/unreact`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| employeeId | int | Yes | Employee removing reaction |
| reaction | string | Yes | Emoji reaction to remove |

**Response:**
```json
{
  "success": true,
  "reactions": {
    "👍": 3,
    "❤️": 1
  }
}
```

---

## Comments

### Add Comment
Add a comment to a note.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/notes/{noteId}/comments/create`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| employeeId | int | Yes | Comment author |
| content | string | Yes | Comment content |

**Response:**
```json
{
  "success": true,
  "comment": {
    "id": 5,
    "content": "Thanks for the reminder!",
    "authorId": 38,
    "authorName": "Jane Doe",
    "createdAt": "2024-06-15 16:00:00"
  }
}
```

---

### Delete Comment
Delete a comment from a note.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/notes/{noteId}/comments/{commentId}/delete`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| employeeId | int | Yes | Employee ID (for authorization) |

**Response:**
```json
{
  "success": true,
  "message": "Comment deleted successfully"
}
```

---

## Pin Management

### Toggle Pin
Toggle the pinned status of a note.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/notes/{noteId}/pin`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| employeeId | int | Yes | Employee making the change |

**Response:**
```json
{
  "success": true,
  "pinned": true
}
```

---

# Reports & Analytics API

## Summary Reports

### Get Summary Report
Get overall backstock summary statistics.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/reports/summary`

**Response:**
```json
{
  "success": true,
  "summary": {
    "totalBins": 450,
    "onSiteBins": 125,
    "offSiteBins": 325,
    "avgAge": 42,
    "staleBins": 28,
    "needsAudit": 15,
    "totalValue": 45000.00,
    "totalItemCount": 8500
  }
}
```

---

### Get Age Distribution
Get bin age distribution breakdown.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/reports/age-distribution`

**Response:**
```json
{
  "success": true,
  "distribution": [
    {"range": "0-30", "count": 150, "percent": 33},
    {"range": "31-60", "count": 120, "percent": 27},
    {"range": "61-90", "count": 100, "percent": 22},
    {"range": "90+", "count": 80, "percent": 18}
  ]
}
```

---

### Get Stale Inventory
Get list of stale bins requiring attention.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/reports/stale`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| daysThreshold | int | No | Days to consider stale (default: 90) |
| limit | int | No | Max results (default: 50) |

**Response:**
```json
{
  "success": true,
  "bins": [
    {
      "id": 789,
      "name": "BIN-2024-0789",
      "location": "Warehouse B",
      "mainCategory": "Winter Coats",
      "age": 120,
      "ageDate": "2024-02-15",
      "itemCount": 25,
      "estimatedValue": 500.00,
      "lastAuditDate": "2024-03-01"
    }
  ],
  "total": 28
}
```

---

## Category Reports

### Get Category Health
Get health metrics for all categories.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/reports/categories/health`

**Response:**
```json
{
  "success": true,
  "categories": [
    {
      "id": 5,
      "name": "Summer Clothing",
      "color": "FF6B6B",
      "binCount": 45,
      "avgAge": 35,
      "health": 85,
      "staleBins": 2,
      "totalValue": 4500.00
    }
  ]
}
```

**Health Score Calculation:**
- 80-100: Healthy (green)
- 50-79: Moderate (yellow)
- 0-49: Needs attention (red)

---

## Location Reports

### Get Location Utilization
Get utilization metrics for all locations.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/reports/locations/utilization`

**Response:**
```json
{
  "success": true,
  "locations": [
    {
      "id": 1,
      "name": "Warehouse A",
      "onSite": false,
      "binCount": 150,
      "capacity": 200,
      "utilization": 75,
      "avgAge": 45,
      "oldestBinAge": 120
    }
  ]
}
```

---

## Activity Reports

### Get Activity Summary
Get activity summary for a time period.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/reports/activity/summary`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| days | int | No | Number of days (default: 30) |

**Response:**
```json
{
  "success": true,
  "activity": {
    "binsCreated": 25,
    "binsDeleted": 5,
    "itemsAdded": 450,
    "itemsRemoved": 320,
    "binsEmptied": 12,
    "auditsCompleted": 35,
    "topEmployees": [
      {"id": 42, "name": "John Smith", "actionCount": 85},
      {"id": 38, "name": "Jane Doe", "actionCount": 72}
    ],
    "activeCategories": [
      {"id": 5, "name": "Summer Clothing", "color": "FF6B6B", "actionCount": 120},
      {"id": 8, "name": "Swimwear", "color": "4ECDC4", "actionCount": 85}
    ]
  }
}
```

---

## Export Reports

### Export Report
Export report data in various formats.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/reports/export`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| format | string | Yes | Export format: `csv`, `pdf`, `json` |
| reportType | string | Yes | Report type: `summary`, `stale`, `activity`, `categories` |
| dateFrom | string | No | Start date for filtering |
| dateTo | string | No | End date for filtering |

**Response (JSON format):**
```json
{
  "success": true,
  "data": { ... },
  "exportedAt": "2024-06-15T14:30:00Z"
}
```

**Response (CSV/PDF format):**
Returns file download with appropriate Content-Type header.

---

# Bin Details API

## Bin Information

### Get Bin Details
Get detailed information about a specific bin.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/bins/{binId}/details`

**Response:**
```json
{
  "success": true,
  "bin": {
    "id": 456,
    "name": "BIN-2024-0456",
    "generatedName": "Summer Tops - Mixed Sizes",
    "notes": "Contains mostly medium and large sizes",
    "location": "Warehouse A",
    "locationId": 1,
    "category": "Summer Clothing",
    "categoryId": 5,
    "categoryColor": "FF6B6B",
    "itemCount": 35,
    "estimatedValue": 250.00,
    "age": 45,
    "ageDate": "2024-05-01",
    "lastAuditDate": "2024-06-01",
    "lastAuditByName": "John Smith",
    "createdAt": "2024-05-01 10:00:00",
    "createdBy": 42,
    "createdByName": "John Smith"
  }
}
```

---

### Update Bin Notes
Update the notes for a bin.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/bins/{binId}/notes`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| notes | string | Yes | New notes content |
| employeeId | int | Yes | Employee making the update |

**Response:**
```json
{
  "success": true,
  "message": "Notes updated successfully"
}
```

---

### Update Item Count
Update the item count for a bin.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/bins/{binId}/item-count`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| itemCount | int | Yes | New item count |
| employeeId | int | Yes | Employee making the update |

**Response:**
```json
{
  "success": true,
  "bin": {
    "id": 456,
    "itemCount": 40
  }
}
```

---

### Update Estimated Value
Update the estimated value for a bin.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/bins/{binId}/estimated-value`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| estimatedValue | float | Yes | New estimated value |
| employeeId | int | Yes | Employee making the update |

**Response:**
```json
{
  "success": true,
  "bin": {
    "id": 456,
    "estimatedValue": 275.00
  }
}
```

---

## Audit

### Record Audit
Record an audit for a bin.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/bins/{binId}/audit`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| employeeId | int | Yes | Auditing employee ID |
| itemCount | int | No | Updated item count |
| estimatedValue | float | No | Updated estimated value |
| notes | string | No | Audit notes |

**Response:**
```json
{
  "success": true,
  "audit": {
    "id": 125,
    "binId": 456,
    "employeeId": 42,
    "employeeName": "John Smith",
    "itemCount": 40,
    "estimatedValue": 275.00,
    "notes": "Counted and verified",
    "auditedAt": "2024-06-15 14:30:00"
  },
  "bin": {
    "id": 456,
    "itemCount": 40,
    "estimatedValue": 275.00,
    "lastAuditDate": "2024-06-15 14:30:00",
    "lastAuditByName": "John Smith"
  }
}
```

---

### Get Audit History
Get audit history for a bin.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/bins/{binId}/audits`

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| limit | int | No | Max results (default: 20) |

**Response:**
```json
{
  "success": true,
  "audits": [
    {
      "id": 125,
      "employeeId": 42,
      "employeeName": "John Smith",
      "itemCount": 40,
      "estimatedValue": 275.00,
      "notes": "Counted and verified",
      "auditedAt": "2024-06-15 14:30:00"
    },
    {
      "id": 100,
      "employeeId": 38,
      "employeeName": "Jane Doe",
      "itemCount": 35,
      "estimatedValue": 250.00,
      "notes": null,
      "auditedAt": "2024-06-01 10:00:00"
    }
  ]
}
```

---

## Name Generation

### Generate Bin Name
Generate or regenerate a descriptive name for a bin.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/bins/{binId}/generate-name`

**Response:**
```json
{
  "success": true,
  "generatedName": "Summer Tops - Mixed Colors S/M",
  "bin": {
    "id": 456,
    "generatedName": "Summer Tops - Mixed Colors S/M"
  }
}
```

---

## Categories

### List Categories
Get all backstock categories.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/categories`

**Response:**
```json
{
  "success": true,
  "categories": [
    {
      "id": 5,
      "name": "Summer Clothing",
      "color": "FF6B6B",
      "binCount": 45,
      "active": true
    },
    {
      "id": 8,
      "name": "Swimwear",
      "color": "4ECDC4",
      "binCount": 12,
      "active": true
    }
  ]
}
```

---

### Get Category Details
Get detailed information about a category.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/categories/{categoryId}`

**Response:**
```json
{
  "success": true,
  "category": {
    "id": 5,
    "name": "Summer Clothing",
    "color": "FF6B6B",
    "description": "Seasonal summer items",
    "binCount": 45,
    "totalItems": 850,
    "totalValue": 8500.00,
    "avgAge": 35,
    "active": true
  }
}
```

---

## Locations

### List Locations
Get all backstock locations.

**Endpoint:** `POST /api/mobile/backstock/{typeNum}/locations`

**Response:**
```json
{
  "success": true,
  "locations": [
    {
      "id": 1,
      "name": "Warehouse A",
      "onSite": false,
      "binCount": 150,
      "active": true
    },
    {
      "id": 2,
      "name": "Back Room",
      "onSite": true,
      "binCount": 45,
      "active": true
    }
  ]
}
```

---

# Error Codes

| HTTP Code | Description |
|-----------|-------------|
| 200 | Success |
| 400 | Bad Request - Missing or invalid parameters |
| 401 | Unauthorized - Invalid or missing API key |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource not found |
| 500 | Internal Server Error |

## Common Error Responses

**Missing API Key:**
```json
{
  "success": false,
  "error": "Missing APIKey parameter"
}
```

**Invalid Store:**
```json
{
  "success": false,
  "error": "Invalid store"
}
```

**Resource Not Found:**
```json
{
  "success": false,
  "error": "Event not found"
}
```

---

# Data Types Reference

## Event Status Values
- `upcoming` - Event has not started yet
- `active` - Event is currently running
- `completed` - Event has ended
- `cancelled` - Event was cancelled

## Alert Types
- `deadline_approaching` - Event deadline is approaching
- `target_reached` - Target bin count reached
- `behind_schedule` - Progress is behind schedule
- `low_inventory` - Category inventory is low
- `action_required` - Manual action needed

## Timeline Activity Types
- `bin_pulled` - Bin pulled from storage
- `bin_stored` - Bin returned to storage
- `event_created` - Event created
- `event_updated` - Event updated
- `alert_created` - Alert generated
- `note_added` - Note added

## Supported Reactions
- 👍 (thumbs up)
- ❤️ (heart)
- 😀 (smile)
- 🎉 (celebration)
- 👀 (eyes)
- ⚠️ (warning)

---

# Changelog

## Version 1.0.0 (December 2024)
- Initial release of Backstock Management Mobile API
- Seasonal Events management
- Team Notes with reactions and comments
- Reports & Analytics
- Bin Details and Audit functionality