docs/agent/thoughts/expenses.md

Field Agent Expenses API

Endpoints

1. Get My Stats

GET /api/v1/ticket-expenses/my-stats?from_date=2024-11-01&to_date=2024-11-30

Response:

{
  "total_expenses": 25,
  "total_amount": 12500.00,
  "approved_count": 20,
  "approved_amount": 10000.00,
  "pending_count": 3,
  "pending_amount": 1500.00,
  "rejected_count": 2,
  "rejected_amount": 1000.00,
  "paid_count": 15,
  "paid_amount": 7500.00,
  "unpaid_count": 5,
  "unpaid_amount": 2500.00,
  "by_category": {
    "transport": 5000.00,
    "materials": 4000.00,
    "meals": 1500.00
  }
}

---

2. Get My Expenses

GET /api/v1/ticket-expenses/my-expenses?is_approved=false&page=1&page_size=50

Query Params:

• is_approved (optional): true | false
• is_paid (optional): true | false
• from_date (optional): YYYY-MM-DD
• to_date (optional): YYYY-MM-DD
• page (default: 1)
• page_size (default: 100, max: 100)

Response:

{
  "expenses": [
    {
      "id": "uuid",
      "ticket_id": "uuid",
      "ticket_reference": "TKT-001",
      "ticket_title": "Install fiber at Westlands",
      "ticket_status": "completed",
      "ticket_assignment_id": "uuid",
      "assignment_status": "completed",
      "category": "transport",
      "description": "Fuel for site visit",
      "expense_date": "2024-11-15",
      "total_cost": 500.00,
      "quantity": 10.5,
      "unit": "liters",
      "unit_cost": 47.62,
      "incurred_by_user_id": "uuid",
      "incurred_by_user_name": "John Doe",
      "is_approved": false,
      "approved_by_user_id": null,
      "approved_by_user_name": null,
      "approved_at": null,
      "rejection_reason": null,
      "is_paid": false,
      "paid_to_user_id": null,
      "paid_to_user_name": null,
      "paid_at": null,
      "payment_reference": null,
      "receipt_document_id": "uuid",
      "location_verified": true,
      "verification_notes": null,
      "payment_recipient_type": "agent",
      "payment_method": "send_money",
      "payment_details": {
        "phone_number": "+254712345678",
        "recipient_name": "John Doe"
      },
      "notes": null,
      "additional_metadata": {},
      "created_at": "2024-11-15T10:00:00Z",
      "updated_at": "2024-11-15T10:00:00Z"
    }
  ],
  "total": 25,
  "page": 1,
  "page_size": 50,
  "pages": 1
}

---

Expense Status States

Pending Approval:

• is_approved: false
• rejection_reason: null

Rejected:

• is_approved: false
• rejection_reason: "reason text"

Approved (Unpaid):

• is_approved: true
• is_paid: false

Paid:

• is_approved: true
• is_paid: true
• paid_at: "timestamp"
• payment_reference: "ref"

---

Notes

• All endpoints auto-filter to current user
• Authorization handled by backend
• Amounts are in KES (Decimal type)
• Dates use ISO format