228 lines
5.2 KiB
Markdown
228 lines
5.2 KiB
Markdown
# 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`)
|
||
```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`
|
||
```json
|
||
{
|
||
"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`
|
||
```json
|
||
{
|
||
"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`)
|
||
```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`
|
||
```json
|
||
{ "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`
|
||
```json
|
||
{
|
||
"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`
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
}
|
||
}
|
||
```
|