اعثر على المواقع وأرشف ما لم تعد تديره منها

ابحث بكلمة مفتاحية، واسترجع المواقع باستخدام رموز المتاجر ومعرّفاتها دفعة واحدة، وجدول أرشفة الفروع المغلقة في نهاية دورة الفوترة، وألغِ أرشفة مجدولة.

تتيح 3 نقاط نهاية للقراءة العثور على المواقع باستخدام مفاتيح مختلفة: البحث بنص حر، والبحث برمز المتجر، والبحث بالمعرّف. الأرشفة عملية كتابة مجدولة: يظل الموقع نشطًا حتى نهاية دورة الفوترة الحالية، ثم تتوقف مزامنته وتتوقف فوترته. يمكنك إلغاء الأرشفة حتى تلك اللحظة.

1. البحث بكلمة مفتاحية

يطابق GET /locations/search?query= عبارة البحث مع الاسم وعنوان الشارع والمدينة ومعرّف المتجر، ويعيد اتصالًا قائمًا على مؤشر: edges[].node مع pageInfo.endCursor، مع تقسيم النتائج إلى صفحات باستخدام first وafter. احذف query لاستعراض الحساب بأكمله على صفحات.

curl "https://listingsapi.com/api/v4/locations/search?query=Acme&first=10" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "searchLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Acme Kitchen",            "storeId": "ACME-NYC-001",            "approved": "APPROVED",            "archived": false,            "archivalScheduledAt": null          }        }      ],      "pageInfo": { "endCursor": "TG9jYXRpb246MTgwMDI4OQ==", "hasNextPage": false, "total": 1 }    }  }}

تعني مصفوفة edges الفارغة عدم وجود أي تطابق، وهو ما ينبغي التحقق منه قبل الإنشاء عندما لا تكون متأكدًا مما إذا كان المتجر موجودًا بالفعل. تقبل كلتا حزمتَي SDK المعامل fields لقصر المطابقة على name أو store_id فقط.

2. البحث برمز المتجر

إذا كانت أنظمتك تستخدم رمز المتجر الخاص بك مفتاحًا للمواقع، فاسترجعها مباشرة باستخدام GET /locations-by-store-codes. المعامل storeCodes عبارة عن مصفوفة JSON مرمّزة بتنسيق URL. لا تظهر الرموز التي ليس لها تطابق في النتيجة.

curl -G https://listingsapi.com/api/v4/locations-by-store-codes \--data-urlencode 'storeCodes=["ACME-NYC-001","ACME-NYC-002"]' \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "getLocationsByStoreCodes": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "archived": false      }    ]  }}

3. استرجاع البيانات الكاملة لدفعة من المعرّفات

عندما تكون لديك بالفعل معرّفات base64 من مخزن البيانات الخاص بك أو من حمولة webhook، يعيد GET /locations-by-ids السجل الكامل لكل منها في استدعاء واحد. تُسترجع المواقع المؤرشفة أيضًا، لذا اقرأ archived وarchivedAt لتمييزها. تُستبعد المعرّفات غير المعروفة دون إشعار؛ لذا قارن الأعداد.

curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ==","TG9jYXRpb246MTgwMDI5MA=="]' \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "getLocationsByIds": [      { "id": "TG9jYXRpb246MTgwMDI4OQ==", "databaseId": 1800289, "name": "Acme Kitchen", "archived": false, "archivedAt": null },      { "id": "TG9jYXRpb246MTgwMDI5MA==", "databaseId": 1800290, "name": "Acme Kitchen Brooklyn", "archived": false, "archivedAt": null }    ]  }}

للحصول على مجموعة فرعية من الحساب بأكمله تُحدَّد على جانب الخادم، يقبل GET /locations أيضًا المعامل filter المرمّز بتنسيق JSON، مثل التصفية حسب حالة الموافقة. راجع سرد جميع المواقع.

4. أرشفة المواقع التي لم تعد تديرها

يأخذ POST /locations/archive المعامل input.locationIds ويعيد عنصر result واحدًا لكل موقع. الأرشفة مجدولة وليست فورية: ينتقل كل موقع إلى ARCHIVE_SCHEDULED، ويستمر في المزامنة حتى نهاية دورة الفوترة الحالية، ويُؤرشف عند إنشاء الفاتورة التالية. ومن تلك اللحظة، تتوقف مزامنته مع منصات النشر وتتوقف فوترته.

curl -X POST https://listingsapi.com/api/v4/locations/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ==", "TG9jYXRpb246MTgwMDI5MA=="]  }}'

{  "data": {    "archiveLocations": {      "errors": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null },        { "locationId": "TG9jYXRpb246MTgwMDI5MA==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null }      ]    }  }}

اقرأ success لكل عنصر: لا يؤدي وجود معرّف واحد غير صالح إلى منع معالجة بقية الدفعة. أثناء جدولة الأرشفة، يكون الحقل archivalScheduledAt الخاص بالموقع معيّنًا في نتائج السرد والبحث. لا يمكن تحديث موقع مؤرشف حتى يُعاد تنشيطه. إذا كانت webhooks مُعدّة، يُطلَق حدث profile.deleted؛ وهذا حذف منطقي، ولا يوجد حذف نهائي.

5. إلغاء أرشفة مجدولة

قبل انتهاء الدورة، يعيد POST /locations/cancel_archive باستخدام المعرّفات نفسها المواقع إلى ACTIVE وتستمر الفوترة. بمجرد أرشفة الموقع بالكامل، يعيد هذا الاستدعاء 404 لذلك الموقع. لا يؤدي الإلغاء إلى إطلاق أي حدث webhook.

curl -X POST https://listingsapi.com/api/v4/locations/cancel_archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="] } }'

{  "data": {    "cancelLocationsArchive": {      "errors": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ACTIVE", "success": true, "errors": null }      ]    }  }}

تتطلب كلتا حزمتَي SDK وسيطين موضعيين إضافيين، هما نوع التحديد ومعرّف changedBy، وترسلانهما مع locationIds. لا يحتاج جسم طلب REST إلا إلى المعرّفات.

الخطوات التالية

• إضافة موقع: استدعاء الإنشاء، ولماذا يتيح تعيين storeId فيه تنفيذ الخطوة 2.
• تحديث موقع: تصحيح تفاصيل المواقع التي عثرت عليها بدلاً من أرشفتها.
• البحث عن مواقع، وجلب المواقع حسب رموز المتاجر، وجلب المواقع حسب المعرّفات، وأرشفة المواقع، وإلغاء الأرشفة المجدولة: الصفحات المرجعية.