hesabixArc/hesabixAPI/API_README.md

Hesabix API Documentation

🔗 دسترسی به مستندات

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI Schema: http://localhost:8000/openapi.json

🚀 شروع سریع

1. نصب و راه‌اندازی

# کلون کردن پروژه
git clone https://github.com/hesabix/api.git
cd hesabix-api

# نصب dependencies
pip install -r requirements.txt

# راه‌اندازی دیتابیس
alembic upgrade head

# اجرای سرور
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

2. اولین درخواست

# بررسی وضعیت API
curl http://localhost:8000/api/v1/health

# دریافت کپچا
curl -X POST http://localhost:8000/api/v1/auth/captcha

# ثبت‌نام
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "Accept-Language: fa" \
  -H "X-Calendar-Type: jalali" \
  -d '{
    "first_name": "احمد",
    "last_name": "احمدی",
    "email": "ahmad@example.com",
    "password": "password123",
    "captcha_id": "captcha_id_from_previous_step",
    "captcha_code": "12345"
  }'

🔐 احراز هویت

کلیدهای API

تمام endpoint های محافظت شده نیاز به کلید API دارند:

Authorization: Bearer sk_your_api_key_here

نحوه دریافت کلید

1. ثبت‌نام: POST /api/v1/auth/register
2. ورود: POST /api/v1/auth/login
3. کلیدهای شخصی: POST /api/v1/auth/api-keys

مثال کامل

# 1. دریافت کپچا
curl -X POST http://localhost:8000/api/v1/auth/captcha

# 2. ورود
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept-Language: fa" \
  -H "X-Calendar-Type: jalali" \
  -d '{
    "identifier": "user@example.com",
    "password": "password123",
    "captcha_id": "captcha_id_from_step_1",
    "captcha_code": "12345"
  }'

# 3. استفاده از API
curl -X GET http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer sk_1234567890abcdef" \
  -H "Accept-Language: fa" \
  -H "X-Calendar-Type: jalali"

🌍 چندزبانه

هدرهای زبان

Accept-Language: fa    # فارسی (پیش‌فرض)
Accept-Language: en    # انگلیسی
Accept-Language: fa-IR # فارسی ایران
Accept-Language: en-US # انگلیسی آمریکا

📅 تقویم

هدرهای تقویم

X-Calendar-Type: jalali    # تقویم شمسی (پیش‌فرض)
X-Calendar-Type: gregorian # تقویم میلادی

🛡️ مجوزهای دسترسی

مجوزهای اپلیکیشن

• user_management: مدیریت کاربران
• superadmin: دسترسی کامل
• business_management: مدیریت کسب و کارها
• system_settings: تنظیمات سیستم

endpoint های محافظت شده

• /api/v1/users/* → نیاز به user_management
• /api/v1/auth/me → نیاز به احراز هویت
• /api/v1/auth/api-keys/* → نیاز به احراز هویت

📊 فرمت پاسخ‌ها

پاسخ موفق

{
  "success": true,
  "message": "عملیات با موفقیت انجام شد",
  "data": {
    // داده‌های اصلی
  }
}

پاسخ خطا

{
  "success": false,
  "message": "پیام خطا",
  "error_code": "ERROR_CODE",
  "details": {
    // جزئیات خطا
  }
}

کدهای خطا

کد	معنی
200	موفقیت
400	خطا در اعتبارسنجی
401	احراز هویت نشده
403	دسترسی غیرمجاز
404	منبع یافت نشد
422	خطا در اعتبارسنجی
500	خطای سرور

🔒 امنیت

کپچا

برای عملیات حساس:

# دریافت کپچا
curl -X POST http://localhost:8000/api/v1/auth/captcha

# استفاده در ثبت‌نام/ورود
{
  "captcha_id": "captcha_id_from_previous_step",
  "captcha_code": "12345"
}

رمزگذاری

• رمزهای عبور: bcrypt
• کلیدهای API: SHA-256

📝 مثال‌های کاربردی

مدیریت کاربران

# لیست کاربران (نیاز به مجوز usermanager)
curl -X GET http://localhost:8000/api/v1/users \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Accept-Language: fa" \
  -H "X-Calendar-Type: jalali"

# جستجوی پیشرفته کاربران
curl -X POST http://localhost:8000/api/v1/users/search \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: fa" \
  -H "X-Calendar-Type: jalali" \
  -d '{
    "take": 10,
    "skip": 0,
    "search": "احمد",
    "search_fields": ["first_name", "last_name", "email"],
    "filters": [
      {
        "property": "is_active",
        "operator": "=",
        "value": true
      }
    ]
  }'

# دریافت اطلاعات یک کاربر
curl -X GET http://localhost:8000/api/v1/users/1 \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Accept-Language: fa" \
  -H "X-Calendar-Type: jalali"

# آمار کاربران
curl -X GET http://localhost:8000/api/v1/users/stats/summary \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Accept-Language: fa" \
  -H "X-Calendar-Type: jalali"

مدیریت معرفی‌ها

# آمار معرفی‌ها
curl -X GET "http://localhost:8000/api/v1/auth/referrals/stats?start=2024-01-01&end=2024-12-31" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Accept-Language: fa" \
  -H "X-Calendar-Type: jalali"

# لیست معرفی‌ها
curl -X POST http://localhost:8000/api/v1/auth/referrals/list \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: fa" \
  -H "X-Calendar-Type: jalali" \
  -d '{
    "take": 10,
    "skip": 0,
    "sort_by": "created_at",
    "sort_desc": true
  }'

# خروجی PDF
curl -X POST http://localhost:8000/api/v1/auth/referrals/export/pdf \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: fa" \
  -H "X-Calendar-Type: jalali" \
  -d '{
    "take": 100,
    "skip": 0
  }' \
  --output referrals.pdf

# خروجی Excel
curl -X POST http://localhost:8000/api/v1/auth/referrals/export/excel \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: fa" \
  -H "X-Calendar-Type: jalali" \
  -d '{
    "take": 100,
    "skip": 0
  }' \
  --output referrals.xlsx

🛠️ توسعه

ساختار پروژه

hesabixAPI/
├── app/
│   ├── core/           # تنظیمات اصلی
│   ├── services/       # سرویس‌ها
│   └── main.py         # نقطه ورود
├── adapters/
│   ├── api/v1/         # API endpoints
│   └── db/             # دیتابیس
├── migrations/         # مهاجرت‌های دیتابیس
└── tests/             # تست‌ها

اجرای تست‌ها

pytest tests/

مهاجرت دیتابیس

# ایجاد migration جدید
alembic revision --autogenerate -m "description"

# اعمال migrations
alembic upgrade head

# بازگشت به migration قبلی
alembic downgrade -1

📞 پشتیبانی

• ایمیل: support@hesabix.com
• مستندات: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• GitHub: https://github.com/hesabix/api

📄 مجوز

این پروژه تحت مجوز MIT منتشر شده است. برای جزئیات بیشتر به فایل LICENSE مراجعه کنید.