معرفی
با API بازگو میتوانید بازخورد مشتری را مستقیم از سرویس خودتان (سایت، اپلیکیشن، سیستم پشتیبانی، CRM یا ربات) به فضای کاری بفرستید. هر بازخورد مثل بازخوردهای دیگر در صندوق بازخورد قرار میگیرد، بهصورت خودکار تحلیل میشود و نتیجهٔ تحلیل را از همین API دریافت میکنید.
| مورد | مقدار |
|---|---|
| آدرس پایه | https://api.bazgo.site |
| نسخه | v1 — همهٔ مسیرها با /v1 شروع میشوند |
| قالب داده | JSON با کدگذاری UTF-8 |
| احراز هویت | کلید API در سرآیند Authorization |
| محدودیت نرخ | ۱۲۰ درخواست در دقیقه برای هر کلید |
| حداکثر حجم بدنه | ۹۶ کیلوبایت |
کلید API دسترسی کامل به دادهٔ فضای کاری شما دارد. آن را فقط در سرور نگه دارید و هرگز در کد مرورگر، اپلیکیشن موبایل یا مخزن گیت قرار ندهید.
شروع سریع
۱. در داشبورد به ورودیها ← اتصال API بروید و یک کلید با دسترسی «ثبت و خواندن» بسازید. مدت اعتبار را میتوانید دائمی بگذارید.
۲. کلید را که با bz_ شروع میشود کپی کنید و در متغیر محیطی سرورتان قرار دهید:
۳. اولین بازخورد را بفرستید:
پاسخ، شناسهٔ بازخورد را برمیگرداند:
۴. چند ثانیه بعد نتیجهٔ تحلیل را بخوانید:
احراز هویت
همهٔ درخواستها به /v1 باید کلید API را به شکل Bearer در سرآیند Authorization داشته باشند:
سطح دسترسی کلیدها
| نوع کلید | ثبت بازخورد | خواندن بازخورد | خواندن مصرف |
|---|---|---|---|
| ثبت و خواندن | ✓ | ✓ | ✓ |
| فقط خواندن | — | ✓ | ✓ |
چرخهٔ عمر کلید
- هنگام ساخت کلید، مدت اعتبار آن را انتخاب میکنید: دائمی (پیشفرض)، ۳۰ روز، ۹۰ روز یا ۱ سال. کلید دائمی تا وقتی لغوش نکنید کار میکند.
- کلیدی که تاریخ انقضا دارد، پس از آن تاریخ با خطای
401 UNAUTHORIZEDرد و از فهرست کلیدها حذف میشود. پیش از انقضا یک کلید جدید بسازید، سرورتان را بهروز کنید و سپس کلید قدیمی را لغو کنید. - کلید فقط یکبار هنگام ساخت نمایش داده میشود. اگر آن را گم کردید، کلید را لغو و یک کلید تازه بسازید.
- کلید لغوشده بلافاصله از کار میافتد.
- برای هر سرویس یک کلید جدا بسازید تا در صورت نشت، فقط همان اتصال را قطع کنید.
ثبت بازخورد
یک بازخورد جدید در فضای کاری ثبت میکند. تحلیل بهصورت غیرهمزمان انجام میشود؛ بنابراین پاسخ بلافاصله با کد 202 برمیگردد.
سرآیندها
| سرآیند | الزامی | توضیح |
|---|---|---|
Authorization | بله | Bearer و سپس کلید API |
Content-Type | بله | فقط application/json |
Idempotency-Key | خیر (توصیهشده) | شناسهٔ یکتای شما برای این بازخورد؛ ۱ تا ۱۲۸ نویسه از حروف انگلیسی، عدد و _ . : - |
بدنهٔ درخواست
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
text | string | بله | متن بازخورد، ۱ تا ۲۰٬۰۰۰ نویسه. فاصلههای ابتدا و انتها حذف میشود. |
metadata | object | خیر | هر دادهٔ JSON دلخواه مثل شمارهٔ سفارش، شعبه یا شناسهٔ مشتری. کنار بازخورد ذخیره میشود. |
فیلدهای دیگر پذیرفته نمیشوند و خطای VALIDATION_ERROR برمیگردانند.
پاسخ موفق — 202 Accepted
سرآیند Location هم آدرس خواندن همین بازخورد را دارد (/v1/feedback/3f8a1c2e-6b4d-4e1a-9c7f-2d5b8e0a4f61).
هر بازخورد پذیرفتهشده یک تعامل از سهمیهٔ ماهانهٔ فضای کاری مصرف میکند. ارسال تکراری با همان
Idempotency-Keyسهمیه مصرف نمیکند.
خواندن بازخورد و نتیجهٔ تحلیل
وضعیت بازخورد و نتیجهٔ تحلیل آن را برمیگرداند. فقط بازخوردهای همین فضای کاری در دسترساند.
پاسخ — 200 OK
فیلدها
| فیلد | توضیح |
|---|---|
status | new در انتظار تحلیل · analyzed تحلیلشده · needs_attention نیازمند رسیدگی · resolved رسیدگیشده |
priority | اولویت از ۰ تا ۱۰۰؛ هرچه بیشتر، فوریتر |
processing.state | pending در صف تحلیل · complete تمامشده · failed تحلیل پس از چند تلاش ناموفق بود |
analysis | تا پیش از پایان تحلیل null است |
signals.topic | کلید موضوعی که در بخش «برچسبها» تعریف کردهاید |
signals.kind | نوع پیام: complaint، suggestion، compliment، question، request یا other |
signals.satisfaction | رضایت مشتری از ۱ (بسیار ناراضی) تا ۱۰ (بسیار راضی) |
signals.urgency · needsAction · churnRisk | احتمال فوریت، نیاز به اقدام و ریسک ریزش، از ۰ تا ۱ |
signals.relevant | احتمال مرتبط بودن پیام با کسبوکار شما، از ۰ تا ۱ |
signals.confidence | اطمینان مدل به نتیجه، از ۰ تا ۱ |
signals.custom | پاسخ پرسشهای سفارشی شما، به تفکیک کلید؛ فقط اگر تعریف کرده باشید |
دریافت نتیجه با پرسوجوی دورهای
تحلیل معمولاً چند ثانیه طول میکشد. تا وقتی processing.state برابر pending است، با فاصله دوباره درخواست بفرستید:
مصرف و سهمیه
مصرف دورهٔ ماهانهٔ جاری فضای کاری را برمیگرداند. هر دو نوع کلید به این مسیر دسترسی دارند.
دورهها بر اساس ماه میلادی (UTC) هستند. وقتی used به limit برسد، ثبت بازخورد تا ابتدای دورهٔ بعد با خطای QUOTA_EXCEEDED رد میشود.
ارسال دوباره بدون تکرار
شبکه ممکن است قطع شود و ندانید درخواست شما ثبت شده یا نه. با فرستادن سرآیند Idempotency-Key میتوانید با خیال راحت همان درخواست را دوباره بفرستید:
- اولین درخواست با یک کلید، بازخورد را ثبت میکند و
202برمیگرداند. - درخواست بعدی با همان کلید و همان بدنه، بازخورد جدیدی نمیسازد؛ همان شناسه را با کد
200و"replayed": trueبرمیگرداند و سهمیه مصرف نمیکند. - درخواست با همان کلید ولی بدنهٔ متفاوت با خطای
409 IDEMPOTENCY_CONFLICTرد میشود.
بهترین مقدار برای این سرآیند، شناسهای است که در سیستم خودتان یکتاست؛ مثل order-1042 یا ticket:88731.
خطاها
همهٔ خطاها قالب یکسانی دارند:
فیلد fields فقط در خطاهای اعتبارسنجی وجود دارد. برای تصمیمگیری در کد، همیشه از code استفاده کنید، نه message.
| HTTP | code | علت و راهحل |
|---|---|---|
| 400 | INVALID_JSON | بدنه JSON معتبر نیست. |
| 400 | VALIDATION_ERROR | فیلدها یا Idempotency-Key نامعتبرند؛ fields را ببینید. |
| 401 | UNAUTHORIZED | کلید ارسال نشده، اشتباه، منقضی یا لغو شده است. |
| 402 | QUOTA_EXCEEDED | سهمیهٔ ماهانه تمام شده است. |
| 403 | FORBIDDEN | کلید اجازهٔ این کار را ندارد (مثلاً ثبت با کلید فقطخواندنی). |
| 404 | NOT_FOUND | بازخورد یا مسیر پیدا نشد. |
| 409 | IDEMPOTENCY_CONFLICT | این Idempotency-Key قبلاً با بدنهٔ دیگری استفاده شده است. |
| 413 | BODY_TOO_LARGE | بدنه بیش از ۹۶ کیلوبایت است. |
| 415 | UNSUPPORTED_MEDIA_TYPE | سرآیند Content-Type: application/json را بفرستید. |
| 429 | RATE_LIMITED | بیش از ۱۲۰ درخواست در دقیقه؛ طبق سرآیند Retry-After صبر کنید. |
| 500 | INTERNAL_ERROR | خطای سرور. requestId را هنگام تماس با پشتیبانی بفرستید. |
چه خطاهایی را دوباره تلاش کنیم؟ فقط 429 و 5xx را، با فاصلهٔ فزاینده و همان Idempotency-Key. بقیهٔ خطاها با تکرار درست نمیشوند.
نمونهکد
نمونههای زیر یک بازخورد ثبت میکنند و خطاها را مدیریت میکنند. کلید را از متغیر محیطی BAZGO_API_KEY میخوانند.
Node.js / TypeScript
Python
PHP (Laravel)
cURL
بهترین روشها
- کلید را در سرور نگه دارید. اگر بازخورد از مرورگر یا اپلیکیشن میآید، آن را به سرور خودتان بفرستید و از آنجا به بازگو ارسال کنید.
- همیشه
Idempotency-Keyبفرستید. با شناسهٔ یکتای سیستم خودتان، تکرار و مصرف اضافهٔ سهمیه غیرممکن میشود. - ارسال را از مسیر اصلی جدا کنید. بازخورد را در صف یا پسزمینه بفرستید تا کندی شبکه روی تجربهٔ کاربر اثر نگذارد.
- فقط
429و5xxرا دوباره تلاش کنید، با فاصلهٔ فزاینده. - برای کلیدهای مدتدار، جایگزینی را از قبل برنامهریزی کنید و کلید قبلی را پس از جابهجایی لغو کنید. اگر کلیدی ممکن است نشت کرده باشد، فوراً لغوش کنید.