hamedandClaude Opus 4.8
492a7df989
Unify and harden the payment flow (same API for the main site and all consumer sites; per-client difference is only frontend_address). - Payment gains STATUS_CANCELED. Gateways distinguish user-cancel from failure (Mellat ResCode=17, SEP CanceledByUser, mock cancel=1) via a new PaymentVerifyResult::canceled flag; callback sets canceled vs failed and skips the circuit-breaker on cancel. - Expiry job now cancels the pending payment when a booking lapses (AppointmentExpiryService + PaymentRepository::findPendingByAppointment). - frontend_address allowlist is read from the payment_allowed_frontend_hosts site setting (manageable via PATCH /api/v1/admin/settings), falling back to the ALLOWED_FRONTEND_HOSTS env var — so a new consumer site needs no code change. - .env: broaden CORS_ALLOW_ORIGIN to city subdomains (*.localhost / *.clinic-pro.ddev.site) and add yazd-nobat.localhost to ALLOWED_FRONTEND_HOSTS. - Update docs/api/payment.md and docs/api/admin.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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
// 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 | Authentication — OTP, Login, JWT | 8 |
| doctor.md | Doctor profile & addresses | 11 |
| clinic.md | Clinics | 7 |
| clinic-invitation.md | Doctor invitations to clinics | 8 |
| appointment.md | Appointments & slot booking | 6 |
| appointment-settings.md | Weekly schedule, date overrides, holidays | 14 |
| payment.md | Payments (Mellat / Sep) | 5 |
| settlement.md | Wallet & settlement requests | 7 |
| rating.md | Ratings, comments, likes | 9 |
| secretary.md | Doctor secretaries | 5 |
| representation.md | Representations (agents) | 6 |
| sms.md | SMS send & templates | 10 |
| blog.md | Blog posts | 6 |
| specialty.md | Medical specialties | 5 |
| insurance.md | Insurances & doctor-insurance links | 10 |
| doctor-service.md | Doctor services | 5 |
| tag.md | Blog tags | 5 |
| location.md | Provinces & cities | 10 |
| user-profile.md | User medical profile | 4 |
| 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 |