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

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

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

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

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

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