# Mobile API: Task Management Documentation

## Overview

The Mobile API Task Management endpoints provide CRUD operations for managing store tasks and task groups. These endpoints allow mobile apps to create, update, and delete tasks just like the admin panel, using API key authentication.

**Important:** These endpoints are for managing the task definitions themselves (what tasks exist). For tracking daily task completion status, see [Mobile API: Workbook Task Completion](mobile-api-workbook-task-completion.md).

## Base URL

```
/api/mobile/tasks
```

## Authentication

All endpoints require an `APIKey` parameter in the POST body.

```
APIKey=your_api_key_here
```

---

## Endpoints

### 1. Get Tasks

Retrieves all tasks for a store, optionally filtered by task group.

```
POST /api/mobile/tasks/:typeNum
```

#### POST Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `APIKey` | string | Yes | Your API key |
| `groupId` | int | No | Filter by task group ID |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/mobile/tasks/pc00" \
  -d "APIKey=your_api_key"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "taskName": "Open All Registers",
      "comment": "Test Comment",
      "taskGroup": 1,
      "recurOn": "MON TUE WED THU FRI SAT SUN ",
      "priority": 1,
      "sortOrder": 0,
      "startDate": null,
      "endDate": null,
      "timeOfDay": null,
      "groupName": "OPENING"
    }
  ]
}
```

#### Task Object Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | int | Unique task identifier |
| `taskName` | string | Task name/title |
| `comment` | string\|null | Task description/instructions |
| `taskGroup` | int | Parent task group ID |
| `recurOn` | string | Days this task appears (e.g., "MON TUE WED THU FRI") |
| `priority` | int | Priority level: `1`=High, `2`=Normal, `3`=Low |
| `sortOrder` | int | Display order within the group |
| `startDate` | string\|null | Task start date (Y-m-d) |
| `endDate` | string\|null | Task end date (Y-m-d) |
| `timeOfDay` | string\|null | Recommended time (HH:MM:SS) |
| `groupName` | string | Name of the parent task group |

---

### 2. Get Task Groups

Retrieves all task groups for a store.

```
POST /api/mobile/tasks/:typeNum/groups
```

#### POST Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `APIKey` | string | Yes | Your API key |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/mobile/tasks/pc00/groups" \
  -d "APIKey=your_api_key"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "data": [
    { "id": 1, "groupName": "OPENING" },
    { "id": 2, "groupName": "CLOSING" }
  ]
}
```

---

### 3. Create Task

Creates a new task in the specified store.

```
POST /api/mobile/tasks/:typeNum/create
```

#### POST Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `APIKey` | string | Yes | - | Your API key |
| `taskName` | string | Yes | - | Task name/title |
| `taskGroup` | int | Yes | - | Task group ID |
| `comment` | string | No | "" | Task description |
| `recurOn` | string | No | "SUN MON TUE WED THU FRI SAT" | Days to show task |
| `priority` | int | No | 2 | Priority: `1`=High, `2`=Normal, `3`=Low |
| `sortOrder` | int | No | 0 | Display order |
| `startDate` | string | No | null | Start date (Y-m-d) |
| `endDate` | string | No | null | End date (Y-m-d) |
| `timeOfDay` | string | No | null | Recommended time (HH:MM:SS) |

#### Success Response (HTTP 201)

```json
{
  "success": true,
  "taskId": 78
}
```

---

### 4. Update Task

Updates an existing task.

```
POST /api/mobile/tasks/:typeNum/:taskId/update
```

Only include fields you want to update. Omitted fields remain unchanged.

#### Success Response (HTTP 200)

```json
{
  "success": true
}
```

---

### 5. Delete Task

Permanently deletes a task.

```
POST /api/mobile/tasks/:typeNum/:taskId/delete
```

#### Success Response (HTTP 200)

```json
{
  "success": true
}
```

---

### 6. Create Task Group

Creates a new task group (e.g., "OPENING", "CLOSING", "MIDDAY").

```
POST /api/mobile/tasks/:typeNum/groups/create
```

#### POST Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `APIKey` | string | Yes | Your API key |
| `groupName` | string | Yes | Name for the new group |

#### Success Response (HTTP 201)

```json
{
  "success": true,
  "groupId": 3
}
```

---

### 7. Update Task Group

Updates a task group's name.

```
POST /api/mobile/tasks/:typeNum/groups/:groupId/update
```

#### POST Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `APIKey` | string | Yes | Your API key |
| `groupName` | string | Yes | New group name |

---

### 8. Delete Task Group

Deletes a task group. By default, groups with tasks cannot be deleted.

```
POST /api/mobile/tasks/:typeNum/groups/:groupId/delete
```

#### POST Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `APIKey` | string | Yes | - | Your API key |
| `deleteTasks` | bool | No | false | Also delete all tasks in the group |

#### Error Response (Group Has Tasks)

```json
{
  "success": false,
  "error": "Task group has 5 task(s). Set deleteTasks=true to delete them."
}
```

---

## Day of Week Values

Use these three-letter codes for the `recurOn` field:

| Code | Day |
|------|-----|
| `SUN` | Sunday |
| `MON` | Monday |
| `TUE` | Tuesday |
| `WED` | Wednesday |
| `THU` | Thursday |
| `FRI` | Friday |
| `SAT` | Saturday |

Multiple days should be space-separated: `"MON TUE WED THU FRI"`

---

## Priority Values

| Value | Name | Description |
|-------|------|-------------|
| `1` | High | High priority task |
| `2` | Normal | Normal priority (default) |
| `3` | Low | Low priority task |

---

## Endpoint Summary

### Task Definition Management
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/mobile/tasks/:typeNum` | Get all tasks |
| POST | `/api/mobile/tasks/:typeNum/groups` | Get all task groups |
| POST | `/api/mobile/tasks/:typeNum/create` | Create a task |
| POST | `/api/mobile/tasks/:typeNum/:taskId/update` | Update a task |
| POST | `/api/mobile/tasks/:typeNum/:taskId/delete` | Delete a task |
| POST | `/api/mobile/tasks/:typeNum/groups/create` | Create a task group |
| POST | `/api/mobile/tasks/:typeNum/groups/:groupId/update` | Update a task group |
| POST | `/api/mobile/tasks/:typeNum/groups/:groupId/delete` | Delete a task group |

### Daily Task Completion Tracking (Workbook)

See [Mobile API: Workbook Task Completion](mobile-api-workbook-task-completion.md) for tracking which tasks have been completed today, by whom, and with what comments.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/mobile/workbook/:typeNum/lists` | Get today's task lists with completion status |
| POST | `/api/mobile/workbook/:typeNum/lists/active` | Get currently active list with carryover tasks |
| POST | `/api/mobile/workbook/:typeNum/completed` | Get completed tasks for a date |
| POST | `/api/mobile/workbook/:typeNum/tasks/:taskId/status` | Update task completion status |
| POST | `/api/mobile/workbook/:typeNum/tasks/:taskId/comment` | Add comment to task |
| POST | `/api/mobile/workbook/:typeNum/tasks/:taskId/comments` | Get task comments |