فروشگاه ساز سازیتو | مستندات

بازخورد و کیف پول

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

قراردادها و احراز هویت

پیش از اجرای نمونه‌ها، این متغیرها را تنظیم کنید:

export BASE_URL="https://your-store.example.com/api/v1"
export API_KEY="your-api-key"
export USER_TOKEN="your-user-jwt"

نام میزبان، فروشگاه (tenant) و پایگاه‌دادهٔ آن را مشخص می‌کند. برای درخواست‌هایی که با API key احراز هویت می‌شوند، هدر زیر را ارسال کنید:

X-API-Key: your-api-key

API key به کاربر مشخصی متصل نیست؛ هر کلید معتبر همیشه به‌عنوان قدیمی‌ترین کاربرِ سوپرادمین فروشگاه (نقش با دسترسی ALL) عمل می‌کند و endpointهای نیازمند مجوز، مجوزهای همان کاربر را بررسی می‌کنند. اگر هدر X-API-Key روی یکی از مسیرهای مجاز API key ارسال شود، هدر Authorization کاملاً نادیده گرفته می‌شود. کلید نامعتبر درخواست را ناشناس می‌کند: endpointهای عمومی کار می‌کنند و endpointهای محافظت‌شده 403 برمی‌گردانند. برای بدنه‌های JSON نیز هدر Content-Type: application/json را ارسال کنید.

APIهای بازخورد

APIهای بازخورد فقط زمانی در دسترس‌اند که قابلیت تجربه برای فروشگاه فعال باشد؛ در غیر این صورت همهٔ آن‌ها 403 با پیام User is not allowed to do the action برمی‌گردانند. علاوه بر این، GET /feedbacks/seed/... و POST /feedbacks/comments/details اگر گزینهٔ enabled در تنظیمات تجربهٔ فروشگاه خاموش باشد، 400 با پیام Invalid Setting برمی‌گردانند.

متد مسیر دسترسی
GET /feedbacks/seed/{order_identifier} عمومی
POST /feedbacks/comments عمومی
GET /feedbacks/comments/average_rate عمومی
GET /feedbacks/comments/details/{product_id} عمومی
POST /feedbacks/comments/details عمومی
GET /feedbacks/admin/comments API key + مجوز خواندن تجربه
GET /feedbacks/admin/comments/{comment_id} API key + مجوز خواندن تجربه
PATCH /feedbacks/admin/comments/details/{id}/publish API key + مجوز به‌روزرسانی تجربه
PATCH /feedbacks/admin/comments/details/{id}/archive API key + مجوز به‌روزرسانی تجربه
PATCH /feedbacks/admin/comments/details/{detail_id}/attachments/{attachment_id}/publish API key + مجوز به‌روزرسانی تجربه
PATCH /feedbacks/admin/comments/details/{detail_id}/attachments/{attachment_id}/archive API key + مجوز به‌روزرسانی تجربه
PATCH /feedbacks/admin/comments/{id}/statuses API key + مجوز به‌روزرسانی تجربه

endpointهای مدیریتی بازخورد با JWT کاربر مدیر هم قابل فراخوانی‌اند. کاربری که مجوز دسترسی کامل تجربه را دارد، همهٔ این عملیات را بدون مجوز خواندن/به‌روزرسانی جداگانه انجام می‌دهد.

دریافت دادهٔ اولیهٔ بازخورد سفارش

سفارش، variantهای یکتای محصولات آن و وضعیت ثبت‌شدن بازخورد را برمی‌گرداند. سفارش باید وجود داشته و واجد شرایط ثبت بازخورد باشد.

curl --request GET "$BASE_URL/feedbacks/seed/ORDER-IDENTIFIER"
{
  "store_id": 12,
  "order_id": 845,
  "order_identifier": "ORDER-IDENTIFIER",
  "items": [
    {
      "product_id": 101,
      "product_variant_id": 205,
      "product_name": "Example product",
      "product_attributes": [],
      "product_image": {}
    }
  ],
  "has_comment_already": false
}

ثبت نظر برای سفارش

هر دو فیلد order_id و order_identifier الزامی‌اند و باید متعلق به یک سفارش باشند. سفارش نباید ناموفق یا لغوشده باشد و اگر وضعیت پرداخت دارد باید پرداخت‌شده باشد. مقدار order_rate باید بین 1 و 5 باشد. برای هر سفارش فقط یک نظر ثبت می‌شود و ارسال دوباره خطا برمی‌گرداند (has_comment_already در endpoint دادهٔ اولیه را بررسی کنید).

curl --request POST "$BASE_URL/feedbacks/comments" \
  --header "Content-Type: application/json" \
  --data '{
    "order_id": 845,
    "order_identifier": "ORDER-IDENTIFIER",
    "order_rate": 5
  }'
{
  "id": "comment-id",
  "order_id": 845,
  "order_identifier": "ORDER-IDENTIFIER",
  "order_rate": 5,
  "created_at": "2026-07-19T10:00:00Z",
  "updated_at": "2026-07-19T10:00:00Z"
}

دریافت میانگین امتیاز فروشگاه

curl --request GET "$BASE_URL/feedbacks/comments/average_rate"
{ "average_rate": 4.35 }

دریافت بازخوردهای منتشرشدهٔ محصول

تمام query parameterها به سرویس تجربه ارسال می‌شوند. پیش‌فرض page_number برابر 1 و page_size برابر 10 (حداکثر 50) است. با exclude=comments فقط product_statistics برگردانده می‌شود. فقط جزئیاتِ منتشرشده (PUBLISHED) نمایش داده می‌شوند. پارامترهای متداول صفحه‌بندی در نمونهٔ زیر آمده‌اند:

curl --get "$BASE_URL/feedbacks/comments/details/101" \
  --data-urlencode "page_number=1" \
  --data-urlencode "page_size=20"

پاسخ شامل دادهٔ صفحه‌بندی product_comments و product_statistics است که میانگین امتیاز محصول و مجموع/درصد توصیه‌ها را در بر دارد.

ثبت جزئیات بازخورد محصول

مقدارهای مجاز recommendation_status:

RECOMMENDED, NOT-RECOMMENDED, NEUTRAL, NONE

comment_id از endpoint ثبت نظر سفارش برمی‌گردد. کلیدهای ارائهٔ فایل پیوست باید پیش از این درخواست از طریق سرویس فایل مرتبط بارگذاری شده باشند.

curl --request POST "$BASE_URL/feedbacks/comments/details" \
  --header "Content-Type: application/json" \
  --data '{
    "comment_id": "comment-id",
    "product_id": 101,
    "product_variant_id": 205,
    "product_rate": 5,
    "recommendation_status": "RECOMMENDED",
    "text": "Good quality and fast delivery.",
    "pros": ["Good build quality"],
    "cons": [],
    "is_anonymous": false,
    "owner": true,
    "attachments_serve_keys": []
  }'

پاسخ شامل شناسهٔ جزئیات، metadata، وضعیت چرخهٔ حیات، فایل‌های پیوست و زمان‌ها است. وضعیت اولیهٔ جزئیات و فایل‌های پیوست به‌ترتیب با تنظیمات auto_publish_comment_detail و auto_publish_attachment فروشگاه تعیین می‌شود.

ارسال دوباره برای همان comment_id، محصول و variant، جزئیات قبلی را به‌روزرسانی می‌کند. product_variant_id باید متعلق به product_id باشد (در غیر این صورت 400 با پیام Invalid ProductVariantID) و product_rate الزامی و غیرصفر است. اگر جزئیات دیگرِ همان نظر روی‌هم ۵۰ فایل پیوست یا ۵۰ مگابایت داشته باشند، درخواست با 400 رد می‌شود.

عملیات مدیریتی بازخورد

دریافت فهرست نظرها (پیش‌فرض page_size برابر 10 و حداکثر 50؛ پارامتر اختیاری sort_by با مقدار order_rate یا created_at به‌صورت صعودی مرتب می‌کند):

curl --get "$BASE_URL/feedbacks/admin/comments" \
  --header "X-API-Key: $API_KEY" \
  --data-urlencode "page_number=1" \
  --data-urlencode "page_size=20"
{ "page_number": 1, "page_size": 20, "total": 1, "results": [] }

دریافت یک نظر:

curl --request GET "$BASE_URL/feedbacks/admin/comments/comment-id" \
  --header "X-API-Key: $API_KEY"

انتشار یا بایگانی جزئیات نظر:

curl --request PATCH "$BASE_URL/feedbacks/admin/comments/details/detail-id/publish" \
  --header "X-API-Key: $API_KEY"

curl --request PATCH "$BASE_URL/feedbacks/admin/comments/details/detail-id/archive" \
  --header "X-API-Key: $API_KEY"

انتشار یا بایگانی فایل پیوست (در حال حاضر فقط attachment_id استفاده می‌شود و detail_id مسیر بررسی نمی‌شود):

curl --request PATCH "$BASE_URL/feedbacks/admin/comments/details/detail-id/attachments/attachment-id/publish" \
  --header "X-API-Key: $API_KEY"

curl --request PATCH "$BASE_URL/feedbacks/admin/comments/details/detail-id/attachments/attachment-id/archive" \
  --header "X-API-Key: $API_KEY"

وضعیت جزئیات و فایل پیوست را در یک درخواست به‌روزرسانی کنید. مقدارهای مجاز life_cycle_status عبارت‌اند از SUBMITTED، PUBLISHED و ARCHIVED.

مقدار {id} در مسیر در حال حاضر توسط controller خوانده نمی‌شود. شناسهٔ واقعی نظر را در comment_id ارسال کنید.

curl --request PATCH "$BASE_URL/feedbacks/admin/comments/comment-id/statuses" \
  --header "X-API-Key: $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "comment_id": "comment-id",
    "comment_detail_updates": [
      {
        "comment_detail_id": "detail-id",
        "product_id": "101",
        "life_cycle_status": "PUBLISHED",
        "attachment_updates": [
          { "attachment_id": "attachment-id", "life_cycle_status": "PUBLISHED" }
        ]
      }
    ]
  }'

APIهای کیف پول

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

متد مسیر دسترسی
GET /users/wallet/balance JWT کاربر (Authorization)
GET /wallet/transactions API key یا JWT کاربر
POST /wallet/management_transaction فقط JWT کاربر God (API key پذیرفته نمی‌شود)
GET /admin/wallet/transactions/{user_id} API key + مجوز خواندن کیف پول
POST /admin/wallet/transactions API key + مجوز به‌روزرسانی کیف پول و دسترسی routeهای کاربر
GET /admin/wallet/transactions/quota API key + مجوز خواندن کیف پول

دریافت ماندهٔ کیف پول کاربر فعلی

این مسیر زیرمجموعهٔ /users است و API key برای آن پذیرفته نمی‌شود. JWT کاربر را در Authorization (به‌صورت خام یا با پیشوند Bearer) ارسال کنید؛ بدون JWT معتبر پاسخ 403 است. اگر کیف پول فروشگاه غیرفعال باشد، enabled: false و balance: 0 برمی‌گردد. balance بر حسب تومان است.

curl --request GET "$BASE_URL/users/wallet/balance" \
  --header "Authorization: $USER_TOKEN"
{
  "result": { "enabled": true, "balance": 125000 },
  "error": "",
  "error_code": 0,
  "status": 200
}

دریافت تراکنش‌های کاربر فعلی

این endpoint تراکنش‌های کیف پولِ کاربرِ احراز هویت‌شده را برمی‌گرداند. با API key، کاربر جاری همان سوپرادمین فروشگاه است؛ برای دیدن تراکنش‌های یک مشتری از /admin/wallet/transactions/{user_id} استفاده کنید. درخواست بدون احراز هویت 400 می‌گیرد. مقدار پیش‌فرض page_number برابر 1 و page_size برابر 10 (حداکثر 100) است.

curl --get "$BASE_URL/wallet/transactions" \
  --header "X-API-Key: $API_KEY" \
  --data-urlencode "page_number=1" \
  --data-urlencode "page_size=20"

مبالغ تراکنش بر حسب تومان و از دید کاربر علامت‌دار هستند. meta_data همیشه وجود دارد و اگر سرویس کیف پول تراکنش را به سفارش متصل کرده باشد شامل order_id است (در غیر این صورت {}). reason رشتهٔ آزاد سرویس کیف پول است؛ برای تراکنش‌های مدیریتی یکی از edit_order، cancel_order، edit_shipping_cost، edit_cashback، gift یا others است.

{
  "result": {
    "transactions": [
      {
        "reason": "gift",
        "created_at": "2026-07-19T10:00:00Z",
        "amount": 50000,
        "meta_data": { "order_id": "ORDER-IDENTIFIER" }
      }
    ],
    "page_size": 20,
    "page_number": 1
  },
  "error": "",
  "error_code": 0,
  "status": 200
}

مسیر تولیدشده /wallet/transactions است (به‌صورت جمع).

انجام تراکنش مدیریتی مستقیم بین دو کیف پول

این endpoint موقت فقط برای کاربر God است و با API key قابل فراخوانی نیست. JWT کاربر God را (در نمونه GOD_TOKEN) در Authorization ارسال کنید و هدر X-API-Key نفرستید، چون با وجود آن Authorization نادیده گرفته می‌شود. مقدار amount بدون تبدیل به سرویس کیف پول ارسال می‌شود و بنابراین بر حسب ریال است. مقدار type: 1 تراکنش عادی بین دو کیف پول، 2 شارژ، 3 برداشت.

curl --request POST "$BASE_URL/wallet/management_transaction" \
  --header "Authorization: $GOD_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "from_wallet_id": "source-wallet-id",
    "to_wallet_id": "destination-wallet-id",
    "amount": 500000,
    "type": 1,
    "reason": "manual adjustment",
    "source_name": "sazito-shop"
  }'

در صورت خطای سرویس کیف پول، پاسخ 400 با پیام خطای انجام تراکنش است.

{
  "result": { "success": true, "time": "2026-07-19T10:00:00Z" },
  "error": "",
  "error_code": 0,
  "status": 200
}

دریافت تراکنش‌های یک کاربر (مدیریت)

به مجوز خواندن کیف پول نیاز دارد. ساختار تراکنش‌ها و صفحه‌بندی پاسخ با endpoint تراکنش‌های کاربر فعلی یکسان است (page_size حداکثر 100). user_id باید عددی و غیرصفر باشد و وجود کاربر بررسی نمی‌شود.

curl --get "$BASE_URL/admin/wallet/transactions/123" \
  --header "X-API-Key: $API_KEY" \
  --data-urlencode "page_number=1" \
  --data-urlencode "page_size=20"

افزایش یا کاهش اعتبار کیف پول کاربر (مدیریت)

به مجوز به‌روزرسانی کیف پول و دسترسی routeهای کاربر نیاز دارد. amount مثبت اعتبار کیف پول را افزایش و مقدار منفی آن را کاهش می‌دهد. مبلغ درخواست بر حسب تومان است و controller پیش از فراخوانی سرویس کیف پول آن را به ریال تبدیل می‌کند.

reason_id مفهوم
1 ویرایش سفارش
2 لغو سفارش
3 ویرایش هزینهٔ ارسال
4 ویرایش cashback
5 هدیه
6 سایر
curl --request POST "$BASE_URL/admin/wallet/transactions" \
  --header "X-API-Key: $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": 123,
    "amount": 50000,
    "reason_id": 5,
    "send_sms": true
  }'
{
  "result": { "success": true, "remaining": 175000 },
  "error": "",
  "error_code": 0,
  "status": 200
}

remaining ماندهٔ کیف پول کاربر پس از تراکنش (تومان) است. این عملیات با 400 ناموفق می‌شود اگر: کیف پول فروشگاه غیرفعال باشد، سقف ماهانهٔ تعداد تراکنش‌های مدیریتی فروشگاه (ماه شمسی) پر شده باشد، user_id یا amount صفر باشد، reason_id خارج از 1 تا 6 باشد، یا مبلغ کاهش از ماندهٔ کیف پول بیشتر باشد. وجود کاربر در فروشگاه بررسی نمی‌شود. هر تراکنش موفق، صرف‌نظر از مبلغ، یک واحد از سهمیهٔ ماهانه را مصرف می‌کند. send_sms اختیاری است (پیش‌فرض false) و پیامک فقط در صورت داشتن شمارهٔ موبایل و سهمیهٔ پیامک ارسال می‌شود.

دریافت سهمیهٔ تراکنش فروشگاه (مدیریت)

مقادیر، تعداد تراکنش‌های مدیریتی کیف پول در ماه شمسی جاری هستند (نه مبلغ). limit سقف اختصاصی فروشگاه یا در نبود آن سقف پلن است و remaining هرگز منفی نمی‌شود.

curl --request GET "$BASE_URL/admin/wallet/transactions/quota" \
  --header "X-API-Key: $API_KEY"
{
  "result": { "limit": 1000, "usage": 125, "remaining": 875 },
  "error": "",
  "error_code": 0,
  "status": 200
}

خطاها

endpointهای بازخورد معمولاً همراه با یک status HTTP، بدنهٔ زیر را بازمی‌گردانند:

{ "message": "error description" }

endpointهای کیف پول معمولاً بدنهٔ زیر را بازمی‌گردانند:

{ "errors": { "message": "localized error description" } }

رد شدن درخواست توسط سیاست دسترسی (کاربر ناشناس، نبود مجوز، یا غیرفعال بودن قابلیت تجربه) در هر دو گروه با 403 و بدنهٔ {"message": "User is not allowed to do the action"} برمی‌گردد. خطاهای سرویس تجربه با همان status سرویس (400، 500 یا 504) برگردانده می‌شوند و message شامل متن خام پاسخ آن سرویس است. خطاهای اعتبارسنجی و خطاهای سرویس کیف پول 400 با بدنهٔ errors برمی‌گردانند. این endpointها 401 برنمی‌گردانند.