وب سرویس جستجو در اشخاص و شرکت‌ها (Search API)

در این قسمت به بررسی وب‌سرویس جستجو در اشخاص و شرکت‌ها (Search API) می‌پردازیم. این سرویس به شما امکان می‌دهد تا بر اساس نام، شناسه ملی، کد ملی یا کد پستی، اطلاعات مربوط به اشخاص و شرکت‌ها را جستجو کنید.

این سرویس یک متن ورودی را دریافت می‌کند و جستجو را در میان اشخاص و شرکت‌ها انجام می‌دهد. نتایج جستجو در دو لیست مجزا برای اشخاص و شرکت‌ها بازگردانده می‌شود.

نحوه استفاده:

روش درخواست (HTTP Method): GET

آدرس درخواست (Endpoint):

{{baseUrl}}/Search?term={{term}}

جایگزین‌های متغیرها:
{{baseUrl}}: آدرس پایه API (https://api.rasm.io/API)
{{term}}: متن جستجو که می‌تواند شامل نام، کد ملی، شناسه ملی یا کد پستی باشد.

پارامترهای ورودی:

• term: متن جستجو که در میان اطلاعات اشخاص و شرکت‌ها جستجو می‌شود. این پارامتر به صورت String بوده و می‌تواند شامل نام، کدملی یا شناسه ملی باشد.

مثال درخواست:

curl --location --request GET 'https://api.rasm.io/API/Search?term=امیر محبعلی نژاد' \
--header 'X-Key: {{XKEY}}'

پاسخ نمونه:

در اینجا یک نمونه پاسخ برای درخواست جستجو در اشخاص و شرکت‌ها آورده شده است:

{
  "companies": {
    "hits": {
      "total": {
        "value": 2
      },
      "hits": [
        {
          "_source": {
            "id": 14009396050,
            "title": "پیشگامان رسمی پردازش دانا",
            "registrationNo": "564196",
            "registrationDate": "2020-08-31T00:00:00"
          }
        }
      ]
    }
  },
  "people": {
    "hits": {
      "total": {
        "value": 1
      },
      "hits": [
        {
          "_source": {
            "id": 4900221112,
            "title": "امیر محبعلی نژاد",
            "isValidNationalCode": true
          }
        }
      ]
    }
  }
}

توضیحات فیلدهای خروجی:

بخش شرکت‌ها (Companies):

• companies.hits.total.value: تعداد شرکت‌های یافت شده.
• companies.hits.hits[]._source: اطلاعات شرکت‌های یافت شده که شامل شناسه ملی، عنوان، شماره ثبت و تاریخ ثبت است.

بخش اشخاص (People):

• people.hits.total.value: تعداد اشخاص یافت شده.

• people.hits.hits[]._source: اطلاعات اشخاص یافت شده که شامل شناسه ملی، نام، و وضعیت صحت کد ملی است.

• Relation: نشان‌دهنده نوع رابطه بین مقدار فیلد “total” و تعداد واقعی نتایج جستجو است. مقدار “gte” به معنی “بزرگتر یا مساوی” است که نشان می‌دهد حداقل 10000 نتیجه موجود است.
• Value: تعداد کل نتایج بازگشتی توسط جستجو را نشان می‌دهد. در اینجا مقدار آن 10000 است.
• Max score: بالاترین امتیاز مستندات در مجموعه نتایج جستجو است که نشان می‌دهد کدام مستند بیشترین تطابق را با جستجو داشته است.
• Score: امتیاز اختصاص داده‌شده به هر سند، که درجه تطابق آن را با جستجوی انجام شده نشان می‌دهد.
• Id: شناسه منحصربه‌فرد سندی است که توسط در دیتابیس جستجو به هر آیتم اختصاص داده می‌شود.
• EntityId: شناسه منحصربه‌فرد مرتبط با موجودیت (entity) است. کد ملی برای شخص و شناسه ملی برای شرکت.
• EntityType: نوع موجودیت (entity) را مشخص می‌کند، شرکت، شخص یا محصول.
• CompanyCount: تعداد شرکت های او (اگر شخص باشد)
• FavoriteListEntityCount: مربوط به لیست های رسمیو است و در وب سرویس معنی ندارد و همیشه 0 است
• Score: امتیاز رسمیو که به این موجودیت داده شده است. بر اساس معیار های مختلف یک امتیاز داده شده تا بزرگی شرکت یا شخص مشخص شود.
  PlaceOfIssue: محل صدور شخص
• Views: تعداد بازدید موجودیت در رسمیو

نکات مهم:

• جستجو بر اساس نام، کد ملی یا شناسه ملی می‌تواند نتایج متفاوتی را بازگرداند. بهتر است برای نتایج دقیق‌تر، از شناسه ملی یا کد ملی استفاده کنید.
• در صورتی که هیچ نتیجه‌ای پیدا نشود، مقدار total برابر با ۰ خواهد بود.

خطاهای احتمالی:

• 400 Bad Request: پارامتر ورودی term معتبر نیست.
• 404 Not Found: موردی با متن جستجوی وارد شده یافت نشد.

---

نتیجه‌گیری:

در این قسمت، نحوه استفاده از وب سرویس جستجو در اشخاص و شرکت‌ها را بررسی کردیم. این سرویس به شما امکان می‌دهد تا به راحتی اطلاعات مرتبط با اشخاص و شرکت‌ها را جستجو و دریافت کنید.