محاسبه تاریخ تسویه T+1 با API تقویم مالی

تاریخ تسویه T+n یعنی n روز کاری بعد از روز معامله یا ثبت دستور. شمردن روزهای تقویمی کافی نیست: جمعه‌ها، تعطیلات رسمی خورشیدی و تعطیلات قمری باید کنار گذاشته شوند. این راهنما نشان می‌دهد چطور همین محاسبه را با API تقویم مالی انجام دهید.

یک مثال واقعی: معامله آخر اسفند

فرض کنید معامله‌ای در پنجشنبه ۲۸ اسفند ۱۴۰۴ ثبت شده و تسویه آن T+1 است. روز بعد، ۲۹ اسفند، هم جمعه است و هم تعطیل رسمی (روز ملی شدن صنعت نفت)؛ بعد از آن چهار روز تعطیلی نوروز می‌آید. تاریخ تسویه درست، چهارشنبه ۵ فروردین ۱۴۰۵ است؛ شش روز تقویمی بعد از معامله.

فراخوان API

curl 'https://iranopenfinance.com/api/calendar/settlement?date=1404/12/28&t=1'

تاریخ را می‌توانید شمسی (با ارقام فارسی یا لاتین) یا میلادی بفرستید. بخش اصلی پاسخ:

{
  "ok": true,
  "data": {
    "t": 1,
    "settlement": {
      "iso": "2026-03-25",
      "jalali": "1405/01/05",
      "jalali_long": "چهارشنبه ۵ فروردین ۱۴۰۵",
      "business_day": true,
      "moved_days": 6,
      "uncertain": false
    }
  }
}

قاعده آخر هفته را درست انتخاب کنید

برای بانک‌ها و شبکه پرداخت، پنجشنبه روز کاری است؛ برای بیشتر دستگاه‌های دولتی و بازار سرمایه نه. پارامتر profile همین را تعیین می‌کند:

به «پیش‌بینی» اعتماد کورکورانه نکنید

تعطیلات قمری بر پایه رؤیت هلال اعلام می‌شوند. تا اعلام رسمی، موتور تقویم تاریخ آن‌ها را محاسبه می‌کند و هر نتیجه‌ای را که به یک تعطیل قمری پیش‌بینی‌شده وابسته باشد با uncertain: true علامت می‌زند. مثلاً T+1 از چهارشنبه ۳ تیر ۱۴۰۵ به شنبه ۶ تیر می‌رسد، چون تاسوعا (پیش‌بینی) و عاشورا (جمعه) در میان‌اند؛ این پاسخ uncertain: true دارد.

در رابط کاربری، هر تاریخ نامطمئن را با برچسب «پیش‌بینی» نشان دهید و برای تسویه‌های حساس یک روز حاشیه در نظر بگیرید.

همین محاسبه در کانال‌های دیگر

• کیت توسعه: settlement(parseDate("1404/12/28"), 1)
• خط فرمان: iof-cal settle 1404/12/28 --t 1
• عامل‌های هوشمند: ابزار calendar_settlement روی سرور MCP

همه این کانال‌ها از یک موتور استفاده می‌کنند؛ پس پاسخ هیچ‌کدام با دیگری فرق نمی‌کند.