API: حساب کاربری

پروفایل، رمز عبور، تنظیمات اعلان، تمدید خودکار، احراز هویت دومرحله‌ای و کلیدهای API.

این نقاط پایانی روی حسابی عمل می‌کنند که مالک کلید یا توکنِ فراخوانی است.

به‌روزرسانی پروفایل

PATCH /account/profile

نام، تلفن یا تصویر را تغییر می‌دهد. ایمیل از اینجا قابل تغییر نیست.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی
`name`	string	خیر
`phone`	string	خیر
`avatar_url`	string	خیر

پاسخ‌ها

200 موفق. برمی‌گرداند User.
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X PATCH https://veneshcloud.ir/api/account/profile \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

تغییر رمز عبور

POST /account/password

رمز فعلی را بررسی و رمز جدید را تعیین می‌کند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی
`current_password`	string	بله
`new_password`	string	بله
`new_password_confirmation`	string	بله

پاسخ‌ها

200 موفق
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/account/password \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"current_password":"your-password","new_password":"your-new-password","new_password_confirmation":"your-new-password"}'

خواندن تنظیمات اعلان

GET /account/notification-preferences

کلیدهای ایمیل و پیامک هر دسته را برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

200 موفق. برمی‌گرداند: data (NotificationPreferences).

نمونه

curl -X GET https://veneshcloud.ir/api/account/notification-preferences \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

به‌روزرسانی تنظیمات اعلان

PATCH /account/notification-preferences

برخی کلیدها را تغییر می‌دهد؛ مواردی که نمی‌فرستید بدون تغییر می‌مانند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`preferences`	object	بله

پاسخ‌ها

200 موفق. برمی‌گرداند: data (NotificationPreferences).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X PATCH https://veneshcloud.ir/api/account/notification-preferences \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"preferences":{}}'

خواندن تمدید خودکار

GET /account/auto-renew

می‌گوید تمدید خودکار برای حساب روشن است یا نه.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

200 موفق. برمی‌گرداند: auto_renew (boolean).

نمونه

curl -X GET https://veneshcloud.ir/api/account/auto-renew \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

به‌روزرسانی تمدید خودکار

PATCH /account/auto-renew

تمدید خودکار را برای کل حساب روشن یا خاموش می‌کند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`auto_renew`	boolean	بله

پاسخ‌ها

200 موفق. برمی‌گرداند: auto_renew (boolean).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X PATCH https://veneshcloud.ir/api/account/auto-renew \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"auto_renew":true}'

شروع راه‌اندازی دومرحله‌ای

POST /account/2fa/setup

فعال‌سازی احراز هویت دومرحله‌ای را با روش انتخابی آغاز می‌کند. برای برنامهٔ احراز هویت، کلید، otpauth_url برای کد QR و کدهای بازیابی یک‌بارمصرف را فقط یک‌بار برمی‌گرداند. تا تأیید نکنید چیزی فعال نمی‌شود.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`method`	string	خیر	`totp`, `email`, `sms`

پاسخ‌ها

200 موفق. برمی‌گرداند: method (string), secret (string), otpauth_url (string), destination_masked (string), expires_in_minutes (integer), recovery_codes (فهرستی از string).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/account/2fa/setup \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

ارسال مجدد کد راه‌اندازی

POST /account/2fa/resend

برای راه‌اندازی در انتظارِ ایمیل یا پیامک، کد تأیید را دوباره می‌فرستد.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

200 موفق. برمی‌گرداند: message (string), expires_in_minutes (integer).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/account/2fa/resend \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

تأیید و فعال‌سازی دومرحله‌ای

POST /account/2fa/confirm

اولین کد را بررسی و احراز هویت دومرحله‌ای را فعال می‌کند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`code`	string	بله

پاسخ‌ها

200 موفق. برمی‌گرداند: message (string), two_factor_enabled (boolean), method (string).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/account/2fa/confirm \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

ارسال کد برای غیرفعال‌سازی

POST /account/2fa/disable-code

برای حساب‌های ایمیل یا پیامک، کد لازم برای خاموش‌کردن دومرحله‌ای را می‌فرستد.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

200 موفق. برمی‌گرداند: message (string), expires_in_minutes (integer).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/account/2fa/disable-code \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

غیرفعال‌سازی دومرحله‌ای

POST /account/2fa/disable

به رمز عبور فعلی و یک کد معتبر نیاز دارد.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`current_password`	string	بله
`code`	string	بله

پاسخ‌ها

200 موفق. برمی‌گرداند: message (string), two_factor_enabled (boolean).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/account/2fa/disable \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"current_password":"your-password","code":"123456"}'

ارسال کد تأیید تلفن

POST /account/phone/send-code

یک کد تأیید به شمارهٔ تلفن حساب شما پیامک می‌کند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

200 موفق. برمی‌گرداند: message (string), destination_masked (string), expires_in_minutes (integer).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/account/phone/send-code \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

تأیید شمارهٔ تلفن

POST /account/phone/verify

کد پیامک‌شده را بررسی و شمارهٔ تلفن را تأییدشده ثبت می‌کند. تغییر شماره، تأیید را بازنشانی می‌کند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`code`	string	بله

پاسخ‌ها

200 موفق. برمی‌گرداند: data (User).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/account/phone/verify \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

فهرست کلیدهای API

GET /account/api-keys

کلیدهای شما را بدون مقدار محرمانه‌شان برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

200 موفق. برمی‌گرداند: data (فهرستی از ApiKey).

نمونه

curl -X GET https://veneshcloud.ir/api/account/api-keys \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

ساخت کلید API

POST /account/api-keys

یک کلید می‌سازد و مقدار محرمانه‌اش را فقط یک‌بار در token برمی‌گرداند. بعداً قابل نمایش دوباره نیست.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`name`	string	بله

پاسخ‌ها

201 ایجاد شد. برمی‌گرداند: data (ApiKey), token (string).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/account/api-keys \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-name"}'

ابطال کلید API

DELETE /account/api-keys/{id}

کلید را حذف می‌کند. هر چیزی که از آن استفاده می‌کند بلافاصله از کار می‌افتد.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`id`	integer

پاسخ‌ها

204 انجام شد، محتوایی برنگردانده می‌شود
404 پیدا نشد

نمونه

curl -X DELETE https://veneshcloud.ir/api/account/api-keys/KEY_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

اشیاء

فهرست فیلدهای اشیایی که در بالا برگردانده می‌شوند.

ApiKey

فیلد	نوع	مقادیر
`id`	integer
`name`	string
`abilities`	فهرستی از string
`last_used_at`	string
`created_at`	string

NotificationChannelPair

فیلد	نوع	مقادیر
`email`	boolean
`sms`	boolean

NotificationPreferences

فیلد	نوع	مقادیر
`order_updates`	`NotificationChannelPair`
`billing`	`NotificationChannelPair`
`support`	`NotificationChannelPair`
`security`	`NotificationChannelPair`

User

فیلد	نوع	مقادیر
`id`	integer
`name`	string
`email`	string
`phone`	string
`avatar_url`	string
`role`	string	`admin`, `support_tech`, `support_finance`, `support_sales`, `customer`
`email_verified`	boolean
`phone_verified`	boolean
`two_factor_enabled`	boolean
`two_factor_method`	string	`totp`, `email`, `sms`
`created_at`	string