"إعلانات الخدمات المحلّية" الشاملة لاستعلام حالة التاجر من خلال واجهة برمجة التطبيقات

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

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

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

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

ما الذي يحتوي عليه حالة التاجر

يحتوي الحقل 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. يحتوي الردّ أيضًا على رمز تعريف صفحة (إذا كانت ليست الصفحة الأخيرة) لطلب البحث عن الصفحة التالية.

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

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

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