وب سرویس سمت‌های یک شخص حقیقی (Person Roles API)

15 مهر 1403

مستندات API

در این قسمت به بررسی وب‌سرویس سمت‌های یک شخص حقیقی (Person Roles API) می‌پردازیم. این سرویس به شما امکان می‌دهد تا اطلاعات مربوط به سمت‌های رسمی یک شخص حقیقی در شرکت‌ها را دریافت کنید.

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

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

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

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

{{baseUrl}}/Person/{{PersonId}}/Companies

جایگزین‌های متغیرها:

{{baseUrl}}: آدرس پایه API (https://api.rasm.io/API)
{{PersonId}}: کد ملی شخص حقیقی (مثلاً 4900221112)

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

PersonId: کد ملی شخص حقیقی. این پارامتر الزامی است.

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

curl --location --request GET 'https://api.rasm.io/API/Person/4900221112/Companies' \
--header 'X-Key: {{XKEY}}'

پاسخ نمونه:

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

[
    {
        "id": 3736291,
        "companyId": 14005798500,
        "personId": 4900221112,
        "positionId": 15,
        "startDate": "2018-04-28T00:00:00",
        "endDate": null,
        "byNewsId": 14022798,
        "duration": "",
        "company": {
            "id": 14005798500,
            "registrationNo": "490948",
            "title": "ژاو ایده تحقق",
            "address": "تهران، خیابان شهید محمد بخشی، پلاک 12",
            "postalCode": "1588834155"
        },
        "position": {
            "id": 15,
            "title": "مدیرعامل",
            "firstRole": "مدیرعامل",
            "secondRole": "رئیس هیئت مدیره"
        }
    }
]

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

id: شناسه داخلی تخصیص سمت.
companyId: شناسه ملی شرکت.
personId: کد ملی شخص حقیقی.
positionId: شناسه داخلی سمت.
startDate: تاریخ شروع سمت به فرمت YYYY-MM-DD.
endDate: تاریخ پایان سمت (در صورت وجود).
byNewsId: شماره آگهی روزنامه رسمی مرتبط با این سمت.
duration: مدت زمانی که فرد در این سمت فعالیت کرده است.
company: شامل اطلاعات شرکت، مانند شناسه ملی، شماره ثبت، عنوان شرکت، آدرس و کد پستی.
position: شامل اطلاعات مربوط به سمت فرد، مانند عنوان سمت، اولین سمت و دومین سمت (در صورت وجود).

نکات مهم:

تاریخ شروع و پایان: برخی سمت‌ها ممکن است تاریخ پایان نداشته باشند که به معنی فعال بودن سمت است.
مدت زمان فعالیت: فیلد duration ممکن است در برخی موارد خالی باشد و باید از فیلدهای startDate و endDate برای محاسبه استفاده شود.

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

400 Bad Request: پارامتر ورودی کد ملی اشتباه است.
404 Not Found: شخصی با کد ملی داده‌شده و سمت مرتبط یافت نشد.
401 Unauthorized: کلید API اشتباه است یا وجود ندارد.

نتیجه‌گیری:

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