مرجع API
مصادقة REST API وعنوان URL الأساسي وتنسيق الاستجابة القياسية وحدود المعدل وقائمة نقاط النهاية الكاملة.
Base URL and authentication
Production: https://doctor.clinit.app
Local dev: http://localhost:3000
All protected routes require a Bearer token:
Authorization: Bearer <accessToken>
Access tokens are obtained via POST /api/auth/login.
Tokens expire in 15 minutes. Use POST /api/auth/refresh to rotate.
Standard response format:
Success: { ...data } HTTP 200 or 201
Error: { "error": "message" } HTTP 400, 401, 403, 404, 409, 429, or 500
Authentication endpoints
POST /api/auth/login Login — returns accessToken and refreshToken
POST /api/auth/clinics Discover clinics for an email (pre-login)
POST /api/auth/refresh Rotate refresh token
GET /api/auth/me Current user profile
POST /api/auth/logout Invalidate refresh token
POST /api/auth/forgot-password Send password reset email
POST /api/auth/reset-password Reset via token from email
POST /api/auth/change-password Change password (authenticated)
POST /api/auth/2fa/setup Generate TOTP secret and QR URI
POST /api/auth/2fa/verify Enable 2FA by confirming TOTP code
POST /api/auth/2fa/verify-login Verify TOTP at login
POST /api/auth/2fa/disable Disable 2FA (password required)
Patient and appointment endpoints
Patients:
GET /api/patients List patients (search, page, limit)
POST /api/patients Create patient
GET /api/patients/[id] Patient profile
PATCH /api/patients/[id] Update patient
DELETE /api/patients/[id] Soft delete
GET /api/patients/[id]/history Clinical history (chronological)
GET /api/patients/[id]/sessions All session SOAP notes
GET /api/patients/[id]/billing Invoice list and balance
GET /api/patients/[id]/vitals Vital sign history
POST /api/patients/import Bulk CSV import
Appointments:
GET /api/appointments List (date, doctorId, status)
POST /api/appointments Create appointment
GET /api/appointments/[id] Single appointment with patient data
PATCH /api/appointments/[id] Update details
PATCH /api/appointments/[id]/status Transition status
GET /api/appointments/available-slots Available slots (doctorId, date, duration)
GET /api/appointments/active-session Currently in-chair appointment
POST /api/appointments/checkin Mark patient arrived
POST /api/appointments/auto-recur Generate recurring series
Billing and analytics endpoints
Billing:
GET/POST /api/billing/invoices List or create invoices
POST /api/billing/invoices/[id]/pay Record payment
POST /api/billing/invoices/[id]/installments Set up instalment plan
GET /api/billing/invoices/summary Revenue summary stats
GET/POST /api/billing/claims Insurance claims
GET /api/billing/overdue Overdue invoices
GET /api/billing/commissions Doctor commission breakdown
Analytics (requires CLINIC_OWNER or ADMIN role):
GET /api/analytics/revenue Revenue over time (from, to, groupBy)
GET /api/analytics/appointments Appointment trends (from, to, status)
GET /api/analytics/doctor-performance Per-doctor KPIs (from, to, doctorId)
GET /api/analytics/patients Patient growth stats (from, to)
GET /api/analytics/patient-ltv Lifetime value per patient
GET /api/analytics/cohort Monthly retention cohort (year)
GET /api/analytics/procedure-profitability Revenue per procedure (from, to)
GET /api/analytics/referral-sources Patient source breakdown
الأخطاء وأكواد الحالة
400 — طلب خاطئ: حقول مفقودة أو غير صالحة
401 — غير مصادق: رمز مفقود أو منتهي الصلاحية أو غير صالح
403 — محظور: مُصادَق لكن صلاحية غير كافية
404 — غير موجود: المورد غير موجود أو ينتمي لعيادة مختلفة
409 — تعارض: سجل مكرر أو تصادم في الحجز
423 — مقفل: الحساب مقفل بعد محاولات فاشلة كثيرة
429 — طلبات كثيرة جداً: تجاوز حد المعدل
502 — بوابة سيئة: خطأ في الخدمة الأعلية
503 — الخدمة غير متاحة: الخدمة الخارجية غير مُهيَّأة
500 — خطأ داخلي في الخادم: خطأ غير متوقع