مرجع api / commercial/companies/search/

جستجوی شرکت

جستجو بر اساس نام، شناسه ملی یا شماره ثبت.

GETcommercial/companies/search/

جستجوی شرکت بر اساس نام، شناسه ملی، یا شماره ثبت. حداقل یکی از این سه پارامتر باید ارسال شود. جستجوی نام به‌صورت case-insensitive icontains انجام می‌شود.

نیازمند اعتبار20 درخواست در دقیقه

هدرها

نام	نوع	الزامی	توضیحات
`X-API-KEY`	string	بله	کلید api شما.

X-API-KEYstringبله

کلید api شما.

پارامترهای کوئری

نام	نوع	الزامی	توضیحات
`idempotency_key`	string	بله	UUID یکتا.
`company_name`	string	خیر	بخشی از نام شرکت (حداقل یکی از سه پارامتر جستجو الزامی است).
`national_id`	string	خیر	شناسه ملی شرکت (تطابق کامل).
`registration_number`	string	خیر	شماره ثبت شرکت (تطابق کامل).
`limit`	integer default: `20`	خیر	حداکثر تعداد نتایج (۱ تا ۱۰۰، پیش‌فرض ۲۰).

idempotency_keystringبله

UUID یکتا.

company_namestring

بخشی از نام شرکت (حداقل یکی از سه پارامتر جستجو الزامی است).

national_idstring

شناسه ملی شرکت (تطابق کامل).

registration_numberstring

شماره ثبت شرکت (تطابق کامل).

limitinteger

default: 20

حداکثر تعداد نتایج (۱ تا ۱۰۰، پیش‌فرض ۲۰).

نمونه درخواست

curl -X GET 'https://saravar.com/api/commercial/companies/search/?company_name=نمونه&limit=10&idempotency_key=550e8400-e29b-41d4-a716-446655440000' \
  -H 'X-API-KEY: <YOUR_API_KEY>'

پاسخ

نام	نوع	الزامی	توضیحات
`debit_transaction_id`	integer \| null	بله	شناسه تراکنش.
`total_charged`	integer	بله	مبلغ کسر شده بر حسب IRR.
`data`	Company[]	بله	آرایه‌ای از { id_code, company_name, national_id, registration_number, company_type, registration_date }.

debit_transaction_idinteger | nullبله

شناسه تراکنش.

total_chargedintegerبله

مبلغ کسر شده بر حسب IRR.

dataCompany[]بله

آرایه‌ای از { id_code, company_name, national_id, registration_number, company_type, registration_date }.

نکات قیمت‌گذاری و رفتار

هزینه به ازای هر نتیجه بازگشتی پس از فیلتر محاسبه می‌شود. اگر limit=100 باشد و ۱۲ نتیجه برگردد، فقط ۱۲ واحد محاسبه می‌شود.
حداقل کارمزد به ازای هر فراخوانی موفق اعمال می‌شود.

خطاها

کد وضعیت	علت	اقدام پیشنهادی
`400`	هیچ پارامتر جستجویی ارسال نشده، idempotency_key مفقود، یا insufficient_credits.	حداقل یکی از company_name / national_id / registration_number را ارسال کنید و کلید idempotency معتبر بفرستید.
`401`	کلید api نامعتبر است.	کلید فعال بسازید.
`403`	احراز هویت ملی تکمیل نشده.	احراز هویت را تکمیل کنید.
`429`	از سقف نرخ عبور کرده‌اید.	backoff اعمال کنید.

400کد وضعیت

علتهیچ پارامتر جستجویی ارسال نشده، idempotency_key مفقود، یا insufficient_credits.

اقدام پیشنهادیحداقل یکی از company_name / national_id / registration_number را ارسال کنید و کلید idempotency معتبر بفرستید.

401کد وضعیت

علتکلید api نامعتبر است.

اقدام پیشنهادیکلید فعال بسازید.

403کد وضعیت

علتاحراز هویت ملی تکمیل نشده.

اقدام پیشنهادیاحراز هویت را تکمیل کنید.

429کد وضعیت

علتاز سقف نرخ عبور کرده‌اید.

اقدام پیشنهادیbackoff اعمال کنید.