# API Interaction Examples

This guide provides real-world request/reponse examples for the most critical platform workflows.

## 1. Authentication

### Login
`POST /api/v1/auth/login`

Use a real account from your `users` table; the password must verify against `users.password_hash` (bcrypt). Example shape only:

```json
{
  "email": "owner@inspiredtech.ae",
  "password": "YourActualPassword"
}
```

**Response:** Returns `token` and `user` object. Invalid credentials return `401` with no token.

### Check Token / User Info
`GET /api/v1/auth/me`

**Headers:**
- `Authorization: Bearer <your_jwt_token>`

**Response:** Returns refreshed `token` and current `user` object. Used to verify session validity and refresh the frontend user state.

---

## 2. Request & Chat

### Get Chat History
`GET /api/v1/chat/history?request_id=24`
```json
{
  "status": "success",
  "data": [
    {
      "id": 105,
      "sender_role": "customer",
      "message": "Can you start on Monday?",
      "created_at": "2026-04-23 10:00:00"
    },
    {
      "id": 106,
      "sender_role": "company",
      "message": "Yes, we are ready.",
      "created_at": "2026-04-23 10:05:00"
    }
  ]
}
```

### Send Message
`POST /api/v1/chat/send`
```json
{
  "request_id": 24,
  "message": "Perfect, please review the contract I just sent."
}
```

---

## 3. Contract Lifecycle

### Init Contract from Quotation
`GET /api/v1/company/contracts/init?quotation_id=7`
Returns pre-filled project name, client details, and items from the quotation.

### Generate Contract (Save Draft)
`POST /api/v1/company/contracts`
```json
{
  "quotation_id": 7,
  "project_name": "Office Fit-out",
  "scope_of_work": "Full renovation...",
  "items": [...],
  "milestones": [...]
}
```

### Send Contract to Client
`POST /api/v1/company/contracts/send?contract_id=10`
Changes status to `under_review`. Client is notified.

### Sign with UAE PASS (Simulated)
`POST /api/v1/company/contracts/sign?contract_id=10`
**Response:**
```json
{
  "status": "success",
  "message": "Contract signed successfully via UAE PASS",
  "data": {
    "signed_at": "2026-04-26 04:30:00",
    "status": "active"
  }
}
```

---

## 4. Revision Workflow

### Start Revision
`POST /api/v1/company/contracts/start-revision?contract_id=10`
Creates a new draft version by copying the current accepted version.

### Compare Versions (Revision Review)
`GET /api/v1/company/contracts/review?contract_id=10&is_revision=1`
Returns both the `current` and `revised` data objects for side-by-side comparison.

### Contract details split (optional lighter calls)
- `GET /api/v1/company/contracts/details?contract_id=10` — header/meta
- `GET /api/v1/company/contracts/timeline?contract_id=10` — timeline JSON
- `GET /api/v1/company/contracts/messages?contract_id=10` — chat history for the linked `request_id`

### Termination settlement (company)
After approval, the contract moves to **`termination_pending`** until reconciliation is confirmed.

**Load settlement matrix (scenarios):**  
`GET /api/v1/company/contracts/termination/settlement?contract_id=10`

**Approve with a scenario:**  
`POST /api/v1/company/contracts/termination/approve`
```json
{
  "contract_id": 10,
  "system_scenario": "work_based",
  "adjustment_amount": null,
  "adjustment_reason": null,
  "reason": "Termination settlement approved by company."
}
```
Valid `system_scenario` values: `work_based`, `refund_required`, `outstanding_payment`.

**Reject pending client termination:**  
`POST /api/v1/company/contracts/termination/reject` — `{ "contract_id": 10 }`

**Reconciliation screen:**  
`GET /api/v1/company/contracts/termination/reconciliation?contract_id=10`

**Finalize (sets `terminated`, `terminated_at`):**  
`POST /api/v1/company/contracts/termination/confirm-settlement` — `{ "contract_id": 10 }`

See Postman folder **05 Contracts → Termination settlement** in `API_COLLECTION.json` for saved requests.

### Company dashboard widgets
`GET /api/v1/company/dashboard/widgets` — single response for dashboard cards (requests, contracts, activity snippets).

---

## 5. Catalog Media Upload

### Upload Service Image/Video
`POST /api/v1/company/services/upload`
**Form-Data:**
- `service_id`: 15
- `media_type`: `image` | `video`
- `file`: (Binary File)

---

## 6. Help & Support

### Submit Help Request (with object linking)
`POST /api/v1/customer/help`
**Form-Data:**
- `category`: `Requests`
- `subject`: `Cannot see quotation`
- `description`: `I received a notification for a quotation but it is not appearing in my list.`
- `related_type`: `request`
- `related_id`: `42`
- `attachments[]`: (Binary File, optional)

**Response:**
```json
{
  "status": "success",
  "message": "Help request submitted successfully",
  "data": {
    "id": 15,
    "status": "open"
  }
}
```

### Submit Help Request (General Account)
`POST /api/v1/customer/help`
**Form-Data:**
- `category`: `Account`
- `subject`: `Update email issue`
- `description`: `I am trying to update my profile email but getting an error.`
- `related_type`: `account`
- `related_id`: null

---

## Pro-Tip: Postman
Always refer to `API_COLLECTION.json` for the most up-to-date endpoint list. Run `php scratch/update_postman.php` to sync your local collection after making backend changes.