الاستعلام عن حالة التاجر عبر واجهة برمجة التطبيقات

حالات الاستخدام

توفّر Google Maps Booking API طريقتَين يمكن استخدامهما لاسترداد حالة التجّار الفرديين بشكل آلي لعمليات دمج مختلفة في "مركز الإجراءات" أو مستودع إعلانات الخدمات المحلّية.

حالات استخدام Merchant Status API:

• يمكنك تحسين أدوات إدارة علاقات العملاء الحالية لتوضيح كيفية عرض مستودع العملاء على منصة "مركز الإجراءات".
• يمكنك إنشاء لوحة بيانات لتتبُّع حالة المستودع وحالة المطابقة للتجّار.
• يمكنك بشكل آلي استرداد حالات المطابقة وقابلية الحجز للتجار وتصحيح أي معلومات غير صحيحة لتحسين جودة البيانات.

ما الذي تتضمّنه حالة التاجر؟

تتضمّن MerchantStatus المعلومات التالية:

• حالة مستودع التاجر: تنطبق على كل من التجّار الذين يقدّمون الحجوزات و/أو في قوائم الانتظار.
• حالة مطابقة التاجر: تشمل تفاصيل حول بيانات النشاط التجاري المطابقة
• بالنسبة إلى إعلانات الخدمات المحلّية من Google فقط) مقدّم خدمة التاجر المطابق: يشمل الرقم التعريفي للعميل وفئات الخدمات.
• عناوين URL التي توضِّح كيفية ظهور التاجر للتاجر من خلال ميزة "الحجز عبر Google"

البحث عن حالة تاجر واحد

يمكنك الحصول على حالة تاجر واحد باستخدام inventory.partners.merchants.getStatus:

GET https://mapsbooking.googleapis.com/v1alpha/inventory/partners/{partnerId}/merchants/{merchantId}/status

إليك نموذج لرمز Python (يمكنك الاطّلاع على أمثلة بمزيد من اللغات هنا):

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_account

credentials = service_account.Credentials.from_service_account_file(
    './your_key.json')
scoped_credentials = credentials.with_scopes(
    ['https://www.googleapis.com/auth/mapsbooking'])
authed_session = AuthorizedSession(scoped_credentials)

response = authed_session.get('https://partnerdev-mapsbooking.googleapis.com' +
    '/v1alpha/inventory/partners/123456789/merchants/001/status')

في ما يلي مثال على استجابة من النوع MerchantStatus:

  {
    "name": "partners/123456789/merchants/001/status",
    "merchantName": "Foo Bar Restaurant",
    "inputGeoInfo": {
      "unstructured_address": "123 Foo Bar Street, Mountain View"
    },
    "processingStatus": "COMPLETED",
    "bookingStatus": {
      "hasValidFutureInventory": true
    },
    "waitlistStatus": {
      "hasValidWaitlistService": true
    }
    "geoMatch": {
      "name": "Foo Bar Restaurant",
      "formattedAddress": "123 Foo Bar St, Mountain View, CA 94043",
      "placeId": "ChIAAAAAAAAABBBBBBBB"
    },
    "directUrls": [
      {
        "type": "BOOKING",
        "url": "https://reserve-partnerdev.sandbox.google.com/maps/reserve/v/dine/m/Nwaaaaa"
      },
      {
        "type": "WAITLIST",
        "url": "https://reserve-partnerdev.sandbox.google.com/maps/reserve/v/wait/c/iDbbbbb"
      }
    ]
  }

استرداد حالات التاجر بشكل مجمّع

يمكنك استرداد حالات جميع التجّار أو مجموعة التجّار الذين يستوفون شروط مطابقة أو مستودع معيّن باستخدام inventory.partners.merchants.status.list. على سبيل المثال، يمكنك إجراء هذه المكالمة لجذب جميع التجّار غير المطابقين الذين لديهم مستودع صالح للحجز لتواريخ مستقبلية:

GET https://mapsbooking.googleapis.com/v1alpha/inventory/partners/{partnerId}/merchants/status?pageSize=50&bookingInventoryStatusRestrict=HAS_VALID_FUTURE_INVENTORY&geoMatchRestrict=GEO_UNMATCHED

سيظهر نموذج الإجابة كما يلي:

  {
    "merchantStatuses": [
      {
        "name": "partners/123456789/merchants/002/status",
        "merchantName": "Bar Foo Restaurant",
        "inputGeoInfo": {
          "unstructured_address": "234 Bar Foo Street, Mountain View"
        },
        "processingStatus": "COMPLETED",
        "bookingStatus": {
          "hasValidFutureInventory": true
        },
        "waitlistStatus": {},
      },
      ...
      {
        "name": "partners/123456789/merchants/080/status",
        "merchantName": "Baz Restaurant",
        "inputGeoInfo": {
          "unstructured_address": "345 Baz Street, Mountain View"
        },
        "processingStatus": "COMPLETED",
        "bookingStatus": {
          "hasValidFutureInventory": true
        },
        "waitlistStatus": {
          "hasValidWaitlistService": true
        },
      },
    ],
    "nextPageToken": "AAABBBB"
  }

سيحتوي هذا الرد على 50 MerchantStatus تستوفي شروط الفلترة ويتم ترتيبها حسب merchant_id. وتحتوي الاستجابة أيضًا على رمز مميّز للصفحة (إذا لم تكن الصفحة الأخيرة) لطلب البحث في الصفحة التالية.

يُرجى العلم أنّه يجب أن تكون شروط الفلترة متسقة في جميع الصفحات.

أفضل الممارسات

وبما أنّ حالات التاجر لا تتغير كثيرًا في معظم الأوقات، ننصح بتخزين النتائج التي تم استردادها في ذاكرة التخزين المؤقت واسترجاعها بشكل دوري (على سبيل المثال كل بضع ساعات) من خلال طلبات بحث جديدة. وقد يحدّ "مركز الإجراءات" من طلباتك إذا تبيّن أنّ عدد الطلبات في الثانية كبير جدًا.