إنشاء listings scan

الاسم	النوع	مطلوب	الوصف
input	object	مطلوب	Wrapper object. The entire request body must be nested under `input`.
input.name	string	مطلوب	Business name, up to 150 characters.
input.street	string	مطلوب	Street address, up to 200 characters.
input.city	string	مطلوب	City, up to 100 characters.
input.stateIso	string	اختياري	State or province code, up to 50 characters. Required for every country except `GB`.
input.postalCode	string	اختياري	Postal code, up to 20 characters. Required for every country except `NG` and `AE`.
input.countryIso	string	مطلوب	Two-letter ISO 3166-1 country code, for example `US`.
input.phone	string	مطلوب	Business phone number with 6 to 15 digits. Local formats are read in the context of `countryIso`, and an international format with a leading `+` works too.

يبدأ فحصًا لنشاط تجاري واحد. يتحقق الفحص من وجود إدراج النشاط التجاري ومدى دقته عبر شبكة الأدلة: الخرائط ومحركات البحث مثل Google وBing وApple Maps وYelp وFacebook وMapQuest، ومجمّعات البيانات والأدلة المحلية، ومساعدي الذكاء الاصطناعي مثل ChatGPT وGemini. بحسب البلد، يتحقق الفحص من نحو 60 دليلًا كحد أقصى. لا يلزم أن يكون النشاط التجاري موقعًا في حسابك، لذا يمكنك تدقيق بيانات نشاط تجاري لعميل محتمل أو لعميل قبل إعداده للاستخدام.

يعيد الاستدعاء النتيجة فورًا ويكون الفحص في حالة QUEUED. تُجرى عمليات التحقق من الأدلة في الخلفية، وتُقرأ النتيجة باستخدام GET /listings/scans/{scanId}.

حالة استخدام: تدقيق إدراجات نشاط تجاري لعميل محتمل. تجمع أداة المبيعات لديك اسم النشاط التجاري وعنوانه ورقم هاتفه. أنشئ فحصًا، واحفظ scan.id المُعاد، واقرأ الفحص المكتمل من data.scan عند وصول الحدث listing_scan.completed. يوفر summary الملخص (عدد الأدلة التي عثرت على النشاط التجاري، وعدد الأدلة التي كانت بياناته فيها دقيقة)، ويوفر results[] التفاصيل الخاصة بكل دليل لعرضها في التقرير.

حالة استخدام: التحقق من حالة نشاط تجاري تديره بالفعل. افحص بيانات النشاط التجاري لأحد مواقعك. يتعرف الفحص عليه ويُنشئ نتائجه من إدراجات النشاط التجاري الفعلية لذلك الموقع بدلًا من البحث مجددًا (انظر إعادة الاستخدام والفحوص المجانية).

كيف ينتهي الفحص

يمر الفحص بالحالتين QUEUED وIN_PROGRESS، ثم ينتهي بالحالة COMPLETED أو FAILED. تكتمل معظم الفحوص خلال 1 إلى 7 دقائق. إذا لم يستجب أحد الأدلة بعد نحو 15 دقيقة، تُضبط نتيجته على UNAVAILABLE ويكتمل الفحص بالنتائج الأخرى.

يُفضّل استخدام webhook. يُرسل كل من الحدثين listing_scan.completed وlisting_scan.failed مرة واحدة لكل فحص، مع كائن الفحص نفسه الذي يعيده GET /listings/scans/{scanId}، بما في ذلك النتائج. تُرسل هذه الأحداث إلى الحسابات التي فعّلت webhooks ولديها عنوان URL لـ webhook تم التحقق منه، وتُوقّع مثل سائر الأحداث. انظر listing_scan.completed.
استخدم الاستعلام الدوري كخيار بديل. إذا لم تتمكن من استقبال webhooks، فاقرأ الفحص كل 15 ثانية حتى تصبح قيمة status هي COMPLETED أو FAILED. لا يحقق الاستعلام بمعدل أسرع أي فائدة، ويستهلك حصتك من الطلبات.

الحقول المطلوبة

الحقول name وstreet وcity وcountryIso وphone مطلوبة دائمًا. يعتمد اشتراط حقلين على البلد:

الحقل	مطلوب	الاستثناءات
`stateIso`	نعم	غير مطلوب في `GB`.
`postalCode`	نعم	غير مطلوب في `NG` و`AE`.

إذا كانت القيمة مفقودة أو بتنسيق غير صحيح، يُرفض الطلب مع SY83003، ويذكر الخطأ اسم الحقل. يجب أن يتكون phone من 6 إلى 15 رقمًا، وأن يتكون countryIso من حرفين.

إعادة الاستخدام والفحوص المجانية

لا يُجري الفحص بحثًا جديدًا دائمًا. يوضح الحقل source في الفحص المُعاد مصدر نتائجه:

`source`	متى تحصل عليه
`DIRECTORY_SEARCH`	بحث جديد في الأدلة. هذا هو النوع الوحيد الذي يستهلك حصتك الشهرية.
`RECENT_SCAN`	أجرى أي مستخدم فحصًا للنشاط التجاري نفسه خلال آخر 7 أيام، لذا نُسخت نتائجه. يوضح `resultsAsOf` وقت جمع البيانات. يُعاد الفحص وهو بالفعل في حالة `COMPLETED`.
`LOCATION_LISTINGS`	يطابق النشاط التجاري أحد مواقعك الخاصة من حيث رقم الهاتف والرمز البريدي والبلد. تأتي النتائج من إدراجات النشاط التجاري الفعلية لذلك الموقع، وتُعيّن قيمة `locationId`، وتتضمن كل نتيجة `syncStatus`.

إذا فحصت النشاط التجاري نفسه مجددًا خلال 7 أيام، يُعاد الفحص الموجود في حسابك بدلًا من إنشاء فحص جديد، مع reused: true في الاستجابة. لا يبدأ فحص جديد ولا يُرسل webhook جديد، لذا اقرأ الفحص المُعاد (فقد يكون قيد التنفيذ) بدلًا من انتظار حدث آخر. وينطبق السلوك نفسه عند فحص أحد مواقعك مجددًا خلال فترة إعادة الاستخدام.

الحصة الشهرية

تشمل الخطط المدفوعة Listings scans ضمن حصة شهرية تعتمد على خطتك. وهي غير متاحة مع تصريح ليوم واحد مجاني للبيئة التجريبية. لا يُحتسب ضمن الحصة إلا فحص DIRECTORY_SEARCH جديد. الحالات التالية مجانية:

تكرار الفحص للنشاط التجاري نفسه خلال 7 أيام (reused: true)،
نسخة RECENT_SCAN،
فحص LOCATION_LISTINGS،
فحص يفشل، إذ لا يُحتسب.

تُجدَّد الحصة مع بداية فترة الفوترة لحسابك. تتضمن كل استجابة لطلب إنشاء quota مع limit وused وremaining وresetsAt، حتى عند رفض الطلب. راجع الخطط والإضافات.

الأخطاء

عند رفض طلب إنشاء، تُعاد استجابة HTTP 200 تتضمن scan: null وسبب الرفض في errors[]، لذا تحقّق من errors ولا تكتفِ برمز الحالة. لا يمكن للمفاتيح المخصصة للقراءة فقط إنشاء فحوص: وهذه هي حالة الفشل الوحيدة على مستوى الطلب، وتُعاد فيها استجابة HTTP 400 مع SY90016.

الرمز	المعنى	الإجراء المطلوب
`SY83001`	Listings scans غير متاحة في خطتك.	استخدم حسابًا مشتركًا في خطة مدفوعة. لا تتيح تصاريح اليوم الواحد تشغيل الفحوص.
`SY83002`	استُنفدت الحصة الشهرية. تتضمن الرسالة الحد ووقت تجديد الحصة، ويُعاد `quota`.	انتظر حتى `quota.resetsAt`، أو تواصل معنا بشأن زيادة الحصة. إعادة استخدام فحص حديث مجانية.
`SY83003`	أحد الحقول مفقود أو غير صالح. يذكر `contextInfo` اسم الحقل ضمن `field`.	صحّح ذلك الحقل وأعد إرسال الطلب.
`SY83004`	الفحوص غير متاحة لذلك البلد.	تحقّق من `countryIso`. تذكر الرسالة الرمز الذي رُفض.
`SY83010`	الفحوص غير متاحة مؤقتًا.	أعد المحاولة لاحقًا.

تتوفر القائمة الكاملة للرموز في رموز الأخطاء.

ملاحظات.

يجب تغليف جسم الطلب داخل كائن input.
تحقّق من errors، وليس من حالة HTTP. يُعاد طلب الإنشاء المرفوض باستجابة HTTP 200.
تُوحَّد صيغة أرقام الهواتف قبل تشغيل الفحص، ويُعدّ الطلبان اللذان يختلفان فقط في التنسيق أو حالة الأحرف أو المسافات متعلقين بالنشاط التجاري نفسه.
يُحتسب كل طلب إنشاء طلبًا واحدًا ضمن حد معدل الطلبات، مهما كان عدد الأدلة التي يتحقق منها الفحص.
يُحتفظ بالفحص لمدة 90 يومًا. بعد ذلك، تُعيد قراءته استجابة 404 مع SY83005.
يتطلب هذا الاستدعاء مفتاحًا بصلاحية Write (الكتابة).

الاستجابات

200The scan was accepted and is `QUEUED`. `reused` is `false` and `results` is empty until directories are checked. Wait for the `listing_scan.completed` webhook, or poll the scan.

Response

{  "data": {    "createListingScan": {      "reused": false,      "scan": {        "id": "TGlzdGluZ1NjYW46N2MxZTRmNTItOWEzYi00ZDY4LWIwZTEtNWYyYThjOWQzZTQ3",        "status": "QUEUED",        "source": "DIRECTORY_SEARCH",        "locationId": null,        "resultsAsOf": null,        "createdAt": "2026-11-05T07:00:41Z",        "startedAt": null,        "completedAt": null,        "business": {          "name": "Franklin Barbecue",          "street": "900 E 11th St",          "city": "Austin",          "stateIso": "TX",          "postalCode": "78702",          "countryIso": "US",          "phone": "+15126531187"        },        "summary": {          "total": 0,          "found": 0,          "accurate": 0,          "inaccurate": 0,          "notFound": 0,          "pending": 0,          "unavailable": 0        },        "failure": null,        "results": []      },      "quota": {        "limit": 50,        "used": 6,        "remaining": 44,        "resetsAt": "2026-11-23T12:38:03Z"      },      "errors": []    }  }}

200The request was rejected, so **no scan was created**. The error is reported in `errors[]` on an `HTTP 200`, `scan` is `null`, and `quota` still returns the current allowance. This example is a phone number with too few digits.

{  "data": {    "createListingScan": {      "reused": false,      "scan": null,      "quota": {        "limit": 50,        "used": 5,        "remaining": 45,        "resetsAt": "2026-11-23T12:38:03Z"      },      "errors": [        {          "code": "SY83003",          "message": "SY83003: Invalid value for phone",          "contextInfo": [            {              "key": "field",              "value": "phone"            }          ]        }      ]    }  }}

400A read-only key was used on this write (`SY90016`). Use a Write key.

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.