/api/v4/connected-accounts/confirm-matchesتأكيد مطابقات الربط
يؤكد المطابقات المقترحة بين المواقع وإدراجات الأنشطة التجارية التي تُرجعها نقطة نهاية اقتراحات الربط.
المعلمات
النص الأساسي
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| input | object | مطلوب | Wrapper object. The entire request body must be nested under `input`. |
| input.matchRecordIds | array of strings | مطلوب | Match-record global IDs to confirm: the standard base64 of `<MatchRecordType>:<matchedDataDatabaseId>`, built from a connection-suggestion record. At least one ID is required. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "input": { "matchRecordIds": [ "R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M=" ] }}الاستجابات
200Request accepted. `success` is `true` when every match was confirmed; when some IDs could not be confirmed they are listed in `failedIds` and `success` is `false`.
{ "data": { "confirmConnectMatches": { "failedIds": null, "success": true } }}400Bad request, the body was not wrapped in `input`, `matchRecordIds` was omitted (error message: `Field value.matchRecordIds of required type [ID!]! was not provided`), or `input` carried a field the endpoint does not accept.
401Unauthenticated, missing or invalid API key.
يقبل عمليات الإقران المقترحة بين المواقع وإدراجات الأنشطة التجارية ويؤكدها، مما ينشئ الربط الفعلي بين مواقع Listings API وإدراجات الأنشطة التجارية المقابلة لها على Google Business Profile أو Facebook. بعد التأكيد، يبدأ إدراج النشاط التجاري بالمزامنة مع موقع Listings API المطابق له.
بنية الطلب. يجب تغليف جسم الطلب داخل كائن input، والحقل الوحيد الذي يقبله هو matchRecordIds، وهو مصفوفة من معرّفات سجلات المطابقة ([ID!]!، مطلوب). يُرفض إرسال جسم مسطّح (غير مغلّف) بحالة HTTP 400، ويُرفض كذلك أي حقل غير معروف داخل input، مثل connectedAccountId أو الحقل الأقدم matchIds (Unknown field "connectedAccountId"). يُتجاهل أي مفتاح زائد خارج input بدلاً من رفضه. لا يوجد حقل connectedAccountId في هذا الطلب؛ إذ يُستدل على الحساب من سجلات المطابقة نفسها.
إنشاء قيمة matchRecordIds. لا يحتوي سجل اقتراح الربط على id. خذ قيمتي matchedDataDatabaseId وaccountType منه، واكتبهما بعد اسم نوع سجل المطابقة مفصولَين بنقطتين رأسيتين، ثم رمّز الناتج باستخدام base64:
import base64 TYPES = { "GMB": "GmbLocationMatchedData", "FB": "FbLocationMatchedData", "APPLE": "AppleLocationMatchedData",} def match_record_id(record): raw = f"{TYPES[record['accountType']]}:{record['matchedDataDatabaseId']}" return base64.b64encode(raw.encode()).decode()إذا لم يُفكّ ترميز المعرّف إلى أحد هذه الأنواع الثلاثة، فلن تحصل على 400. يُرجع الاستدعاء HTTP 200 مع success: false ومن دون failedIds، لذا تحقّق من success في كل استدعاء.
تمثّل نقطة النهاية هذه الخطوة الأخيرة في سير عمل الربط الجماعي: اربط الحساب، وشغّل POST /connected-accounts/trigger-matches لإنشاء الاقتراحات، وراجعها باستخدام نقطة نهاية اقتراحات الربط، ثم أكّد السجلات المعتمدة هنا.
حالة استخدام: قبول المطابقات التي تمت مراجعتها دفعة واحدة. بعد أن تستورد وكالة حساب Google الخاص بعميل وتراجع عمليات الإقران المقترحة في واجهة المستخدم الخاصة بك، أرسل matchRecordIds المعتمدة في استدعاء واحد بدلاً من استدعاء لكل مطابقة. أرسل فقط المعرّفات التي اعتمدها المشغّل، بحيث تبقى الاقتراحات التي لم تُراجع أو الاقتراحات الخاطئة دون تغيير.
لا يؤدي تأكيد المطابقة إلى إرسال البيانات فوراً إلى Google أو Facebook؛ بل يربط موقع Listings API بإدراج النشاط التجاري على منصة النشر، بحيث تمر تحديثات إدراج النشاط التجاري اللاحقة عبر هذا الربط. يُرجع الاستدعاء الناجح success: true مع failedIds: null. عندما يتعذر تأكيد معرّف واحد أو أكثر (على سبيل المثال، سجل مطابقة غير معروف أو سبق استخدامه، أو مطابقة أُرشف موقعها منذ ذلك الحين)، تُرجع هذه المعرّفات في failedIds وتكون قيمة success هي false، لتتمكن من إعادة المحاولة أو عرض حالات الفشل فقط. يحتوي failedIds على معرّفات قاعدة البيانات بعد فك ترميزها، وليس القيم المرمّزة التي أرسلتها، لذا طابقها مع matchedDataDatabaseId. لاختيار إدراج نشاط تجاري واحد يدوياً دون المرور بالاقتراحات، استخدم نقطة نهاية connect-listing بدلاً من ذلك.
curl -X POST 'https://listingsapi.com/api/v4/connected-accounts/confirm-matches' \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H 'Content-Type: application/json' \ -d '{ "input": { "matchRecordIds": [ "R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M=" ] } }'