clinicpro/docs/api/representation.md

Representation (Agent) API

Prefix: /api/v1/representation

Representations are sales agents who earn commission on appointments booked through their referral.

---

POST /api/v1/representation

Create a new representation.

Permission: ROLE_ADMIN

Request Body (application/json)

{
  "full_name": "علی احمدی",
  "mobile_number": "09123456789",
  "city_id": 42,
  "commission_percent": 10,
  "bank_account": {
    "iban": "IR...",
    "account_number": "1234567890",
    "bank_name": "بانک ملت",
    "owner_name": "علی احمدی"
  }
}

Field	Type	Required	Description
full_name	string	✅	Agent full name
mobile_number	string	✅	Login mobile (creates a User account)
city_id	integer	❌	City ID (FK to categories where bundle=city)
commission_percent	float	❌	Commission rate (0–100)
bank_account	object	❌	Bank details for settlements

Response 201

{
  "success": true,
  "data": {
    "uuid": "rep-uuid-...",
    "full_name": "علی احمدی",
    "mobile_number": "09123456789",
    "city_id": 42,
    "commission_percent": 10,
    "active": true,
    "bank_account": { ... },
    "created_at": 1717000000
  }
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin
ERR_CONFLICT_001	409	Mobile number already in use
ERR_VALIDATION_001	422	Invalid input

---

GET /api/v1/representation/{uuid}

Get representation detail.

Permission: AUTH — must be the representation's user or ROLE_ADMIN

Path Parameters

Param	Type	Description
uuid	string (UUID)	Representation UUID

Response 200

{
  "success": true,
  "data": {
    "uuid": "...",
    "full_name": "علی احمدی",
    "mobile_number": "09123456789",
    "city_id": 42,
    "city_name": "تهران",
    "commission_percent": 10,
    "active": true,
    "bank_account": { ... },
    "created_at": 1717000000
  }
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_FORBIDDEN_001	403	Not owner or admin
ERR_NOT_FOUND_001	404	Representation not found

---

PATCH /api/v1/representation/{uuid}

Update representation.

Permission: AUTH — must be the representation's user or ROLE_ADMIN

Request Body (application/json)

{
  "full_name": "علی احمدی جدید",
  "city_id": 50,
  "commission_percent": 12,
  "bank_account": { ... },
  "active": true
}

All fields optional.

Response 200

Updated representation object.

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_FORBIDDEN_001	403	Not owner or admin
ERR_NOT_FOUND_001	404	Representation not found

---

DELETE /api/v1/representation/{uuid}

Delete a representation.

Permission: ROLE_ADMIN

Response 200

{ "success": true, "data": { "message": "نماینده حذف شد" } }

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin
ERR_NOT_FOUND_001	404	Representation not found

---

GET /api/v1/representation/{uuid}/dashboard/monthly

Get monthly earnings dashboard for a representation.

Permission: AUTH — must be the representation's user or ROLE_ADMIN

Path Parameters

Param	Type	Description
uuid	string (UUID)	Representation UUID

Query Parameters

Param	Type	Required	Description
year	integer	✅	e.g. 2024
month	integer	✅	1–12

Response 200

{
  "success": true,
  "data": {
    "period": { "year": 2024, "month": 6 },
    "stats": {
      "total_appointments": 15,
      "total_revenue_rials": 7500000,
      "commission_rials": 750000,
      "daily": [
        { "date": "2024-06-01", "appointments": 2, "revenue": 1000000, "commission": 100000 }
      ]
    }
  }
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_FORBIDDEN_001	403	Not owner or admin
ERR_NOT_FOUND_001	404	Representation not found

---

GET /api/v1/representation/{uuid}/dashboard/yearly

Get yearly earnings dashboard for a representation.

Permission: AUTH — must be the representation's user or ROLE_ADMIN

Query Parameters

Param	Type	Required	Description
year	integer	✅	e.g. 2024

Response 200

{
  "success": true,
  "data": {
    "period": { "year": 2024 },
    "months": [
      { "month": 1, "appointments": 10, "revenue_rials": 5000000, "commission_rials": 500000 },
      { "month": 2, "appointments": 8, "revenue_rials": 4000000, "commission_rials": 400000 }
    ],
    "totals": {
      "appointments": 97,
      "revenue_rials": 48500000,
      "commission_rials": 4850000
    }
  }
}