TASK_STATUS_UPDATE_GUIDE.md

Task Status Update API - Quick Reference

Endpoint

PATCH /tracker/tasks/{task_id}/status

Request Format

{
  "status": "in_progress",
  "timestamp": 1708156800000,
  "latitude": 19.0760,
  "longitude": 72.8777
}

Status Values

• not_started - Initial state
• in_progress - Task is being worked on
• completed - Task is finished

Valid Status Transitions

From: not_started

✅ not_started → in_progress (captures started_at) ✅ not_started → completed (direct completion)

From: in_progress

✅ in_progress → completed (captures completed_at) ✅ in_progress → not_started (revert)

From: completed

✅ completed → in_progress (reopen) ❌ completed → not_started (must go through in_progress)

Validation Rules

Required Fields

• status - Must be one of: not_started, in_progress, completed
• timestamp - Unix timestamp in milliseconds (positive integer)
• latitude - Must be between -90 and 90
• longitude - Must be between -180 and 180

Authorization

• Must be authenticated (JWT token required)
• Task must be assigned to the authenticated employee
• Task must belong to employee's merchant

Response Codes

200 OK - Success

{
  "success": true,
  "message": "Task status updated successfully"
}

400 Bad Request - Invalid Transition

{
  "success": false,
  "error": "Cannot transition from 'completed' to 'not_started'",
  "detail": "Cannot transition from 'completed' to 'not_started'"
}

404 Not Found - Task Not Found or Unauthorized

{
  "success": false,
  "error": "Task with ID {task_id} not found",
  "detail": "Task with ID {task_id} not found"
}

422 Unprocessable Entity - Validation Error

{
  "success": false,
  "error": "Validation Error",
  "errors": [
    {
      "field": "body -> latitude",
      "message": "ensure this value is greater than or equal to -90",
      "type": "value_error.number.not_ge"
    }
  ]
}

Timestamp Tracking

started_at

• Set when status changes to in_progress
• Stored as Unix timestamp in milliseconds (BIGINT)
• Captured from request payload

completed_at

• Set when status changes to completed
• Stored as Unix timestamp in milliseconds (BIGINT)
• Captured from request payload

updated_at

• Set on every status update
• Stored as PostgreSQL TIMESTAMP
• Automatically set by database

Location Tracking

Every status update captures the employee's location:

• latitude - Updated on every status change
• longitude - Updated on every status change

This allows tracking where the employee was when they:

• Started the task
• Completed the task
• Made any status changes

Example Usage

Start a task

curl -X PATCH "http://localhost:8003/tracker/tasks/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "timestamp": 1708156800000,
    "latitude": 19.0760,
    "longitude": 72.8777
  }'

Complete a task

curl -X PATCH "http://localhost:8003/tracker/tasks/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "timestamp": 1708160400000,
    "latitude": 19.0761,
    "longitude": 72.8778
  }'

Reopen a completed task

curl -X PATCH "http://localhost:8003/tracker/tasks/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "timestamp": 1708164000000,
    "latitude": 19.0762,
    "longitude": 72.8779
  }'

Testing

Run the comprehensive test suite:

python test_tasks_api.py

This will:

1. Create a test task
2. Test GET /tasks/today
3. Test all valid status transitions
4. Test invalid transitions (should fail)
5. Test with invalid task ID (should fail)

Database Schema

The status update modifies these columns in trans.scm_tasks:

• status - Updated to new status
• started_at - Set when transitioning to in_progress
• completed_at - Set when transitioning to completed
• latitude - Updated on every change
• longitude - Updated on every change
• updated_at - Automatically updated by database

Security Features

1. Authentication - JWT token required
2. Authorization - Only assigned employee can update
3. Merchant Validation - Task must belong to employee's merchant
4. Privacy - Returns 404 for unauthorized access (doesn't reveal task existence)
5. Validation - All inputs validated before processing
6. Idempotency - Same status updates are allowed (no error)

Best Practices

1. Always capture current location - Don't reuse old coordinates
2. Use server time - Generate timestamp on client but validate on server
3. Handle errors gracefully - Check response status and show appropriate messages
4. Validate before sending - Check coordinates and timestamp format
5. Retry on network errors - But not on 400/404 errors
6. Log status changes - For audit trail and debugging