Skip to Content
مستندات متریکس همواره در حال بهبود است! 🚀 آخرین به‌روزرسانی‌ها را از اینجا دنبال کنید.
مستندات فنیRest APITroubleshooting

عیب‌یابی API (API Troubleshooting)

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

۱. مشکلات احراز هویت و دسترسی (Authentication & Access Issues)

  • خطای 403 Forbidden:

    • دلیل ۱: API Key اشتباه یا نامعتبر.
      • راه‌حل: APP_ID و API_Key خود را از بخش تنظیمات اپلیکیشن در پنل متریکس مجدداً بررسی کنید.
    • دلیل ۲: تنظیم WhiteList IP در پنل.
      • توضیح: اگر در پنل متریکس برای API خود WhiteList IP تنظیم کرده‌اید، فقط درخواست‌هایی از IPهای مجاز پاسخ داده می‌شوند.
      • راه‌حل: اطمینان حاصل کنید که درخواست‌های شما از IPهای ثبت شده در WhiteList ارسال می‌شوند یا تنظیمات WhiteList را در پنل بررسی و در صورت نیاز موقتاً غیرفعال کنید.

  • افشا شدن Server API Key:

    • نکته امنیتی: Server API Key نباید هرگز در کد سمت کلاینت (وب یا اپلیکیشن موبایل) استفاده یا افشا شود.
    • راه‌حل: اگر Server API Key شما لو رفت یا به اشتباه در معرض دید قرار گرفت، فوراً در پنل متریکس نوع آن را به Client تغییر دهید و سپس یک API Key جدید بسازید و جایگزین کنید.

۲. مشکلات مربوط به فرمت و داده (Data Format & Content Issues)

  • خطای 400 Bad Request:

    • دلیل احتمالی: ساختار JSON نامعتبر یا فیلدهای ناقص/اشتباه.
    • راه‌حل:
      • مطمئن شوید بدنه درخواست شما JSON معتبر است.
      • تمامی فیلدهای اجباری (type, id, time, name/customName و شناسه‌های کاربری مربوطه) را بررسی کنید.
      • نوع داده هر فیلد (مانند time و birthday به صورت عددی Long، revenue به صورت Double) را مطابق مستندات بررسی کنید.

  • رویدادها در پنل نمایش داده نمی‌شوند اما کد 200 OK دریافت شده:

    • توضیح: دریافت کد 200 OK فقط به معنای موفقیت‌آمیز بودن ارسال درخواست به سرور است و لزوماً به معنی پردازش صحیح رویداد نیست.
    • دلایل احتمالی:
      • رویداد تکراری: اگر یک رویداد را با metrixUserId ثابت و time یکسان ارسال کنید، سیستم متریکس آن را به صورت خودکار تکراری تشخیص داده و حذف (Drop) می‌کند.
      • customUserId یا metrixUserId نادرست/ناقص.
      • name یا customName نامعتبر یا خالی.
    • راه‌حل:
      • مطمئن شوید برای هر پیام id یکتا و برای هر رویداد time صحیح و منطقی ارسال می‌کنید.
      • صحت شناسه‌های customUserId و metrixUserId را بررسی کنید.
      • از صحت name یا customName و پیروی از Taxonomy اطمینان حاصل کنید.

۳. مشکلات مربوط به کانال‌های پیام‌رسانی (Messaging Channel Issues)

  • عدم دریافت پیام (Push/SMS/Email):
    • راه‌حل: قبل از تست از طریق API، حتماً ارسال پیام از طریق پنل متریکس برای کانال مورد نظر (مثلاً Push Notification یا SMS) را تست کرده باشید. این کار اطمینان می‌دهد که تنظیمات کانال شما در پنل صحیح است.

۴. مشکلات اتصال سرور (Server Connectivity Issues)

  • عدم برقراری ارتباط با Endpoint متریکس:

    • دلیل احتمالی: فایروال سرور شما، مشکلات شبکه، یا DNS Resolution ناموفق.
    • راه‌حل‌ها:
      • بررسی وضعیت DNS: مطمئن شوید سرور شما می‌تواند آدرس entry.metrix.ir را به IP مربوطه تبدیل کند. می‌توانید از دستور dig یا nslookup در ترمینال سرور خود استفاده کنید: 
        dig entry.metrix.ir
        یا 
        nslookup entry.metrix.ir
      • تست اتصال (Ping/Telnet/cURL): بررسی کنید آیا سرور شما می‌تواند به Endpoint متریکس دسترسی پیدا کند.
        • با Telnet (برای پورت 443): 
          telnet entry.metrix.ir 443
          اگر اتصال برقرار شود، صفحه‌ای خالی یا پیام “Connected” را مشاهده خواهید کرد. در غیر این صورت، مشکل در فایروال یا شبکه وجود دارد.
        • با cURL (تست ساده اتصال): 
          curl -v https://entry.metrix.ir/
          این دستور جزئیات اتصال را نشان می‌دهد و می‌تواند به شناسایی مشکلات SSL/TLS یا شبکه کمک کند.
      • بررسی فایروال سرور: مطمئن شوید فایروال سرور شما اجازه دسترسی به پورت 443 (HTTPS) و دامنه entry.metrix.ir را می‌دهد.
      • بررسی لاگ‌های شبکه: لاگ‌های شبکه سرور خود را برای هرگونه خطای اتصال یا رد شدن درخواست‌ها بررسی کنید.

  • خطاهای سرور (5xx Server Error) یا Timeout:

    • دلیل احتمالی: این خطاها معمولاً به مشکلات موقتی در سمت سرور متریکس یا مشکلات شبکه گسترده‌تر اشاره دارند.
    • راه‌حل: مشکل ممکن است موقتی باشد. درخواست را مجدداً ارسال کنید (با مکانیزم Retry و Exponential Backoff). اگر ادامه داشت، با پشتیبانی تماس بگیرید.

۵. تماس با پشتیبانی

اگر با وجود بررسی‌های بالا، همچنان با مشکلی مواجه هستید، لطفاً با تیم پشتیبانی متریکس تماس بگیرید. برای تسریع فرآیند عیب‌یابی، اطلاعات زیر را حتماً ارسال کنید:

  • APP_ID شما.
  • درخواست curl کامل مربوط به مشکل (شامل Headers و Body).
  • پاسخ دریافتی از سرور متریکس (شامل کد وضعیت HTTP و بدنه پاسخ).
  • تاریخ و زمان دقیق وقوع مشکل (UTC).
  • هرگونه پیام خطای مربوطه از لاگ‌های سرور شما.
FAQsWeb