Add API documentation for Representation, Secretary, Settlement, SMS, Specialty, Tag, and User Profile endpoints

2026-06-11 10:27:27 +03:30
parent e88ae9bf9c
commit cced85456a
22 changed files with 5691 additions and 0 deletions
@@ -0,0 +1,90 @@
+# ClinicPro — API Documentation Index
+
+> **Base URL:** `https://clinic-pro.ddev.site`  
+> **API Prefix:** `/api/v1`  
+> **Swagger UI:** `https://clinic-pro.ddev.site/api/doc` — user: `admin` / pass: `clinic123`
+
+---
+
+## Authentication
+
+All protected endpoints require:
+```
+Authorization: Bearer <JWT_TOKEN>
+```
+
+| Role | Description |
+|------|-------------|
+| `PUBLIC` | No token required |
+| `AUTH` | Any valid JWT |
+| `ROLE_ADMIN` | Admin user |
+| `ROLE_DOCTOR` | Doctor user |
+| `ROLE_CLINIC` | Clinic owner |
+| `ROLE_SECRETARY` | Secretary |
+
+---
+
+## Standard Response Envelope
+
+```json
+// Success
+{ "success": true, "data": { ... } }
+
+// Paginated
+{ "success": true, "data": [...], "meta": { "totalRecords": 100, "totalPages": 5, "currentPage": 1 } }
+
+// Error
+{ "success": false, "data": null, "errors": [{ "code": "ERR_XXX_000", "message": "..." }] }
+```
+
+---
+
+## Modules
+
+| File | Domain | Endpoints |
+|------|--------|-----------|
+| [auth.md](auth.md) | Authentication — OTP, Login, JWT | 8 |
+| [doctor.md](doctor.md) | Doctor profile & addresses | 11 |
+| [clinic.md](clinic.md) | Clinics | 7 |
+| [clinic-invitation.md](clinic-invitation.md) | Doctor invitations to clinics | 8 |
+| [appointment.md](appointment.md) | Appointments & slot booking | 6 |
+| [appointment-settings.md](appointment-settings.md) | Weekly schedule, date overrides, holidays | 14 |
+| [payment.md](payment.md) | Payments (Mellat / Sep) | 5 |
+| [settlement.md](settlement.md) | Wallet & settlement requests | 7 |
+| [rating.md](rating.md) | Ratings, comments, likes | 9 |
+| [secretary.md](secretary.md) | Doctor secretaries | 5 |
+| [representation.md](representation.md) | Representations (agents) | 6 |
+| [sms.md](sms.md) | SMS send & templates | 10 |
+| [blog.md](blog.md) | Blog posts | 6 |
+| [specialty.md](specialty.md) | Medical specialties | 5 |
+| [insurance.md](insurance.md) | Insurances & doctor-insurance links | 10 |
+| [doctor-service.md](doctor-service.md) | Doctor services | 5 |
+| [tag.md](tag.md) | Blog tags | 5 |
+| [location.md](location.md) | Provinces & cities | 10 |
+| [user-profile.md](user-profile.md) | User medical profile | 4 |
+| [admin.md](admin.md) | Admin dashboard & management | 25+ |
+
+---
+
+## Error Code Reference
+
+| Code | Message (FA) | HTTP |
+|------|--------------|------|
+| `ERR_AUTH_001` | توکن JWT منقضی یا نامعتبر | 401 |
+| `ERR_AUTH_002` | کد OTP نامعتبر | 401 |
+| `ERR_AUTH_003` | کد OTP منقضی شده | 401 |
+| `ERR_AUTH_004` | تعداد تلاش‌های OTP به حد مجاز رسیده | 429 |
+| `ERR_AUTH_005` | نام کاربری یا رمز عبور اشتباه | 401 |
+| `ERR_AUTH_006` | دسترسی ممنوع | 403 |
+| `ERR_VALIDATION_001` | ورودی نامعتبر | 422 |
+| `ERR_VALIDATION_002` | فیلد الزامی وارد نشده | 422 |
+| `ERR_NOT_FOUND_001` | منبع درخواستی یافت نشد | 404 |
+| `ERR_CONFLICT_001` | تداخل: منبع در حال استفاده | 409 |
+| `ERR_FORBIDDEN_001` | دسترسی به این منبع مجاز نیست | 403 |
+| `ERR_PAYMENT_001` | درگاه پرداخت در دسترس نیست | 503 |
+| `ERR_PAYMENT_002` | مبلغ پرداخت نامعتبر | 422 |
+| `ERR_PAYMENT_003` | وضعیت نوبت برای پرداخت مناسب نیست | 422 |
+| `ERR_FILE_001` | فرمت فایل مجاز نیست | 422 |
+| `ERR_SMS_003` | تمپلیت قبلاً ارسال شده | 422 |
+| `ERR_SECRETARY_001` | پلن فعلی اجازه منشی بیشتر نمی‌دهد | 422 |
+| `ERR_RATE_LIMIT_001` | درخواست‌های زیاد، بعداً تلاش کنید | 429 |