تحميل شعار وصورة غلاف وصور

أرفق شعارًا وصورة غلاف وصورًا للمعرض بموقع عبر عناوين URL، واعرض المرفقات، وميّز الصورة الرئيسية بنجمة، وأزل ما لم يعد مناسبًا.

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

1. التحميل عبر عنوان URL

يأخذ POST /locations/photos القيمة input.locationId ومصفوفة input.photos. يوضع عنوان URL لكل عنصر في حقل اسمه photo، وليس url. اضبط type صراحةً على LOGO أو COVER أو ADDITIONAL؛ ويُخزّن العنصر الذي لا يحتوي على type بوصفه صورة إضافية.

curl -X POST https://listingsapi.com/api/v4/locations/photos \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photos": [      { "photo": "https://cdn.example.com/jenny-home/logo.png", "type": "LOGO" },      { "photo": "https://cdn.example.com/jenny-home/cover.jpg", "type": "COVER" },      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" }    ]  }}'

{  "data": {    "addLocationPhotos": {      "success": true,      "request": {},      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "databaseId": 5878931, "type": "LOGO", "starred": false,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png" },        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": false }      ],      "errors": null    }  }}

احتفظ بقيمة id لكل صورة: فهي ما تأخذه نقطتا النهاية للتمييز بنجمة والإزالة. تؤدي إعادة تحميل LOGO أو COVER إلى استبدال الموجود. تُخزّن الدفعة الصغيرة مباشرةً ضمن معالجة الطلب بهذا الشكل. أما الدفعة الكبيرة فتُضاف إلى قائمة الانتظار: يُعاد photos فارغًا وتُضبط قيمة request.requestId. حدّد مسار التنفيذ بناءً على وجود requestId، ثم استعلم دوريًا من GET /locations/photos/requests/{requestId}.

curl https://listingsapi.com/api/v4/locations/photos/requests/e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a \-H "Authorization: API $LISTINGSAPI_KEY"

2. عرض المرفقات

يُعيد GET /locations/{locationId}/photos كل ملفات الوسائط المرفقة بالموقع في مصفوفة بسيطة. استخدمه للتحقق من غياب الشعار أو صورة الغلاف قبل التحميل، ولجمع المعرّفات للخطوتين التاليتين. يقبل المسار المعرّف بترميز base64 أو الرقم دون ترميز.

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/photos \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "mediaFilesOfLocation": [      { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "categoryName": "Logo", "categoryId": "4", "starred": false, "viewsCount": 0 },      { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "categoryName": "Additional", "categoryId": "12", "starred": true, "viewsCount": 143 }    ]  }}

تكون قيمة categoryName هي Logo أو Cover أو Additional. يُعيد الموقع الذي لا يحتوي على وسائط مصفوفة فارغة، وليس خطأً.

3. تمييز الصور الإضافية بنجمة

يميّز POST /locations/photos/star الصور الإضافية لمنحها أولوية في العرض على منصات النشر التي تدعم الصور المميّزة. يمكن تمييز صور ADDITIONAL فقط بنجمة، بحد أقصى 4 لكل موقع؛ وتؤدي إضافة صورة خامسة إلى فشل الاستدعاء بأكمله مع SY15012. يمكنك أيضًا تمرير starred: true على عنصر وقت التحميل.

curl -X POST https://listingsapi.com/api/v4/locations/photos/star \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="],    "starred": true  }}'

{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "type": "ADDITIONAL", "starred": true }      ],      "error": null    }  }}

مفتاح الاستجابة هو starUnstarLocationPhotos، ويحمل error مفردًا، وليس مصفوفة errors. تتحكم العلامة starred في جسم الطلب في الإجراء: أرسل false لإلغاء التمييز بنجمة. تأخذ دوال SDK القيمة المنطقية نفسها.

4. إزالة صورة

يفصل POST /locations/photos/remove الصور الإضافية عن الموقع باستخدام المعرّف. يبيّن removedCount عدد الصور التي فُصلت، لذا فإن 0 مع errors: null يعني أن أيًا من تلك المعرّفات لم يكن مرفقًا بهذا الموقع.

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

{  "data": {    "removeLocationPhotos": {      "removedCount": 1,      "errors": null    }  }}

يمكن إزالة صور ADDITIONAL فقط هنا. لتغيير الشعار أو صورة الغلاف، حمّل صورة جديدة بقيمة type تلك لتحل محل القديمة. تفصل الإزالة الملف عن الموقع؛ ولا تحذفه بالضرورة من مكتبة الوسائط لديك.

5. كيفية استخدام منصات النشر لكل خانة

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

• تحديث موقع: ساعات العمل وفترات الإغلاق وفئات Google في السجل نفسه.
• التحقق من حالة إدراج النشاط التجاري والروابط المنشورة: الاطّلاع على وقت نشر منصات النشر للصور الجديدة.
• تحميل الصور، جلب الصور، تمييز الصور بنجمة، إزالة الصور، وحالة التحميل المجمع: الصفحات المرجعية.
• مراجع SDK: الصور في Python والصور في Node.