چگونه به عنوان یک توسعه دهنده نرم افزار، بین نرم افزار خود و نرم افزار حضور وغیاب نوین پرداز ارتباط برقرار نماییم؟

چگونه به عنوان یک توسعه دهنده نرم افزار، بین نرم افزار خود و نرم افزار حضور وغیاب نوین پرداز ارتباط برقرار نماییم؟

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

نرم افزارهای Third-Party (Third-Party Applications):

به برنامه ها یا نرم افزارهایی گفته می شود که توسط توسعه دهنده ای به جز توسعه دهنده نرم افزار اصلی به جهت یکپارچه سازی و افزایش قابلیت ها مورد استفاده قرار می گیرند نرم افزارهای شخص ثالت یا Third-Party Applications گفته می شود. البته گاهی این نرم افزارها ممکن است توسط یک توسعه دهنده و برنامه نویس تولید شده باشند اما در کنار نرم افزار اصلی به عنوان یک افزونه یا نرم افزاری با کاربرد متفاوت مورد استفاده قرار گیرند.

File Exchange

تبادل فایل (File Exchange) یکی از روش های تبادل اطلاعات بین نرم افزار اصلی (First-Party) و نرم افزارهای شخص ثالث (Third-Party) می باشد که از طریق فایل هایی با فرمت هایی مانند: CSV، XML، JSON یا فایل های Excel انجام می گیرد.

Rest API

یکی دیگر از روش های برقراری ارتباط و تبادل اطلاعات بین نرم افزارها استفاده از روش Rest API می باشد که با استفاده از پروتکل های HTTP و HTTPS انجام می شود. مدل تبادل در این روش Pull می باشد یعنی ابتدا نرم افزار درخواست کننده یا همان Third-Party درخواست خود را به یک Endpint که توسط نرم افزار ارائه دهنده یا نرم افزار اصلی در نظر گرفته است، ارسال می کند و نرم افزار اصلی اطلاعات را در فرمت توافق شده مانند JSON به نرم افزار درخواست کننده ارسال می نماید.

Webhook

این اصطلاح نیز یکی دیگر از روش های ارتباطی بین نرم افزارها می باشد که مانند روش Rest API با استفاده از پروتکل های HTTP و HTTPS انجام می شود با این تفاوت که این بار از مدل Push به جای Pull استفاده می شود. در واقع روش ارتباطی Webhook با مدل Push یک روش رویدار محور (Event-Driven) بوده یعنی به محض یک رویداد این بار این نرم افزار اصلی (First-Party) است که اطلاعات را به نرم افزار شخص ثالت (Third-Party) ارسال می نماید. در واقع در این روش Rest API سمت نرم افزار شخص ثالث پیاده سازی شده و اطلاعات در فرمت توافق شده مانند JSON ارسال می شوند.

روش های دریافت اطلاعات نرم افزار حضور و غیاب نوین پرداز توسط نرم افزارهای شخص ثالث (Third-Party Applications)

نرم افزار حضور و غیاب نوین پرداز که بر پایه .Net Framework توسعه یافته است این قابلیت را دارد تا با روش های مختلف: تبادل فایل (File Exchange)، Rest API و Webhook با انواع نرم افزار Third-Party (توسعه یافته با هر نوع زبان برنامه نویسی C#، PHP، Java و…) و پیاده سازی شده روی هر پلتفرم (Web, Windows, Linux و…) تبادل اطلاعات را انجام دهد. یکی از این اطلاعاتی که مورد نیاز نرم افزارهای Third-Party می باشد، ترددهای ثبت شده اشخاص بر روی دستگاه های حضور و غیاب نوین پرداز می باشد.

در ادامه به آموزش روش های ارتباطی با نرم افزار حضور و غیاب نوین پرداز پرداخته شده است:

1. روش تبادل فایل (File Exchange): یکی از قابلیت های نرم افزار حضور و غیاب نوین پرداز این است که در کنار قابلیت چاپ گزارشات، قابلیت دریافت خروجی با فرمت های مختلف از جمله: فرمت های مختلف عکس، PDF، CSV، فایل های Excel، Word وجود دارد که طبق چهارچوب و استانداردهای هر نرم افزار Third-Party می توان این خروجی را دریافت کرد و در نرم افزار مقصد بارگذاری نمود. همانطور که در عکس زیر مشاهده می نمایید، به عنوان مثال یکی از گزارشات قابل دریافت در نرم افزار حضور و غیاب نوین پرداز در حالت پیش نمایش نمایش داده شده و لیست فرمت های قابل دریافت مشخص گردیده.

2. API: نرم افزار حضور و غیاب نوین پرداز از دو روش Rest API و Webhook جهت تبادل اطلاعات با نرم افزارهای Third-Party پشتیبانی می نماید.

دریافت اطلاعات با روش Rest API

طبق توضیحات روش ارتباطی Rest API، در این روش ابتدا باید نرم افزار درخواست کننده (Third-Party)، درخواست های خود را به نرم افزار حضور و غیاب نوین پرداز ارسال نماید. فرآیند آماده سازی نرم افزار حضور و غیاب و تبادل اطلاعات باید طبق الگوریتم زیر انجام گیرد:

1.ابتدا طبق راهنمای زیر در نرم افزار حضور و غیاب نوین پرداز، یک کاربر جدید به همراه رمز تعریف نمایید:

بطور مثال نام کابر «restadmin» و پسورد «1234» می باشد.

– از منوی اطلاعات پایه «1» کاربران «2» را انتخاب نمایید.
– در پنجره لیست کاربران، پس از کلیک بر روی کمه اضافه «1» کلیک نمایید.
– نام کاربر «1» و رمز «2» مورد نظر خود را وارد نمایید و سپس با کلیک بر روی دکمه ثبت «3» اطلاعات را ذخیره کنید.

2.جهت فعالسازی روش دریافت Rest API طبق راهنمای زیر اقدام نمایید:

– ابتدا از منوی امکانات «1» گزینه تنظیمات نرم افزار «2» را انتخاب نمایید.
– در پنجره تنظیمات نرم افزار، سربرگ تنظیمات API «1» را انتخاب نمایید.

ابتدا از فعالسازی Rest API «1» اطمینان حاصل نمایید. سپس در قسمت آدرس Rest API «2» آدرس شبکه سیستمی که نرم افزار حضور و غیاب بر روی آن نصب می باشد و به عنوان یک سرور، همیشه در دسترس خواهد بود را وارد نمایید و در قسمت پورت «3» پورت ارتباطی بین دو نرم افزار را وارد نمایید. دقت داشته باشید این پورت بصورت پیش فرض 7593 می باشد و در صورت نیاز می توانید آن را تغییر دهید.

نکته: در صورتی که بر روی سرور Rest API فایروال فعال دارید، پورت در نظر گرفته را در لیست پورت های قابل دسترسی فایروال اضافه نمایید.

3. ارسال درخواست لاگین توسط نرم افزار Third-Party

در این مرحله نرم افزار Third-Party باید با کمک نام کاربر و رمزی که در مرحله اول تعریف شد، در قالب یک متد «Post» درخواست لاگین را به Endpoint نرم افزار حضور و غیاب نوین پرداز ارسال نماید. قالب درخواست به شکل زیر می باشد:

POST : http://{API Server IP}/api/login

Content type: "application/json"

"Body": {

"username": "restadmin",

"Password": "1234"

{API Server IP}: به جای این پارامتر، آدرس شبکه سرور Rest API که در مرحله دوم الگوریتم توضیح داده شد قرار دهید.

احراز هویت و ایجاد توکن توسط نرم افزار حضور و غیاب نوین پرداز  
   نرم افزار حضور و غیاب نوین پرداز پس از احراز هویت کاربر، یکJWT  (JSON Web Token) ایجاد کرده و برای نرم افزار Third-Party ارسال می نماید.

نمونه پاسخ دریافتی از نرم افزار حضور و غیاب نوین پرداز

    "Status": "Ok",

    "Message": {

        "Token": "eyJhbGci...",

        "Username": "restadmin",

        "Expiration": "2026-06-20T12:57:07Z"

    }

نکته: از این مرحله به بعد، نرم افزار Third-Party باید توکن دریافتی را در هدر (Header) هر درخواستی که به سمت نرم افزار حضور و غیاب نوین پرداز ارسال می نماید، قرار دهد.

Authorization: Bearer <JWT Token>

نکته: از آنجا که توکن (Token) طول عمر کوتاهی دارد، باید بصورت منظم درخواست توکن جدید توسط نرم افزار Third-Party ارسال شود.

نکته: در صورت انقضای توکن ایجاد شده، نرم افزار حضور و غیاب نوین پرداز کد وضعیت 401 را ارسال می نماید.

4. درخواست دریافت تردد/ترددهای ثبت شده

نرم افزار Third-Party درخواست خود را جهت دریافت رکورد/رکوردها (تردد/ترددها) به Endpoint نرم افزار حضور و غیاب نوین پرداز ارسال می نماید.
این درخواست به دو روش زیر امکان پذیر می باشد:

  • درخواست ترددها (رکوردها) بصورت تک به تک

در این نوع درخواست، نرم افزار حضور و غیاب اولین رکوردی که در صف ارسال می باشد را به نرم افزار Third-Party ارسال خواهد کرد. این درخواست در قالب متد «GET» می باشد.

GET : http://{API Server IP}/api/attendance/next

Authorization: Bearer <JWT Token>

نمونه پاسخ دریافتی از نرم افزار حضور و غیاب نوین پرداز

{

    "Status": "Ok",

    "Message": {

        "Guid": "6475bb97-527e-4fc1-944a-30105a7b5a5a",

        "LogTime": "2020-10-19T13:54:00",

        "LogTimeUtc": "2020-10-19T13:54:00+03:30",

        "PersonNo": 3,

        "DeviceInfo": {

            "Name": "1",

            "No": 1,

            "Ip": "192.168.1.224",

            "TcpPort": 5005,

            "SerialNumber": "C45812554960",

            "Modified": "2026-06-20T13:33:57.0291793+03:30",

            "Status": true,

            "Guid": "940feb09-5889-4765-90a9-e21e2e84050a"

        },

        "PersonInfo": {

            "Name": "محمدامین",

            "Family": "علیزاده",

            "FullName": "محمدامین علیزاده",

            "Guid": "ea14565c-9f78-437c-b55a-e7e06e7fe1f7"

        },

        "TypeTaradod": 3,

        "TypeTaradodVacationOrMission": 1,

        "Modified": "2026-06-11T11:51:41.127",

        "DeviceNo": 1

    }

}

  • درخواست ترددها (رکوردها) بصورت گروهی

در این نوع درخواست، نرم افزار Third-Party در قالب یک متد «GET» درخواست دریافت رکوردها را بصورت دسته ای به نرم افزار حضور و غیاب ارسال می نماید.

GET : http://{API Server IP}/api/attendance/search

Authorization: Bearer <JWT Token>

Deviceno: اگر از چند دستگاه حضور و غیاب استفاده می نمایید، توسط این پارامتر می توانید رکوردهای یک دستگاه با شماره خاص را دریافت نمود. بطور مثال:

GET http://{API Server IP}/api/attendance/search?deviceno=2

Personno: با استفاده از این پارامتر، می توان ترددهای یک شخص با کد بخصوص را دریافت نمود. بطور مثال:

GET http://{API Server IP}/api/attendance/search?Personno=125

Modified:

GET http://{API Server IP}/api/attendance/search?Modified=125

Count: با استفاده از این پارامتر، می توان تعداد رکوردهای درخواستی را محدود کرد. بطور مثال

GET http://{API Server IP}/api/attendance/search?Count=2

Skip:

GET http://{API Server IP}/api/attendance/search?Skip=1

نکته: از این پارامترها می توان بصورت ترکیبی استفاده نمود، بطور مثال:

GET http://{API Server IP}/api/attendance/search?deviceno=1& personno=125&count=2

نمونه پاسخ دریافتی از نرم افزار حضور و غیاب نوین پرداز

{

    "Status": "Ok",

    "Message": [

        {

            "Guid": "f7430615-1b13-4345-b57c-9ab38ea20b1b",

            "LogTime": "2020-10-19T13:56:00",

            "LogTimeUtc": "2020-10-19T13:56:00+03:30",

            "PersonNo": 125,

            "DeviceInfo": {

                "Name": "1",

                "No": 1,

                "Ip": "192.168.1.224",

                "TcpPort": 5005,

                "SerialNumber": "C45812554960",

                "Modified": "2026-06-23T09:25:21.6594084+03:30",

                "Status": true,

                "Guid": "940feb09-5889-4765-90a9-e21e2e84050a"

            },

            "PersonInfo": {

                "Name": "معصومه",

                "Family": "حسینی",

                "FullName": "معصومه حسینی",

                "Guid": "db9deeb2-cf81-434d-bfd1-4c1119304315"

            },

            "TypeTaradod": 3,

            "TypeTaradodVacationOrMission": 1,

            "Modified": "2026-06-11T11:51:41.127",

            "DeviceNo": 1

        },

{

            "Guid": "0a7e0aba-8c23-4733-99e4-89ea96594b3a",

            "LogTime": "2020-10-20T09:07:00",

            "LogTimeUtc": "2020-10-20T09:07:00+03:30",

            "PersonNo": 125,

            "DeviceInfo": {

                "Name": "1",

                "No": 1,

                "Ip": "192.168.1.224",

                "TcpPort": 5005,

                "SerialNumber": "C45812554960",

                "Modified": "2026-06-23T09:25:21.6594084+03:30",

                "Status": true,

                "Guid": "940feb09-5889-4765-90a9-e21e2e84050a"

            },

            "PersonInfo": {

                "Name": "معصومه",

                "Family": "حسینی",

                "FullName": "معصومه حسینی",

                "Guid": "db9deeb2-cf81-434d-bfd1-4c1119304315"

            },

            "TypeTaradod": 3,

            "TypeTaradodVacationOrMission": 1,

            "Modified": "2026-06-11T11:51:41.127",

            "DeviceNo": 1

        }

    ]

}

5. ارسال تاییدیه دریافت اطلاعات به نرم افزار حضور و غیاب نوین پرداز

نرم افزار Third-Party پس از دریافت اطلاعات و انجام عملیات های سمت خود مانند: ذخیره سازی در بانک اطلاعاتی، به دلیل جلوگیری از دریافت رکوردهای تکراری باید تاییدیه دریافت اطلاعات را به نرم افزار حضور و غیاب ارسال نماید. این عملیات به دو روش زیر می تواند انجام گیرد:

  • تاییدیه دریافت رکوردها بصورت تک به تک

در این حالت، نرم افزار Third-Party در قالب یک متد «GET» شناسه (IDs) هر رکورد را بصورت تک به تک به Endpoint نرم افزار حضوروغیاب نوین پرداز ارسال می نماید.

نکته: ID همان GUID رکورد دریافتی می باشد.

Post : http://{API Server IP}/api/attendance/ack

Content type: "application/json"

"Body": {

"id": " d8561b29-153d-4e87-8db6-45a9991ac0ea "

}

در مثال زیر نمونه ای از تاییدیه دریافت یک رکورد بخصوص را مشاهده می نمایید.

GET http://{API Server IP}/api/attendance/ ack?id=d8561b29-153d-4e87-8db6-45a9991ac0ea

نمونه پاسخ دریافتی از نرم افزار حضور و غیاب نوین پرداز

{

     "Status": "string",

     "Results": "true"

}

  • تاییدیه دریافت رکوردها بصورت گروهی

در این حالت، نرم افزار Third-Party در قالب یک متد «Post» لیستی از شناسه ها (Guids) را به عنوان رکوردهای دریافت شده به Endpoint نرم افزار حضور و غیاب نوین پرداز ارسال می نماید.

نکته: Guid همان Guid رکورد دریافتی می باشد.

POST : http://{API Server IP}/api/attendance/ack/batch

Content type: "application/json"

Authorization: Bearer <JWT Token>

"Body": {

    "Guids": [

        "acb15d3a-7c65-4c75-ba6b-0f5668197135",

        "34fcca6c-5107-4922-9dc4-447868ac7b1b"

    ]

}

نمونه پاسخ دریافتی از نرم افزار حضور و غیاب نوین پرداز

{

    "Status": "Ok",

    "Message": {

        "Results": [

            true,

            true

        ]

}

روش تست کردن دریافت اطلاعات از نرم افزار حضور و غیاب نوین پرداز با روش Rest API

جهت تست دریافت اطلاعات با روش Rest API کافیست از نرم افزار Postman استفاده نمایید. که در ادامه مثال هایی از هر نوع درخواست را مشاهده می کنید:

ارسال درخواست لاگین توسط نرم افزار Third-Party

درخواست ترددها (رکوردها) بصورت تک به تک

درخواست ترددها (رکوردها) بصورت گروهی

تاییدیه دریافت رکوردها بصورت تک به تک

تاییدیه دریافت رکوردها بصورت گروهی

دریافت اطلاعات با روش Webhook (روش پیشنهادی نوین پرداز)

 در این روش، برعکس روش Rest API که ابتدا نرم افزار درخواست کننده (Third-Party Application)، درخواست خود را ارسال می نماید، این بار این نرم افزار حضور و غیاب نوین پرداز است که پس از ثبت رکورد جدید (تردد جدید) در بانک اطلاعاتی، اطلاعات را به Endpoint مقصد ارسال خواهد کرد.
جهت تنظیمات Webhook طبق راهنمای زیر عمل نمایید:

سوالات متداول (FAQ)

1. تفاوت Rest API و Webhook در نرم‌افزار حضور و غیاب نوین پرداز چیست؟

در روش Rest API، نرم‌افزار مقصد هر زمان که نیاز داشته باشد، اطلاعات را از نرم‌افزار حضور و غیاب درخواست می‌کند (Pull). اما در روش Webhook، به محض ثبت تردد جدید، نرم‌افزار حضور و غیاب اطلاعات را به صورت خودکار برای نرم‌افزار مقصد ارسال می‌کند (Push). به همین دلیل Webhook برای دریافت آنی اطلاعات گزینه مناسب‌تری است.

2. برای استفاده از Rest API نرم‌افزار حضور و غیاب نوین پرداز به چه مواردی نیاز است؟

برای استفاده از Rest API کافی است:

  • قابلیت Rest API در تنظیمات نرم‌افزار فعال شود.
  • یک کاربر Rest API در نرم افزار و غیاب نوین پرداز تعریف شود.
  • آدرس و پورتRest API  مشخص گردد.
  • ارسال درخواست ها به Endpoint های تعیین شده نرم افزار حضوروغیاب نوین پرداز طبق چهارچوب و قوانین تعیین شده در مستندات.

3. آیا امکان اتصال نرم‌افزارهای نوشته شده با PHP، C#، Java یا Python به نرم‌افزار حضور و غیاب نوین پرداز وجود دارد؟

بله. از آنجا که ارتباط از طریق HTTP و داده‌های JSON انجام می‌شود، هر زبان برنامه‌نویسی یا فریم‌ورکی که از این استانداردها پشتیبانی کند، می‌تواند با نرم‌افزار حضور و غیاب نوین پرداز ارتباط برقرار کند.

4. اطلاعات ترددها با چه فرمتی از طریق API ارسال می‌شوند؟

تمام اطلاعات از طریق Rest API و Webhook با فرمت استاندارد JSON ارسال می‌شوند و شامل اطلاعاتی مانند زمان تردد، شماره پرسنلی، اطلاعات دستگاه، مشخصات فرد و شناسه (GUID) هر رکورد هستند.

5. چرا باید پس از دریافت اطلاعات، عملیات ACK انجام شود؟

ارسال تأییدیه (ACK) به نرم‌افزار حضور و غیاب اعلام می‌کند که اطلاعات با موفقیت دریافت و ذخیره شده‌اند. در غیر این صورت، رکوردها دوباره ارسال خواهند شد تا از از دست رفتن اطلاعات جلوگیری شود.

6. آیا می‌توان فقط ترددهای یک شخص یا یک دستگاه خاص را دریافت کرد؟

بله. در متد Search می‌توان با استفاده از پارامترهایی مانند PersonNo، DeviceNo، Count، Skip و Modified فقط اطلاعات مورد نیاز را دریافت کرد و از انتقال داده‌های اضافی جلوگیری نمود.

7. اگر JWT Token منقضی شود چه اتفاقی می‌افتد؟

در صورت انقضای توکن، سرورRest API کد وضعیت 401 Unauthorized را برمی‌گرداند. در این شرایط نرم‌افزار باید مجدداً درخواست Login ارسال کرده و توکن جدید دریافت کند.

8. برای تست Rest API نرم‌افزار حضور و غیاب نوین پرداز از چه ابزاری استفاده کنیم؟

یکی از بهترین ابزارها برای تستRest API نرم‌افزار حضور و غیاب نوین پرداز، نرم‌افزار Postman است که امکان ارسال درخواست‌های Login، دریافت ترددها و ارسال ACK را بدون نیاز به برنامه‌نویسی فراهم می‌کند.

9. آیا استفاده از Webhook بهتر از Rest API است؟

بله. در بیشتر پروژه‌ها استفاده از Webhook  توصیه می شود چرا که در این روش اطلاعات بلافاصله پس از ثبت تردد ارسال می شوند و نیازی به ارسال درخواست‌های مکرر از سمت نرم‌افزار مقصد نمی باشد. به همین دلیل بار شبکه و سرور کاهش یافته و اطلاعات سریع‌تر منتقل می‌شوند.

10. آیا برای استفاده از API نرم‌افزار حضور و غیاب نوین پرداز باید مستقیماً به دستگاه حضور و غیاب متصل شویم؟

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