/api/v4/connected-accountsعرض الحسابات المتصلة
يُرجع حسابات Google وFacebook المتصلة بحسابك في Listings API، مع حالة الاتصال وأعداد المواقع المرتبطة.
المعلمات
الاستعلام
| الاسم | النوع | مطلوب | الوصف | الافتراضي |
|---|---|---|---|---|
| page | integer | اختياري | 1-based page number. | 1 |
| perPage | integer | اختياري | Records per page. | 20 |
| publisher | string | اختياري | Narrow to one publisher by account type: `GoogleAccount`, `FacebookAccount`, `AppleAccount`, `YelpAccount`, `TripadvisorAccount`, `LinkedinAccount`, `PinterestAccount`, or `TwitterAccount`. | — |
| status | string | اختياري | Narrow to one connection status: `Connected`, `NotConnected`, or `ConnectionIssue`. Note the mixed case, and that these are not the values the response's own `status` field uses. | — |
الاستجابات
200List of connected accounts with pagination metadata.
{ "data": { "connectedAccountsInfo": { "pageInfo": { "hasNextPage": false, "hasPreviousPage": false, "totalPages": 1, "totalRecords": 1 }, "records": [ { "accountId": "12345", "clientName": "owner@brightsmile-dental.com", "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "connectedAccountType": "GoogleAccount", "connectedLocationsCount": 0, "connectivityIssue": null, "email": "owner@brightsmile-dental.com", "lastFetchMatchesRequestedAt": "2026-07-06 21:43:07 UTC", "remarks": null, "requestMatches": false, "requestMatchesStatus": "MATCH_COMPLETED", "status": "CONNECTED" } ] } }}401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
يُرجع جميع حسابات Google Business Profile وFacebook Pages المصرّح لها بالاتصال بحسابك في Listings API. يتضمن كل سجل حالة الاتصال (status، connectivityIssue)، وعدد المواقع المرتبطة (connectedLocationsCount)، وحالة آخر عملية جلب للمطابقات (requestMatchesStatus).
حالة استخدام: فحص حالة الاتصال قبل المزامنة. استدعِ نقطة النهاية هذه في بداية مهمة ليلية للعثور على الحسابات التي انتهت صلاحية بيانات اعتمادها. يتطلب أي سجل تكون فيه قيمة connectivityIssue غير null أو تكون فيه قيمة status غير CONNECTED أن يعيد العميل منح التفويض عبر خطوات الربط؛ تجاوز هذه السجلات حتى لا تهدر استدعاء trigger-matches باستخدام بيانات اعتماد غير صالحة.
حالة استخدام: تحديد connectedAccountId للاستدعاءات اللاحقة. تعتمد نقاط النهاية trigger-matches وfetch-listings وfolders وdetails جميعها على connectedAccountId. اعرض الحسابات، واختر الحساب الذي تطابق فيه قيمة email العميل، وأعد استخدام قيمة connectedAccountId الخاصة به.
يستخدم تقسيم النتائج إلى صفحات وتصفيتها معاملات استعلام بسيطة وغير متداخلة، وليس JSON: page وperPage وpublisher وstatus. لا يوجد معامل pageInfo أو filters أو sort، ولا توجد طريقة لتغيير الترتيب: تُرتّب النتائج دائمًا حسب البريد الإلكتروني للحساب، بترتيب تصاعدي. يُتجاهل أي شيء آخر ترسله بدلًا من رفضه، لذا يؤدي إرسال pageInfo بصيغة JSON إلى إرجاع الصفحة 1 دون تنبيه.
curl -s 'https://listingsapi.com/api/v4/connected-accounts?page=1&perPage=20&publisher=GoogleAccount&status=Connected' \ -H "Authorization: API $LISTINGSAPI_KEY"لا يستخدم عامل التصفية status والحقل status مجموعة القيم نفسها. يقبل عامل التصفية Connected أو NotConnected أو ConnectionIssue؛ وتكون قيمة status في كل سجل مُرجع هي CONNECTED أو MATCH_IN_PROGRESS أو CONNECTIVITY_ISSUE. إذا أرسلت قيمة status من السجل نفسه في عامل التصفية، فهي قيمة enum غير صالحة وتُرجع 400.
اقرأ pageInfo.hasNextPage وpageInfo.totalPages في الاستجابة لتحديد ما إذا كان ينبغي جلب صفحة أخرى. يُحتسب استدعاء نقطة النهاية هذه ضمن حد معدل الطلبات للحساب، وتتضمن استجابة 429 ترويسة Retry-After.
curl -X GET 'https://listingsapi.com/api/v4/connected-accounts' \ -H "Authorization: API $LISTINGSAPI_KEY"