مرجع api / commercial/companies/role-check/

اعتبارسنجی نقش

بررسی اینکه آیا شخصی هم‌اکنون نقش مشخصی را در شرکت دارد.

POSTcommercial/companies/role-check/

اعتبارسنجی این که آیا شخصی هم‌اکنون نقش مشخصی را در یک شرکت دارد یا خیر. اگر role_type ارسال نشود، صرفاً وجود هر نقش فعال بررسی می‌شود. این endpoint با persons/role-check/ معادل است.

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

هدرها

نام	نوع	الزامی	توضیحات
`X-API-KEY`	string	بله	کلید api شما.
`Content-Type`	string default: `application/json`	بله	باید application/json باشد.

X-API-KEYstringبله

کلید api شما.

Content-Typestringبله

default: application/json

باید application/json باشد.

بدنه درخواست

نام	نوع	الزامی	توضیحات
`company_national_id`	string	بله	شناسه ملی شرکت (۱۱ رقم).
`person_national_id`	string	بله	شناسه ملی شخص (۱۰ رقم).
`role_type`	string	خیر	نوع نقش برای بررسی. مقادیر مجاز: ceo، chairman، vice_chairman، inspector، alternative_inspector، liquidator، board_member، signing_authority. در صورت عدم ارسال، وجود هر نقش فعال بررسی می‌شود.
`idempotency_key`	string	بله	UUID یکتا.

company_national_idstringبله

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

person_national_idstringبله

شناسه ملی شخص (۱۰ رقم).

role_typestring

نوع نقش برای بررسی. مقادیر مجاز: ceo، chairman، vice_chairman، inspector، alternative_inspector، liquidator، board_member، signing_authority. در صورت عدم ارسال، وجود هر نقش فعال بررسی می‌شود.

idempotency_keystringبله

UUID یکتا.

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

curl -X POST 'https://saravar.com/api/commercial/companies/role-check/' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_national_id": "12345678901",
    "person_national_id": "1234567890",
    "role_type": "ceo",
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
  }'

پاسخ

نام	نوع	الزامی	توضیحات
`debit_transaction_id`	integer \| null	بله	شناسه تراکنش کسر اعتبار.
`total_charged`	integer	بله	مبلغ کسر شده بر حسب IRR.
`data.is_valid`	boolean	بله	آیا نقش معتبر و فعال است.
`data.role_type`	string \| null	بله	نوع نقش تأیید شده (در صورت is_valid=true).
`data.role_name`	string \| null	بله	نام فارسی نقش.
`data.date_assigned`	string \| null	بله	تاریخ شروع نقش.
`data.expire_date`	string \| null	بله	تاریخ پایان نقش (در صورت وجود).

debit_transaction_idinteger | nullبله

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

total_chargedintegerبله

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

data.is_validbooleanبله

آیا نقش معتبر و فعال است.

data.role_typestring | nullبله

نوع نقش تأیید شده (در صورت is_valid=true).

data.role_namestring | nullبله

نام فارسی نقش.

data.date_assignedstring | nullبله

تاریخ شروع نقش.

data.expire_datestring | nullبله

تاریخ پایان نقش (در صورت وجود).

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

یک واحد به ازای هر فراخوانی موفق محاسبه می‌شود — صرف‌نظر از اینکه نتیجه is_valid=true یا false باشد.
حداقل کارمزد به ازای هر فراخوانی موفق اعمال می‌شود.

خطاها

کد وضعیت	علت	اقدام پیشنهادی
`400`	پارامتر اجباری مفقود، role_type نامعتبر، یا insufficient_credits.	بدنه را بررسی کنید و در صورت نیاز کیف‌پول را شارژ کنید.
`401`	کلید api نامعتبر است.	کلید فعال بسازید.
`403`	احراز هویت ملی تکمیل نشده.	احراز هویت را تکمیل کنید.
`404`	شرکت یا شخص یافت نشد.	شناسه‌های ملی را بررسی کنید.
`429`	از سقف نرخ عبور کرده‌اید.	backoff اعمال کنید.

400کد وضعیت

علتپارامتر اجباری مفقود، role_type نامعتبر، یا insufficient_credits.

اقدام پیشنهادیبدنه را بررسی کنید و در صورت نیاز کیف‌پول را شارژ کنید.

401کد وضعیت

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

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

403کد وضعیت

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

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

404کد وضعیت

علتشرکت یا شخص یافت نشد.

اقدام پیشنهادیشناسه‌های ملی را بررسی کنید.

429کد وضعیت

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

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