Add API documentation for Representation, Secretary, Settlement, SMS, Specialty, Tag, and User Profile endpoints
This commit is contained in:
hamed
@@ -0,0 +1,380 @@
|
||||
# Doctor API
|
||||
|
||||
> **Prefix:** `/api/v1/doctor`, `/api/v1/doctors`, `/api/v1/clinic-pro/doctor-address*`
|
||||
|
||||
---
|
||||
|
||||
## POST `/api/v1/doctor`
|
||||
|
||||
Create a doctor profile for the authenticated user.
|
||||
|
||||
**Permission:** `AUTH` — any authenticated user
|
||||
|
||||
### Request Body (`application/json`)
|
||||
```json
|
||||
{
|
||||
"title": "دکتر علی احمدی",
|
||||
"gender": "male",
|
||||
"medical_system_code": "12345",
|
||||
"degree": "متخصص",
|
||||
"info": "توضیحات درباره پزشک",
|
||||
"specialties": [1, 2],
|
||||
"doctor_services": [3, 4]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `title` | string | ✅ | Full name with title |
|
||||
| `gender` | string | ❌ | `"male"` or `"female"` |
|
||||
| `medical_system_code` | string | ❌ | Nظام پزشکی code |
|
||||
| `degree` | string | ❌ | Academic degree |
|
||||
| `info` | string | ❌ | Bio/description |
|
||||
| `specialties` | integer[] | ❌ | Array of specialty IDs |
|
||||
| `doctor_services` | integer[] | ❌ | Array of doctor service IDs |
|
||||
|
||||
### Response `201`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"uuid": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"title": "دکتر علی احمدی",
|
||||
"gender": "male",
|
||||
"medical_system_code": "12345",
|
||||
"degree": "متخصص",
|
||||
"info": "...",
|
||||
"doctor_rate": null,
|
||||
"active_doctor_appointment": false,
|
||||
"specialties": [],
|
||||
"doctor_services": [],
|
||||
"created_at": 1717000000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing or invalid token |
|
||||
| `ERR_CONFLICT_001` | 409 | Doctor profile already exists for this user |
|
||||
| `ERR_VALIDATION_002` | 422 | Missing required field |
|
||||
|
||||
---
|
||||
|
||||
## GET `/api/v1/doctor/{uuid}`
|
||||
|
||||
Get doctor detail with clinics.
|
||||
|
||||
**Permission:** `PUBLIC`
|
||||
|
||||
### Path Parameters
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `uuid` | string (UUID) | Doctor UUID |
|
||||
|
||||
### Response `200`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"data": {
|
||||
"uuid": "550e8400-...",
|
||||
"title": "دکتر علی احمدی",
|
||||
"gender": "male",
|
||||
"medical_system_code": "12345",
|
||||
"degree": "متخصص",
|
||||
"info": "...",
|
||||
"image": "https://...",
|
||||
"doctor_rate": 4.5,
|
||||
"active_doctor_appointment": true,
|
||||
"specialties": [{ "id": 1, "name": "قلب و عروق" }],
|
||||
"doctor_services": [{ "id": 3, "name": "نوار قلب" }],
|
||||
"clinics": [{ "uuid": "...", "name": "کلینیک الوند" }],
|
||||
"created_at": 1717000000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> ⚠️ **Double-nested:** Frontend extracts with `data?.data?.data`
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |
|
||||
|
||||
---
|
||||
|
||||
## GET `/api/v1/doctors`
|
||||
|
||||
List doctors with pagination and filters.
|
||||
|
||||
**Permission:** `PUBLIC`
|
||||
|
||||
### Query Parameters
|
||||
| Param | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `page` | integer | ❌ | Default: 1 |
|
||||
| `limit` | integer | ❌ | Default: 20 |
|
||||
| `search` | string | ❌ | Search in title |
|
||||
| `specialty_id` | integer | ❌ | Filter by specialty |
|
||||
| `city_id` | integer | ❌ | Filter by city |
|
||||
| `state_id` | integer | ❌ | Filter by province |
|
||||
|
||||
### Response `200`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"uuid": "...",
|
||||
"title": "دکتر علی احمدی",
|
||||
"degree": "متخصص",
|
||||
"doctor_rate": 4.5,
|
||||
"image": "https://..."
|
||||
}
|
||||
],
|
||||
"meta": {
|
||||
"totalRecords": 50,
|
||||
"totalPages": 3,
|
||||
"currentPage": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PATCH `/api/v1/doctor/{uuid}`
|
||||
|
||||
Update doctor profile.
|
||||
|
||||
**Permission:** `AUTH` — must be the owner (or `ROLE_ADMIN`)
|
||||
|
||||
### Path Parameters
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `uuid` | string (UUID) | Doctor UUID |
|
||||
|
||||
### Request Body (`application/json`)
|
||||
Same fields as POST — all optional.
|
||||
|
||||
### Response `200`
|
||||
Updated doctor object (same structure as GET single).
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
| `ERR_FORBIDDEN_001` | 403 | Not the owner |
|
||||
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |
|
||||
|
||||
---
|
||||
|
||||
## DELETE `/api/v1/doctor/{uuid}`
|
||||
|
||||
Delete a doctor profile.
|
||||
|
||||
**Permission:** `ROLE_ADMIN`
|
||||
|
||||
### Path Parameters
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `uuid` | string (UUID) | Doctor UUID |
|
||||
|
||||
### 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 | Doctor not found |
|
||||
|
||||
---
|
||||
|
||||
## POST `/file/upload/clinic_pro/doctor/field_image`
|
||||
|
||||
Upload doctor profile image.
|
||||
|
||||
**Permission:** `AUTH`
|
||||
|
||||
### Request
|
||||
`Content-Type: multipart/form-data`
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `file` | binary | ✅ | Image file (max 5MB) |
|
||||
|
||||
### Response `200`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"url": "https://clinic-pro.ddev.site/uploads/doctor/abc123.jpg",
|
||||
"uuid": "...",
|
||||
"filename": "abc123.jpg",
|
||||
"filemime": "image/jpeg",
|
||||
"filesize": 204800
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_FILE_001` | 422 | Invalid file type |
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
|
||||
---
|
||||
|
||||
## GET `/api/v1/clinic-pro/doctor-addresses/{doctorId}`
|
||||
|
||||
Get all practice addresses for a doctor.
|
||||
|
||||
**Permission:** `PUBLIC`
|
||||
|
||||
### Path Parameters
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `doctorId` | integer | Doctor's numeric ID |
|
||||
|
||||
### Response `200`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "مطب تهران",
|
||||
"address": "تهران، خیابان...",
|
||||
"telephone": "02112345678",
|
||||
"latitude": 35.6892,
|
||||
"longitude": 51.3890
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST `/api/v1/clinic-pro/doctor-address`
|
||||
|
||||
Add a new practice address.
|
||||
|
||||
**Permission:** `AUTH` — must own the doctor profile
|
||||
|
||||
### Request Body
|
||||
```json
|
||||
{
|
||||
"name": "مطب تهران",
|
||||
"address": "تهران، خیابان ولیعصر",
|
||||
"telephone": "02112345678",
|
||||
"latitude": 35.6892,
|
||||
"longitude": 51.3890
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required |
|
||||
|-------|------|----------|
|
||||
| `name` | string | ❌ |
|
||||
| `address` | string | ❌ |
|
||||
| `telephone` | string | ❌ |
|
||||
| `latitude` | float | ❌ |
|
||||
| `longitude` | float | ❌ |
|
||||
|
||||
### Response `201`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": 1,
|
||||
"name": "مطب تهران",
|
||||
"address": "تهران، خیابان ولیعصر",
|
||||
"telephone": "02112345678",
|
||||
"latitude": 35.6892,
|
||||
"longitude": 51.3890
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
| `ERR_FORBIDDEN_001` | 403 | Not the doctor owner |
|
||||
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |
|
||||
|
||||
---
|
||||
|
||||
## PATCH `/api/v1/clinic-pro/doctor-address/{id}`
|
||||
|
||||
Update a practice address.
|
||||
|
||||
**Permission:** `AUTH` — must own the doctor profile
|
||||
|
||||
### Path Parameters
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | integer | Address ID |
|
||||
|
||||
### Request Body
|
||||
Same fields as POST — all optional.
|
||||
|
||||
### Response `200`
|
||||
Updated address object.
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
| `ERR_FORBIDDEN_001` | 403 | Not the owner |
|
||||
| `ERR_NOT_FOUND_001` | 404 | Address not found |
|
||||
|
||||
---
|
||||
|
||||
## DELETE `/api/v1/clinic-pro/doctor-address/{id}`
|
||||
|
||||
Delete a practice address.
|
||||
|
||||
**Permission:** `AUTH` — must own the doctor profile
|
||||
|
||||
### Response `200`
|
||||
```json
|
||||
{ "success": true, "data": { "message": "آدرس حذف شد" } }
|
||||
```
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
| `ERR_FORBIDDEN_001` | 403 | Not the owner |
|
||||
| `ERR_NOT_FOUND_001` | 404 | Address not found |
|
||||
|
||||
---
|
||||
|
||||
## POST `/api/v1/clinic-pro/doctor-address/from-clinic/{clinicUuid}`
|
||||
|
||||
Create a doctor address automatically from a clinic's location.
|
||||
|
||||
**Permission:** `AUTH` — must own the doctor profile and be associated with the clinic
|
||||
|
||||
### Path Parameters
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `clinicUuid` | string (UUID) | Clinic UUID |
|
||||
|
||||
### Response `201`
|
||||
Address object created from clinic data.
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_FORBIDDEN_001` | 403 | Not associated with this clinic |
|
||||
| `ERR_NOT_FOUND_001` | 404 | Clinic not found |
|
||||
Reference in New Issue
Block a user