---
title: "تقویم.dev™ | زیرساخت زمان، تقویم و زمان‌بندی برای توسعه‌دهندگان"
description: "API و زیرساخت زمان برای تقویم شمسی، روزهای کاری، زمان‌بندی، دسترس‌پذیری، رزرو، سررسید، عامل‌های هوشمند و ویجت‌های آماده. با API، SDK، CLI و MCP."
url: https://taghvim.dev/
lang: fa
source: "تقویم.dev"
---

> API و زیرساخت زمان برای تقویم شمسی، روزهای کاری، زمان‌بندی، دسترس‌پذیری، رزرو، سررسید، عامل‌های هوشمند و ویجت‌های آماده. با API، SDK، CLI و MCP.

زیرساخت زمان · بومی ایران · برای توسعه‌دهندگان

# زمان و تاریخ را به ما بسپارید.

تقویم شمسی، میلادی و قمری، تعطیلات و روزهای کاری، زمان‌بندی و رزرو، تکرار، سررسید، یادآور و اجرای زمان‌دار؛ همه در یک موتور.

از راه API، SDK، CLI، MCP، وب‌هوک یا ویجت‌های آماده به آن وصل شوید تا هیچ تیمی منطق تاریخ و زمان را از صفر ننویسد.

رایگان شروع کنید مستندات را ببینید

بدون کارت بانکی · دسترسی زودهنگام · کلید محیط تست به‌محض راه‌اندازی

API SDK CLI MCP ویجت‌ها وب‌هوک‌ها

آزمایشگاه تاریخ را باز کنید

_کنسول زیرساخت زمان_

خواندن تاریخ نوبت‌های آزاد سررسید برنامه‌ی عامل

**خواندن تاریخ** موتور تقویم

عبارت فارسی حساب کن

**۱۴۰۵/۰۷/۱۹، ساعت ۱۰:۰۰** به وقت تهران ۳ روز کاری بعد

روی زبانه‌ها بزنید یا عبارت را خودتان بنویسید.

- شمسی، میلادی، قمری
- روزهای کاری
- تعطیلات
- دسترس‌پذیری
- رزرو
- سررسیدها
- برنامه‌های تکرارشونده
- زمان‌بندی عامل‌ها

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

چرا به ما بسپارید؟

## زمان ساده به نظر می‌رسد، تا وقتی وارد محصول واقعی شود.

هر تیمی که برای کاربران ایرانی نرم‌افزار می‌سازد، زود با این پرسش‌های تکراری روبه‌رو می‌شود:

- تاریخ شمسی و میلادی را به هم تبدیل کن.
- فهرست تعطیلات را به‌روز نگه دار.
- روز کاری را درست بشمار.
- منطقه‌ی زمانی را فراموش نکن.
- رویدادهای تکرارشونده را پیاده کن.
- نگذار دو نفر یک نوبت را با هم بگیرند.
- اگر سررسید به تعطیلی خورد، چه باید کرد؟
- یادآور نباید دو بار فرستاده شود.
- وب‌هوکی که نرسید، دوباره فرستاده شود.
- عامل هوشمند فقط در حد اختیارش کار کند.

چندی بعد، آن «تابع کوچک تاریخ» به زیرسیستمی پیچیده تبدیل شده که مدام نگهداری می‌خواهد.

زیرساخت زمانِ دست‌ساز قبل بعد

قبل

محصول شما

- کتابخانه‌ی تاریخ شمسی
- فایل دستی تعطیلات
- کارهای زمان‌بندی‌شده‌ی سرور
- جدول‌های رزرو
- سرویس یادآور
- همگام‌سازی تقویم
- منطق سررسید سفارشی
- زمان‌بندی عامل‌ها

بعد

محصول شما

**تقویم.dev™**

- تقویم
- زمان‌بندی
- سررسید
- رزرو
- عامل‌ها

زیرساخت زمان

## نه فقط «API تقویم»؛ زیرساخت زمان.

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

**تقویم.dev™** زیرساخت زمان

### تقویم

- شمسی، میلادی و قمری
- تعطیلات
- روزهای کاری
- تبدیل تاریخ
- قالب‌بندی

زنده امروز **۹ مهر ۱۴۰۵**

### زمان‌بندی

- نوبت‌های آزاد
- منابع
- رزرو موقت
- رزرو
- تکرار

زنده نخستین روز کاری پیش رو **شنبه ۱۱ مهر ۱۴۰۵**

### اجرا

- برنامه‌های زمانی
- سررسیدها
- یادآورها
- اجرای عامل‌ها
- گردش‌کارها

زنده اجرای بعدی «هر روز کاری، ساعت ۱۸» **۱۴۰۵/۰۷/۰۹، ساعت ۱۸:۰۰**

روی هر قابلیت بزنید تا نمونه‌ی زنده‌اش را ببینید.

یک مدل زمانی و چند رابط؛ بی‌آنکه منطق زمان در هر محصول از نو نوشته شود.

رابط‌ها

## یک موتور، با هر رابطی که لازم دارید.

### API

REST API نسخه‌دار برای همه‌ی اجزای پایه‌ی زمان و زمان‌بندی.

http

```
POST /v1/dates/resolve
POST /v1/business-days/add
POST /v1/deadlines
POST /v1/schedules/preview
```

اجرا کنید پاسخ موتور

مرجع تعاملی API

### SDK

کتابخانه‌های نوع‌دار برای TypeScript و Python؛ زبان‌های دیگر هم در راه‌اند.

ts

```
const slots = await taghvim.availability.find({
  resourceId: "doctor_1",
  duration: "PT30M"
})
```

اجرا کنید پاسخ موتور

ویرایشگر نمونه

### CLI

توسعه، آزمون و کارهای روزمره، همه از خط فرمان.

bash

```
taghvim date resolve "سه روز کاری بعد"
taghvim availability find
taghvim sandbox clock advance 3d
```

اجرا کنید پاسخ موتور

خط فرمان نمونه

### MCP

ابزارهای زمان و زمان‌بندی برای عامل‌های هوشمند، با اختیار و دامنه‌ی دسترسی مشخص.

text

```
taghvim_find_availability
taghvim_create_reservation
taghvim_create_deadline
taghvim_create_schedule
```

اجرا کنید پاسخ موتور

عامل را امتحان کنید

### ویجت‌ها

اجزای آماده‌ی راست‌به‌چپ با تقویم شمسی، برای جاسازی مستقیم در محصول.

- انتخابگر تاریخ
- ویجت رزرو
- ویجت سررسید

ویجت‌ها را ببینید

### وب‌هوک‌ها

رویدادهای زمانی را به سامانه‌ی خودتان برسانید؛ امضاشده، با تلاش دوباره و قابل بازپخش.

json

```
{
  "id": "evtlog_…",
  "type": "taghvim.event.reservation.confirmed.v1"
}
```

اجرا کنید پاسخ موتور

رویدادها و وب‌هوک‌ها

ویجت‌ها

## رابط کاربری آماده، و کنترل همچنان در دست شما.

اگر نمی‌خواهید رابط کاربری را از صفر بسازید، ویجت‌های ما را در محصولتان جاسازی کنید. اگر کنترل کامل می‌خواهید، همین قابلیت‌ها از راه API و SDK هم در دسترس‌اند.

**انتخابگر تاریخ** زنده، با موتور تقویم

ویجت الف: انتخاب تاریخ شمسی؛ روز انتخاب‌شده اناری است و تعطیلی با نقطه نشان داده می‌شود.

**رزرو نوبت** نمونه

روزهای کاری پیش رو موتور تقویم

شنبه **۱۱** مهر یکشنبه **۱۲** مهر دوشنبه **۱۳** مهر سه‌شنبه **۱۴** مهر چهارشنبه **۱۵** مهر

تاریخ **۱۴۰۵/۰۷/۱۱**

۰۹:۰۰ ۰۹:۳۰ ۱۰:۰۰ ۱۱:۳۰ ۱۴:۰۰ ۱۵:۳۰

رزرو ساعت ۱۰:۰۰

1. آزاد
2. رزرو موقت ۱۰:۰۰
3. تأیید
4. رسید

ویجت ب: روزها را موتور تقویم می‌دهد و تعطیلی‌ها کنار می‌روند؛ ساعت‌های آزاد نمونه‌اند.

**محاسبه‌ی سررسید** زنده، با موتور تقویم

تاریخ مبنا ۱۵ مهر ۱۴۰۵ فاصله اگر تعطیل بود

نتیجه **۲۰ آبان ۱۴۰۵**

ویجت ج: با موتور تقویم؛ تاریخ و فاصله را تغییر دهید.

**ساعت‌های کاری هفته** نمونه

- **شنبه** _۰۹:۰۰_ _۱۷:۰۰_
- **یکشنبه** _۰۹:۰۰_ _۱۷:۰۰_
- **دوشنبه** تعطیل
- **سه‌شنبه** _۱۰:۰۰_ _۱۴:۰۰_
- **چهارشنبه** _۰۹:۰۰_ _۱۷:۰۰_

ویجت د: ساعت‌های در دسترس هر روز (نمونه).

**برنامه‌ی زمانی عامل** زنده، با موتور تقویم

**تکرار**

هر روز کاری

**ساعت**

۱۸:۰۰

**منطقه‌ی زمانی**

تهران

**مقصد**

عامل تطبیق حساب‌ها

**سقف مصرف**

۱٬۰۰۰ عملیات در هر اجرا

فعال

اجرای بعدی **۱۴۰۵/۰۷/۰۹، ساعت ۱۸:۰۰**

ویجت هـ: اجرای بعدی را موتور روز کاری حساب می‌کند.

**نشان‌های کوچک** زنده، با موتور تقویم

امروز **پنجشنبه ۹ مهر ۱۴۰۵** روز کاری

شمسی، میلادی و قمری (ام‌القری) **۹ مهر ۱۴۰۵** **۱ اکتبر ۲۰۲۶** **۲۰ ربیع‌الثانی ۱۴۴۸**

تعطیلی رسمی بعدی **۴۴ روز دیگر: شهادت حضرت فاطمه زهرا** شنبه ۲۳ آبان ۱۴۰۵ (پیش‌بینی)

کد جاسازی رونوشت

```
<taghvim-day-badge date="today" profile="bank"></taghvim-day-badge>
```

ویجت و: سه نشان زنده برای کنار فرم‌ها و فاکتورها، با داده‌ی موتور تقویم.

موتور تقویم

## هسته‌ای مطمئن برای تاریخ‌های ایران.

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

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

**مبدل تاریخ** موتور تقویم

شمسی

روز ماه سال

۱۵ مهر ۱۴۰۵

میلادی

روز ماه سال

۷ اکتبر ۲۰۲۶

قمری (ام‌القری)

روز ماه سال

۲۶ ربیع‌الثانی ۱۴۴۸

روز قبل امروز روز بعد

**روز هفته**

چهارشنبه

**وضعیت**

روز کاری

**تاریخ میلادی (ISO)**

۲۰۲۶-۱۰-۰۷

**منطقه‌ی زمانی**

تهران

**بسته‌ی تقویم**

iran-2026.10.01

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

**آزمایشگاه تاریخ** موتور تقویم

عبارت یا تاریخ

حساب کن

سه روز کاری بعد از ۱۵ مهر ساعت ۱۰ ۳۰ روز کاری بعد از ۱۴۰۵/۰۷/۱۵ فردا ۲۰۲۶-۱۰-۱۰ ۹ مهر ۱۴۰۵ ۱۴۴۸/۰۴/۲۷ هـ

نتیجه

۱۴۰۵/۰۷/۱۹، ساعت ۱۰:۰۰

یکشنبه ۱۹ مهر ۱۴۰۵

`2026-10-11T10:00:00+03:30[Asia/Tehran]`

تبدیل تاریخ میان شمسی، میلادی و قمری (با ارقام فارسی یا لاتین) کار خود موتور تقویم است. موتور هنوز زبان طبیعی فارسی را کامل نمی‌فهمد؛ این آزمایشگاه فقط این الگوها را روی آن می‌سازد: «N روز (کاری) بعد/قبل از …»، «امروز/فردا/پس‌فردا/دیروز» و «ساعت HH:MM». هر عبارت دیگری را صادقانه «نامفهوم» اعلام می‌کند.

روزهای کاری

## «۳۰ روز بعد» و «۳۰ روز کاری بعد» یک چیز نیستند.

وقتی پای قرارداد، پرداخت، SLA، تسویه، حقوق یا مقررات در میان است، شمردن روز کاری دیگر یک تابع کمکی ساده نیست.

از روز

۳۰ روز بعد **شنبه ۱۶ آبان ۱۴۰۵**

۳۰ روز کاری بعد **چهارشنبه ۲۰ آبان ۱۴۰۵**

روز کاری جمعه تعطیل رسمی سررسید

نمونه‌ی درخواست API رونوشت

```
POST /v1/business-days/add
{
  "date": "1405-07-15",
  "days": 30
}
```

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

### تعطیلات و مناسبت‌ها

موتور تقویم

ماه سال

سپتامبر تا اکتبر ۲۰۲۶ ۲۶ روز کاری، بدون تعطیل رسمی

**مهر ۱۴۰۵**

| ش | ی | د | س | چ | پ | ج |
| --- | --- | --- | --- | --- | --- | --- |
| ۱ | ۲ | ۳ |  |  |  |  |
| ۴ | ۵ | ۶ | ۷ | ۸ | ۹ | ۱۰ |
| ۱۱ | ۱۲ | ۱۳ | ۱۴ | ۱۵ | ۱۶ | ۱۷ |
| ۱۸ | ۱۹ | ۲۰ | ۲۱ | ۲۲ | ۲۳ | ۲۴ |
| ۲۵ | ۲۶ | ۲۷ | ۲۸ | ۲۹ | ۳۰ |  |

1. در این ماه تعطیلی رسمی یا مناسبتی ثبت نشده است.

تعطیل رسمی تعطیلی قمری (پیش‌بینی) جمعه امروز

[دریافت تعطیلات ۱۴۰۵ (فایل ICS)](https://taghvim.dev/calendar/holidays-1405.ics)

موتور زمان‌بندی

## زمان‌بندی برای همه‌چیز، نه فقط جلسه‌ها.

برای ما «منبع» هر چیزی است که بشود وقتش را تخصیص داد: یک نفر، اتاق، خودرو، دستگاه، سرویس یا عامل هوشمند.

1. منبع
2. قاعده‌های دسترس‌پذیری
3. نوبت‌های پیشنهادی
4. محدودیت‌ها
5. رزرو موقت
6. رزرو
7. رویداد

- تقویم هر منبع
- ظرفیت
- فاصله میان نوبت‌ها
- بازه‌های بسته
- هم‌پوشانی چند منبع
- رزرو موقت
- جلوگیری از تداخل
- دسترس‌پذیری تکرارشونده
- جابه‌جایی نوبت
- قاعده‌های لغو

نوبت **۱۰:۰۰**

**کاربر الف** _رزرو موقت را گرفت_

**کاربر ب** _این نوبت گرفته شده است_ گزینه‌های بعدی: _۱۰:۳۰_ _۱۱:۳۰_

درخواست‌های هم‌زمان نباید به دو رزرو برای یک نوبت برسند.

دوباره اجرا کن

**سازنده‌ی قاعده‌ی تکرار** موتور تقویم

قاعده ساعت

آخرین روز کاری هر ماه، ساعت ۰۹:۰۰

شش نوبت بعدی

1. **پنجشنبه ۳۰ مهر ۱۴۰۵**
2. **شنبه ۳۰ آبان ۱۴۰۵**
3. **دوشنبه ۳۰ آذر ۱۴۰۵**
4. **چهارشنبه ۳۰ دی ۱۴۰۵**
5. **پنجشنبه ۲۹ بهمن ۱۴۰۵** ۱ روز زودتر، به‌خاطر تعطیلی
6. **پنجشنبه ۲۷ اسفند ۱۴۰۵** ۲ روز زودتر، به‌خاطر تعطیلی

درخواست API (JSON) رونوشت

```
POST /v1/schedules/preview
{
  "rule": "last-business",
  "from": "1405-07-09",
  "count": 6
}
```

موتور سررسید

## سررسید فقط یک ستون تاریخ در جدول نیست.

سررسید را می‌شود از یک تاریخ ثابت، یک رویداد، شمار روزهای کاری، سیاست سازمان یا حتی یک سند ورودی حساب کرد.

1. **رویداد مبنا** ۱۴۰۵/۰۷/۱۵
2. **فاصله** ۳۰ روز کاری
3. **بسته‌ی تقویم ایران** iran-2026.10.01
4. **اگر تعطیل بود** روز کاری بعد
5. **سررسید نهایی** ۱۴۰۵/۰۸/۲۰

### کاربردها

- سررسید صورت‌حساب
- مهلت‌های SLA
- تمدید قرارداد
- مهلت‌های قانونی
- مهلت بستن حقوق
- بازه‌های تسویه
- تاریخ بازبینی انطباق
- مرحله‌های درمان و کارآزمایی

**مهلت SLA به ساعت کاری** موتور تقویم

شروع ساعت

مهلت (ساعت کاری)

آغاز کار پایان کار

پنجشنبه‌ها تا ساعت ۱۳

پایان مهلت **دوشنبه ۲۰ مهر ۱۴۰۵، ساعت ۱۰:۰۰**

ساعت‌ها نمونه‌اند و تغییرپذیر؛ روزهای کاری و تعطیلات از موتور تقویم (پروفایل بانکی، جمعه تعطیل).

**پیش‌نمایش یادآورها** موتور تقویم

سررسید ساعت ارسال

یادآورها

۷ روز پیش از آن ۳ روز کاری پیش از آن ۱ روز کاری پیش از آن روز سررسید

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

گردش‌کارها

## چند قدم، یک تقویم؛ تاریخ همه‌ی قدم‌ها با هم جابه‌جا می‌شود.

هر قدم نسبت به قدمی دیگر تعریف می‌شود: چند روز کاری پس از تأیید، یا ده روز تقویمی پس از آن. تاریخ شروع، فاصله‌ها یا قاعده‌ی تعطیلی را تغییر دهید و «اجرا» را بزنید تا موتور تقویم همه‌ی قدم‌ها را دوباره بچیند.

**سازنده‌ی گردش‌کار: از تأیید قرارداد تا تسویه** موتور تقویم

تاریخ شروع قاعده‌ی تعطیلی

اجرا کن نمونه‌ی اولیه

1. ۱

   **تأیید قرارداد** روز شروع؛ اگر تعطیل باشد، روز کاری بعد.

   **دوشنبه ۱۲ بهمن ۱۴۰۵**
2. ۲

   **سررسید پرداخت** ده روز تقویمی پس از تأیید؛ اگر به تعطیلی بخورد، طبق قاعده جابه‌جا می‌شود.

   فاصله نوع روز نسبت به: تأیید قرارداد

   **شنبه ۲۴ بهمن ۱۴۰۵** ۲۲ بهمن ۱۴۰۵ تعطیل است (پیروزی انقلاب اسلامی)؛ به شنبه ۲۴ بهمن ۱۴۰۵ منتقل شد
3. ۳

   **یادآور** دو روز کاری پیش از سررسید.

   فاصله نوع روز نسبت به: سررسید پرداخت

   **سه‌شنبه ۲۰ بهمن ۱۴۰۵**
4. ۴

   **تسویه** یک روز کاری پس از سررسید.

   فاصله نوع روز نسبت به: سررسید پرداخت

   **یکشنبه ۲۵ بهمن ۱۴۰۵**

همان درخواست به API رونوشت

```
POST /v1/workflow-runs/preview
{
  "start": "1405-11-12",
  "roll": "following",
  "steps": [
    {
      "id": "approve",
      "offset": 0,
      "unit": "business"
    },
    {
      "id": "due",
      "offset": 10,
      "unit": "calendar",
      "relative_to": "approve"
    },
    {
      "id": "remind",
      "offset": -2,
      "unit": "business",
      "relative_to": "due"
    },
    {
      "id": "settle",
      "offset": 1,
      "unit": "business",
      "relative_to": "due"
    }
  ]
}
```

زمان‌بندی عامل‌ها و MCP

## عامل‌های هوشمند هم به زمان‌بندی درست نیاز دارند.

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

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

**عامل**

پیگیری وصول مطالبات

**برنامه**

هر روز کاری، ساعت ۰۹:۰۰

**دامنه**

فضای کاری وصول مطالبات

**ابزارها**

۴

**سقف مصرف**

۵۰۰ عملیات در هر اجرا

**آخرین اجرا**

موفق

**اجرای بعدی**

**۱۴۰۵/۰۷/۱۱، ساعت ۰۹:۰۰**

1. زمان اجرا رسید
2. بررسی سیاست
3. کنترل سقف مصرف
4. محیط اجرای عامل
5. ابزارهای MCP
6. رسید اجرا

داده‌ی نمایشی؛ اجرای بعدی را موتور روز کاری حساب می‌کند.

**گفت‌وگو با عامل (نمونه)** نمونه

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

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

رویدادها و وب‌هوک‌ها

## وقتی زمانِ چیزی تغییر می‌کند، سامانه‌ی شما هم باید باخبر شود.

ما رویدادمحوریم: هر اتفاق مهم یک رویداد می‌سازد و می‌تواند به یک وب‌هوک برسد.

1. `taghvim.event.reservation.confirmed.v1`
2. `taghvim.event.schedule.triggered.v1`
3. `taghvim.event.deadline.overdue.v1`
4. `taghvim.event.notification.delivered.v1`
5. `taghvim.event.connector.degraded.v1`

**تقویم.dev™**

- ERP
- CRM
- پرداخت
- عامل هوشمند
- انبار داده
- اپلیکیشن داخلی

روی هر رویداد بزنید تا ببینید به کجا می‌رسد.

- تحویل امضاشده
- تلاش دوباره
- سابقه‌ی تحویل
- بازپخش
- ایمن در برابر تکرار
- محتوای نسخه‌دار

**سابقه‌ی تحویل یک وب‌هوک** نمونه

رویداد گیرنده دو بار خطا بدهد ارسال بازپخش همان رویداد

نمونه؛ زمان‌ها به وقت تهران، از همین لحظه

خط پردازش رویدادها

## هر رویداد اول از قاعده‌های تقویم می‌گذرد، بعد به مقصد می‌رسد.

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

**خط پردازش** موتور تقویم

رویداد زمان رسیدن گیرنده‌ی وب‌هوک یک بار خطا بدهد

فرستادن رویداد پخش خودکار

گزارش اجرا

1. هنوز رویدادی فرستاده نشده است.

رویداد در دقیقهتأخیر (میلی‌ثانیه)

نمونه: تصمیم‌های زمانی را موتور تقویم می‌گیرد؛ بار و تأخیر نمایشی‌اند.

مرکز اعلان‌ها

## اعلانی که تقویم را می‌شناسد.

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

**یک اعلان بسازید** موتور تقویم

تعطیلی پیش رو سررسید قرارداد وب‌هوک تحویل شد تحویل ناموفق مهلت SLA نزدیک است یادآور جابه‌جا شد

اعلان‌ها واقعی‌اند؛ متن و شماره‌ها نمونه‌اند.

پیش‌نمایش روی گوشی

**تاریخچه‌ی اعلان‌ها** پاک کردن تاریخچه

1. هنوز اعلانی نیامده است. یکی از دکمه‌ها را بزنید.

جست‌وجو، شواهد و رسیدها

## بدانید چه شد، چرا شد، و بر پایه‌ی چه.

برای هر عملیات مهم رسید، سابقه‌ی رویدادها و شواهد نگه می‌داریم؛ به‌ویژه برای گردش‌کارهای حساس یا مشمول مقررات.

**جست‌وجو** نمونه

سررسیدهای فعال قراردادها در این هفته

فیلترها

**فضای کاری**

حقوقی

**نوع**

سررسید

**وضعیت**

فعال

**موعد**

این هفته

سابقه‌ی رویدادهای یک رزرو

1. ۰۹:۴۱:۱۲ رزرو موقت ساعت ۱۰:۰۰ گرفته شد `taghvim.event.reservation.held.v1`
2. ۰۹:۴۱:۴۰ رزرو تأیید شد `taghvim.event.reservation.confirmed.v1`
3. ۰۹:۴۱:۴۰ رسید صادر شد `taghvim.event.receipt.issued.v1`
4. ۰۹:۴۱:۴۱ یادآور برای روز کاری قبل تنظیم شد `taghvim.event.reminder.scheduled.v1`
5. ۰۹:۴۱:۴۲ وب‌هوک به سامانه‌ی کلینیک تحویل شد `taghvim.event.webhook.delivered.v1`

پخش سابقه

**رسید رزرو** نمونه

**وضعیت**

تأییدشده

**انجام‌دهنده**

`usr_123`

**سیاست**

`booking-v3`

**منبع**

`doctor_1`

**زمان**

۱۰:۰۰ تا ۱۰:۳۰

**رویداد**

`evtlog_7f3a…`

**رسید**

`rcpt_92c1…`

بررسی امضای رسید

یکپارچه‌سازی

## به سامانه‌های موجود وصل شوید، بی‌آنکه به آن‌ها گره بخورید.

ما یک مدل مرجع نگه می‌داریم و هر یکپارچه‌سازی را از منطق اصلی جدا می‌کنیم.

**تقویم.dev™**

- تقویم گوگل
- Outlook
- ICS
- CalDAV

مدل مرجع

**ICS** وضعیت: فعال

خروجی یک‌طرفه؛ فایل تعطیلات ۱۴۰۵ همین حالا با موتور تقویم ساخته شده و دریافت‌شدنی است.

روی هر اتصال بزنید تا جزئیاتش را ببینید.

### نخستین یکپارچه‌سازی‌ها

- ICS
- CalDAV
- تقویم گوگل
- تقویم مایکروسافت (Outlook)
- وب‌هوک‌ها
- اعلان ایمیلی
- درگاه پرداخت برای صورت‌حساب‌های ما

[**فایل ICS واقعی: تعطیلات رسمی ۱۴۰۵** همین حالا با موتور تقویم ساخته شده؛ در هر برنامه‌ی تقویمی وارد کنید.](https://taghvim.dev/calendar/holidays-1405.ics)

اتصال‌دهنده‌ها، بسته‌های تقویم، گردش‌کارها و ویجت‌های بیشتر از بازارچه نصب می‌شوند؛ اما برای شروع به بازارچه نیازی نیست.

یک‌بار بسازید

## یک‌بار تعریف کنید، همه‌جا به کار ببرید.

مدل مرجع زمان

- REST API
- SDK
- CLI
- MCP
- ویجت‌ها
- وب‌هوک‌ها
- اپلیکیشن وب

REST API رونوشت

```
POST /v1/business-days/add
{ "date": "1405-07-09", "days": 3 }
```

همه یک پاسخ می‌گیرند: **دوشنبه ۱۳ مهر ۱۴۰۵**

روی هر رابط بزنید تا همان کار را در آن رابط ببینید.

API، MCP و ویجت سه محصول جدا نیستند؛ سه رابط روی یک موتورند. برای همین رفتار و معنای هر عملیات همه‌جا یکسان است.

شروع برای توسعه‌دهندگان

## سه قدم تا نخستین پاسخ.

1. ### ۱ پروژه بسازید

   text رونوشت

   ```
   Project: my-app
   Environment: sandbox
   Locale: fa-IR
   Timezone: Asia/Tehran
   ```
2. ### ۲ کلید را تنظیم کنید

   bash رونوشت

   ```
   export TAGHVIM_API_KEY=tgv_test_...
   ```
3. ### ۳ نخستین درخواست

   bash رونوشت

   ```
   curl https://api.taghvim.dev/v1/dates/resolve \
     -H "Authorization: Bearer $TAGHVIM_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "text":"سه روز کاری بعد",
       "locale":"fa-IR"
     }'
   ```

پاسخ رونوشت

```
{
  "status": "resolved",
  "jalali": "1405-07-13",
  "business_day": true
}
```

پاسخ نمونه؛ تاریخ آن را موتور تقویم از امروز حساب می‌کند.

**خط فرمان** موتور تقویم

دوباره پخش کن

خط فرمان نمونه؛ خروجی هر فرمان را همین موتور تقویم می‌سازد.

**ویرایشگر SDK** `due-date.ts` موتور تقویم

1. `import { Taghvim } from "@taghvim/sdk";`
3. `const taghvim = new Taghvim({ apiKey: process.env.TAGHVIM_API_KEY });`
5. `// 30 business days after today, Iranian bank calendar`
6. `const due = await taghvim.businessDays.add({`
7. `date: "1405-07-09",`
8. `days: 30,`
9. `});`
10. `console.log(due.result.jalali);`

اجرا خروجی

کد نمونه با SDK؛ «اجرا» همان عملیات را روی موتور تقویم در مرورگر انجام می‌دهد.

درخواست کلید محیط تست

API عمومی در مرحله‌ی دسترسی زودهنگام است؛ کلید محیط تست برای فهرست انتظار صادر می‌شود.

مرجع تعاملی API

## همه‌ی عملیات‌ها، با امکان امتحان روی همین صفحه.

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

جست‌وجو در عملیات‌ها ۴۸ عملیات [دریافت مشخصات (OpenAPI ۳٫۱)](https://taghvim.dev/openapi.json)

کلید API شما فقط برای فراخوانی واقعی لازم است. کلید تنها به api.taghvim.dev فرستاده می‌شود و هیچ‌جا ذخیره نمی‌شود.

نشانی سرویس: `https://api.taghvim.dev` · احراز هویت: `Authorization: Bearer tgv_test_…`

### سامانه و قرارداد سلامت سرویس، آمادگی، نسخه‌ها و خود قرارداد API.

GET `/v1/health` سلامت سرویس بدون کلید

#### پاسخ‌ها

- **۲۰۰** `Health`
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

فراخوانی واقعی روی api.taghvim.dev بازنشانی

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/health"
```

GET `/v1/readiness` آمادگی سرویس بدون کلید

#### پاسخ‌ها

- **۲۰۰** `Readiness`
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.
- **۵۰۳** `Readiness`

#### امتحان کنید

فراخوانی واقعی روی api.taghvim.dev بازنشانی

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/readiness"
```

GET `/v1/versions` نسخه‌ها بدون کلید

#### پاسخ‌ها

- **۲۰۰** `Versions`
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

فراخوانی واقعی روی api.taghvim.dev بازنشانی

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/versions"
```

GET `/openapi.json` همین سند OpenAPI بدون کلید

#### پاسخ‌ها

- **۲۰۰**
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

فراخوانی واقعی روی api.taghvim.dev بازنشانی

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/openapi.json"
```

### تقویم و تبدیل تاریخ تقویم‌ها و تبدیل تاریخ.

GET `/v1/calendars/systems` تقویم‌های پشتیبانی‌شده اجرا در مرورگر

#### پاسخ‌ها

- **۲۰۰** `CalendarSystems`
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "systems": [
    {
      "id": "jalali",
      "name": "Solar Hijri (Jalali)",
      "name_fa": "هجری شمسی",
      "year_range": [
        1300,
        1499
      ]
    },
    {
      "id": "gregorian",
      "name": "Gregorian",
      "name_fa": "میلادی",
      "year_range": [
        1921,
        2121
      ]
    },
    {
      "id": "hijri",
      "name": "Hijri (Umm al-Qura)",
      "name_fa": "هجری قمری (ام‌القری)",
      "year_range": [
        1343,
        1500
      ],
      "note": "Lunar holidays are predicted until officially announced."
    }
  ],
  "business_day_profile": {
    "id": "bank",
    "weekend": [
      5
    ],
    "description_fa": "تقویم بانکی ایران: جمعه و تعطیلات رسمی، روز غیرکاری هستند."
  },
  "timezone": "Asia/Tehran",
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/calendars/systems" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

POST `/v1/dates/convert` تبدیل تاریخ اجرا در مرورگر

یک تاریخ شمسی، میلادی یا قمری را می‌گیرد و همان روز را در هر سه تقویم، همراه با وضعیت روز کاری، برمی‌گرداند.

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `date` | `DateInput` | الزامی |  |
| `calendar_system` | `object` | اختیاری | مقدارها: `jalali`، `gregorian`، `hijri` |

#### پاسخ‌ها

- **۲۰۰** `ConvertResponse`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست. `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "input": {
    "text": "1405-07-15",
    "calendar_system": "jalali"
  },
  "date": {
    "iso": "2026-10-07",
    "jalali": "1405-07-15",
    "hijri": "1448-04-26",
    "weekday": 3,
    "weekday_fa": "چهارشنبه",
    "jalali_text_fa": "۱۵ مهر ۱۴۰۵",
    "business_day": true,
    "holidays": [],
    "predicted_holiday": false
  },
  "leap_year": false,
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/dates/convert" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1405-07-15"}'
```

POST `/v1/dates/resolve` خواندن تاریخ از متن فارسی اجرا در مرورگر

تاریخ صریح (مانند «۱۵ مهر ۱۴۰۵») یا عبارت نسبی فارسی (مانند «سه روز کاری بعد از ۱۵ مهر ساعت ۱۰»، «فردا» یا «۵ روز قبل») را با روزهای کاری تقویم بانکی به تاریخ دقیق تبدیل می‌کند و مراحل و فرض‌ها را نشان می‌دهد. عبارتی را که بدون حدس قابل خواندن نباشد، رد می‌کند.

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `text` | `string` | الزامی |  |
| `locale` | `object` | اختیاری | پیش‌فرض: `"fa-IR"` |
| `timezone` | `object` | اختیاری | پیش‌فرض: `"Asia/Tehran"` |
| `calendar_system` | `object` | اختیاری | پیش‌فرض: `"jalali"` |
| `reference_instant` | `string` | اختیاری |  |
| `ambiguity_policy` | `AmbiguityPolicy` | اختیاری | مقدارها: `assume_and_report`، `return_candidates`، `reject` |

#### پاسخ‌ها

- **۲۰۰** `ResolveResponse`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۴۲۲** `unresolved_expression` این عبارت بدون حدس‌زدن به تاریخ تبدیل نشد.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "resolution_id": "resolv_01M3VB29M0922GR6818486HQXP",
  "status": "ambiguous",
  "normalized_expression": {
    "type": "business_day_offset",
    "anchor": {
      "kind": "explicit_date",
      "calendar_system": "jalali"
    },
    "offset_business_days": 3,
    "local_time": "10:00:00"
  },
  "resolved": {
    "instant": "2026-10-11T06:30:00.000Z",
    "timezone": "Asia/Tehran",
    "jalali": "1405-07-19 10:00",
    "gregorian": "2026-10-11 10:00"
  },
  "confidence": 0.9,
  "jalali": "1405-07-19",
  "iso": "2026-10-11",
  "time": "10:00",
  "timezone": "Asia/Tehran",
  "date": {
    "iso": "2026-10-11",
    "jalali": "1405-07-19",
    "hijri": "1448-04-30",
    "weekday": 7,
    "weekday_fa": "یکشنبه",
    "jalali_text_fa": "۱۹ مهر ۱۴۰۵",
    "business_day": true,
    "holidays": [],
    "predicted_holiday": false
  },
  "business_day": true,
  "depends_on_predicted_holiday": false,
  "assumptions": [
    {
      "kind": "year",
      "value": "1405"
    }
  ],
  "candidates": [
    {
      "jalali": "1405-07-19",
      "iso": "2026-10-11",
      "time": "10:00",
      "resolved": {
        "instant": "2026-10-11T06:30:00.000Z",
        "timezone": "Asia/Tehran",
        "jalali": "1405-07-19 10:00",
        "gregorian": "2026-10-11 10:00"
      },
      "assumptions": [
        {
          "kind": "year",
          "value": "1405"
        }
      ],
      "business_day": true
    },
    {
      "jalali": "1406-07-19",
      "iso": "2027-10-11",
      "time": "10:00",
      "resolved": {
        "instant": "2027-10-11T06:30:00.000Z",
        "timezone": "Asia/Tehran",
        "jalali": "1406-07-19 10:00",
        "gregorian": "2027-10-11 10:00"
      },
      "assumptions": [
        {
          "kind": "year",
          "value": "1406"
        }
      ],
      "business_day": true
    }
  ],
  "ambiguity_policy": "return_candidates",
  "reference_instant": "2026-09-29T20:00:00.000Z",
  "steps": [
    {
      "step": "متن ورودی",
      "value": "سه روز کاری بعد از 15 مهر ساعت 10"
    },
    {
      "step": "ساعت",
      "value": "۱۰:۰۰"
    },
    {
      "step": "تعداد روز",
      "value": "۳"
    },
    {
      "step": "نوع روز",
      "value": "روز کاری"
    },
    {
      "step": "جهت",
      "value": "بعد"
    },
    {
      "step": "مبنا",
      "value": "شمسی"
    },
    {
      "step": "تقویم کاری",
      "value": "بانکی"
    },
    {
      "step": "فرض",
      "value": "سال ۱۴۰۵ (سال جاری)"
    },
    {
      "step": "تاریخ شمسی",
      "value": "۱۹ مهر ۱۴۰۵"
    },
    {
      "step": "روز هفته",
      "value": "یکشنبه"
    }
  ],
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/dates/resolve" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"سه روز کاری بعد از ۱۵ مهر ساعت ۱۰","locale":"fa-IR","calendar_system":"jalali","timezone":"Asia/Tehran","reference_instant":"2026-09-29T20:00:00Z","ambiguity_policy":"return_candidates"}'
```

### روز کاری محاسبه‌ی روز کاری بر پایه‌ی تقویم بانکی ایران.

POST `/v1/business-days/add` افزودن روز کاری اجرا در مرورگر

چند روز کاری به یک تاریخ اضافه یا از آن کم می‌کند؛ جمعه‌ها و تعطیلات رسمی شمرده نمی‌شوند.

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `date` | `DateInput` | الزامی |  |
| `days` | `integer` | الزامی | بازه: -۳۶۵۰…۳۶۵۰ |

#### پاسخ‌ها

- **۲۰۰** `BusinessDaysAddResponse`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست. `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "from": {
    "iso": "2026-10-07",
    "jalali": "1405-07-15",
    "hijri": "1448-04-26",
    "weekday": 3,
    "weekday_fa": "چهارشنبه",
    "jalali_text_fa": "۱۵ مهر ۱۴۰۵",
    "business_day": true,
    "holidays": [],
    "predicted_holiday": false
  },
  "days": 30,
  "result": {
    "iso": "2026-11-11",
    "jalali": "1405-08-20",
    "hijri": "1448-06-01",
    "weekday": 3,
    "weekday_fa": "چهارشنبه",
    "jalali_text_fa": "۲۰ آبان ۱۴۰۵",
    "business_day": true,
    "holidays": [],
    "predicted_holiday": false
  },
  "calendar_days": 35,
  "depends_on_predicted_holiday": false,
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/business-days/add" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1405-07-15","days":30}'
```

POST `/v1/business-days/diff` شمارش روزهای کاری میان دو تاریخ اجرا در مرورگر

روزهای کاری و روزهای تعطیل میان دو تاریخ را می‌شمارد (روز آغاز شمرده نمی‌شود، روز پایان شمرده می‌شود).

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `from` | `DateInput` | الزامی |  |
| `to` | `DateInput` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `BusinessDaysDiffResponse`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست. `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "from": {
    "iso": "2026-10-07",
    "jalali": "1405-07-15"
  },
  "to": {
    "iso": "2026-11-06",
    "jalali": "1405-08-15"
  },
  "calendar_days": 30,
  "business_days": 25,
  "days_off": [
    {
      "jalali": "1405-07-17",
      "iso": "2026-10-09",
      "reason": "weekend",
      "titles": []
    },
    {
      "jalali": "1405-07-24",
      "iso": "2026-10-16",
      "reason": "weekend",
      "titles": []
    },
    {
      "jalali": "1405-08-01",
      "iso": "2026-10-23",
      "reason": "weekend",
      "titles": []
    },
    {
      "jalali": "1405-08-08",
      "iso": "2026-10-30",
      "reason": "weekend",
      "titles": []
    },
    {
      "jalali": "1405-08-15",
      "iso": "2026-11-06",
      "reason": "weekend",
      "titles": []
    }
  ],
  "depends_on_predicted_holiday": false,
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/business-days/diff" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"1405-07-15","to":"1405-08-15"}'
```

POST `/v1/business-days/is-business-day` آیا این روز کاری است؟ اجرا در مرورگر

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `date` | `DateInput` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `BusinessDayStatus`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست. `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "date": {
    "iso": "2026-10-07",
    "jalali": "1405-07-15",
    "hijri": "1448-04-26",
    "weekday": 3,
    "weekday_fa": "چهارشنبه",
    "jalali_text_fa": "۱۵ مهر ۱۴۰۵",
    "business_day": true,
    "holidays": [],
    "predicted_holiday": false
  },
  "business_day": true,
  "reason": null,
  "predicted": false,
  "previous_business_day": {
    "iso": "2026-10-06",
    "jalali": "1405-07-14"
  },
  "next_business_day": {
    "iso": "2026-10-08",
    "jalali": "1405-07-16"
  },
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/business-days/is-business-day" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1405-07-15"}'
```

GET `/v1/business-days/check` آیا این روز کاری است؟ (با پارامتر) اجرا در مرورگر

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `date` | پرس‌وجو | `DateInput` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `BusinessDayStatus`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست. `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`date` پرس‌وجو، الزامی

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "date": {
    "iso": "2026-10-07",
    "jalali": "1405-07-15",
    "hijri": "1448-04-26",
    "weekday": 3,
    "weekday_fa": "چهارشنبه",
    "jalali_text_fa": "۱۵ مهر ۱۴۰۵",
    "business_day": true,
    "holidays": [],
    "predicted_holiday": false
  },
  "business_day": true,
  "reason": null,
  "predicted": false,
  "previous_business_day": {
    "iso": "2026-10-06",
    "jalali": "1405-07-14"
  },
  "next_business_day": {
    "iso": "2026-10-08",
    "jalali": "1405-07-16"
  },
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/business-days/check?date=1405-07-15" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

GET `/v1/business-days/next` روز کاری بعدی اجرا در مرورگر

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `date` | پرس‌وجو | `DateInput` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `AdjacentBusinessDay`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست. `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`date` پرس‌وجو، الزامی

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "from": {
    "iso": "2027-02-10",
    "jalali": "1405-11-21"
  },
  "direction": "next",
  "result": {
    "iso": "2027-02-13",
    "jalali": "1405-11-24",
    "hijri": "1448-09-06",
    "weekday": 6,
    "weekday_fa": "شنبه",
    "jalali_text_fa": "۲۴ بهمن ۱۴۰۵",
    "business_day": true,
    "holidays": [],
    "predicted_holiday": false
  },
  "calendar_days": 3,
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/business-days/next?date=1405-11-21" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

GET `/v1/business-days/previous` روز کاری قبلی اجرا در مرورگر

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `date` | پرس‌وجو | `DateInput` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `AdjacentBusinessDay`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست. `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`date` پرس‌وجو، الزامی

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "from": {
    "iso": "2027-02-13",
    "jalali": "1405-11-24"
  },
  "direction": "previous",
  "result": {
    "iso": "2027-02-10",
    "jalali": "1405-11-21",
    "hijri": "1448-09-03",
    "weekday": 3,
    "weekday_fa": "چهارشنبه",
    "jalali_text_fa": "۲۱ بهمن ۱۴۰۵",
    "business_day": true,
    "holidays": [],
    "predicted_holiday": false
  },
  "calendar_days": -3,
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/business-days/previous?date=1405-11-24" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

### تعطیلات تعطیلات رسمی ایران؛ تعطیلات قمری پیش‌بینی‌شده جدا مشخص می‌شوند.

GET `/v1/holidays` تعطیلات رسمی یک سال یا ماه شمسی اجرا در مرورگر

تعطیلات قمری تا اعلام رسمی «پیش‌بینی» هستند و ممکن است یک روز جابه‌جا شوند.

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `year` | پرس‌وجو | `integer` | الزامی |  |
| `month` | پرس‌وجو | `integer` | اختیاری |  |

#### پاسخ‌ها

- **۲۰۰** `HolidayList`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۲۲** `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`year` پرس‌وجو، الزامی `month` پرس‌وجو

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "year": 1405,
  "month": 11,
  "count": 2,
  "holidays": [
    {
      "jalali": "1405-11-04",
      "iso": "2027-01-24",
      "title": "ولادت حضرت قائم",
      "kind": "lunar",
      "status": "predicted"
    },
    {
      "jalali": "1405-11-22",
      "iso": "2027-02-11",
      "title": "پیروزی انقلاب اسلامی",
      "kind": "solar",
      "status": "official"
    }
  ],
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/holidays?year=1405&month=11" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

GET `/v1/holidays/{date}` تعطیلات یک روز اجرا در مرورگر

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `date` | مسیر | `DateInput` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `HolidayDay`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست. `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`date` مسیر، الزامی

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "date": {
    "iso": "2027-02-11",
    "jalali": "1405-11-22",
    "hijri": "1448-09-04",
    "weekday": 4,
    "weekday_fa": "پنجشنبه",
    "jalali_text_fa": "۲۲ بهمن ۱۴۰۵",
    "business_day": false,
    "holidays": [
      "پیروزی انقلاب اسلامی"
    ],
    "predicted_holiday": false
  },
  "holiday": true,
  "holidays": [
    {
      "jalali": "1405-11-22",
      "iso": "2027-02-11",
      "title": "پیروزی انقلاب اسلامی",
      "kind": "solar",
      "status": "official"
    }
  ],
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/holidays/1405-11-22" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

### سررسید و مهلت سررسیدها، مهلت بر حسب ساعت کاری و یادآورها.

POST `/v1/deadlines` ساختن سررسید اجرا در مرورگر

سررسیدی بر پایه‌ی تاریخ مبنا، تعداد روز (کاری یا تقویمی) و قاعده‌ی جابه‌جایی در روز تعطیل می‌سازد و نگه می‌دارد.

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `anchor` | `DateInput` | الزامی |  |
| `days` | `integer` | الزامی | بازه: ۰…۳۶۵۰ |
| `type` | `object` | اختیاری | مقدارها: `business`، `calendar`؛ پیش‌فرض: `"business"` |
| `roll` | `Roll` | اختیاری | مقدارها: `following`، `modified_following`، `preceding`، `modified_preceding`، `nearest`، `none` |
| `title` | `string` | اختیاری |  |
| `subject_ref` | `string` | اختیاری |  |

#### پاسخ‌ها

- **۲۰۱** `Deadline`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۰۹** `idempotency_conflict` این Idempotency-Key پیش‌تر با درخواست دیگری به کار رفته است. `idempotency_in_progress` درخواستی با همین Idempotency-Key هنوز در حال پردازش است.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست. `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۱** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "id": "ddl_01M3VB29M043WZCTAH2HQEB8YJ",
  "status": "active",
  "title": null,
  "subject_ref": null,
  "anchor": {
    "iso": "2026-10-07",
    "jalali": "1405-07-15",
    "hijri": "1448-04-26",
    "weekday": 3,
    "weekday_fa": "چهارشنبه",
    "jalali_text_fa": "۱۵ مهر ۱۴۰۵",
    "business_day": true,
    "holidays": [],
    "predicted_holiday": false
  },
  "rule": {
    "days": 10,
    "type": "business",
    "roll": "following"
  },
  "due": {
    "iso": "2026-10-19",
    "jalali": "1405-07-27",
    "hijri": "1448-05-08",
    "weekday": 1,
    "weekday_fa": "دوشنبه",
    "jalali_text_fa": "۲۷ مهر ۱۴۰۵",
    "business_day": true,
    "holidays": [],
    "predicted_holiday": false
  },
  "moved_days": 0,
  "depends_on_predicted_holiday": false,
  "created_at": {
    "iso": "2026-10-01T09:00:00.000Z",
    "local": "2026-10-01T12:30:00+03:30",
    "jalali": "1405-07-09 12:30:00",
    "timezone": "Asia/Tehran"
  },
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/deadlines" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"anchor":"1405-07-15","days":10,"type":"business"}'
```

GET `/v1/deadlines/{id}` دریافت سررسید اجرا در مرورگر

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `Deadline`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`id` مسیر، الزامی

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/deadlines/{id}" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

POST `/v1/sla/due` مهلت بر حسب ساعت کاری اجرا در مرورگر

پایان یک مهلت را با شمردن فقط ساعت‌های کاری حساب می‌کند؛ روزهای تعطیل و ساعت‌های بیرون از وقت اداری شمرده نمی‌شوند.

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `start` | `DateInput` | الزامی |  |
| `time` | `string` | اختیاری | پیش‌فرض: `"09:00"` |
| `hours` | `number` | الزامی | بازه: ……۲۰۰۰ |
| `open` | `string` | اختیاری | پیش‌فرض: `"08:00"` |
| `close` | `string` | اختیاری | پیش‌فرض: `"16:00"` |
| `thursday_close` | `string \| null` | اختیاری |  |

#### پاسخ‌ها

- **۲۰۰** `SlaResponse`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست. `invalid_time` ساعت واردشده معتبر نیست. `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "start": {
    "iso": "2026-10-07T11:30:00.000Z",
    "local": "2026-10-07T15:00:00+03:30",
    "jalali": "1405-07-15 15:00:00",
    "timezone": "Asia/Tehran"
  },
  "hours": 24,
  "due": {
    "iso": "2026-10-12T06:30:00.000Z",
    "local": "2026-10-12T10:00:00+03:30",
    "jalali": "1405-07-20 10:00:00",
    "timezone": "Asia/Tehran"
  },
  "calendar_days": 5,
  "timezone": "Asia/Tehran",
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/sla/due" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start":"1405-07-15","time":"15:00","hours":24,"open":"08:00","close":"16:00","thursday_close":"13:00"}'
```

POST `/v1/reminders/preview` پیش‌نمایش یادآورها اجرا در مرورگر

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

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `due` | `DateInput` | الزامی |  |
| `time` | `string` | اختیاری | پیش‌فرض: `"09:00"` |
| `offsets` | `object[]` | الزامی |  |
| `offsets[].n` | `integer` | الزامی | بازه: ۰…۳۶۵ |
| `offsets[].unit` | `object` | الزامی | مقدارها: `business`، `calendar` |

#### پاسخ‌ها

- **۲۰۰** `RemindersResponse`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست. `invalid_time` ساعت واردشده معتبر نیست.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "due": {
    "iso": "2026-11-11",
    "jalali": "1405-08-20"
  },
  "reminders": [
    {
      "offset": {
        "n": 7,
        "unit": "calendar"
      },
      "at": {
        "iso": "2026-11-04T05:30:00.000Z",
        "local": "2026-11-04T09:00:00+03:30",
        "jalali": "1405-08-13 09:00:00",
        "timezone": "Asia/Tehran"
      },
      "moved_days": 0,
      "depends_on_predicted_holiday": false
    },
    {
      "offset": {
        "n": 3,
        "unit": "business"
      },
      "at": {
        "iso": "2026-11-08T05:30:00.000Z",
        "local": "2026-11-08T09:00:00+03:30",
        "jalali": "1405-08-17 09:00:00",
        "timezone": "Asia/Tehran"
      },
      "moved_days": 0,
      "depends_on_predicted_holiday": false
    },
    {
      "offset": {
        "n": 0,
        "unit": "calendar"
      },
      "at": {
        "iso": "2026-11-11T05:30:00.000Z",
        "local": "2026-11-11T09:00:00+03:30",
        "jalali": "1405-08-20 09:00:00",
        "timezone": "Asia/Tehran"
      },
      "moved_days": 0,
      "depends_on_predicted_holiday": false
    }
  ],
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/reminders/preview" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"due":"1405-08-20","time":"09:00","offsets":[{"n":7,"unit":"calendar"},{"n":3,"unit":"business"},{"n":0,"unit":"calendar"}]}'
```

### تکرار تکرار: نوبت‌های بعدی یک قاعده.

POST `/v1/schedules/preview` نوبت‌های بعدی یک قاعده‌ی تکرار اجرا در مرورگر

نوبت‌های بعدی یک قاعده‌ی تکرار را حساب می‌کند؛ مثلاً «آخرین روز کاری هر ماه».

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `rule` | `object` | الزامی | مقدارها: `last-business`، `first-business`، `day-of-month`، `weekly`، `every-business` |
| `from` | `DateInput` | الزامی |  |
| `count` | `integer` | اختیاری | پیش‌فرض: `6`؛ بازه: ۱…۲۴ |
| `day` | `integer` | اختیاری | بازه: ۱…۳۱ |
| `weekday` | `integer` | اختیاری | بازه: ۱…۷ |
| `roll` | `object` | اختیاری | مقدارها: `following`، `preceding`، `skip`؛ پیش‌فرض: `"following"` |

#### پاسخ‌ها

- **۲۰۰** `SchedulePreview`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۴۲۲** `invalid_date` تاریخ واردشده تاریخ شمسی، میلادی یا قمری معتبری نیست.
- **۴۲۹** `quota_exceeded` سهمیه‌ی ماهانه‌ی عملیات پلن شما تمام شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

ارسال فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **۲۰۰** `Taghvim-Request-Id: req_example`

پاسخ موتور در مرورگر رونوشت

```
{
  "rule": "last-business",
  "rule_fa": "آخرین روز کاری هر ماه",
  "from": {
    "iso": "2026-09-23",
    "jalali": "1405-07-01"
  },
  "occurrences": [
    {
      "jalali": "1405-07-30",
      "iso": "2026-10-22",
      "scheduled_iso": "2026-10-22",
      "moved_days": 0,
      "depends_on_predicted_holiday": false
    },
    {
      "jalali": "1405-08-30",
      "iso": "2026-11-21",
      "scheduled_iso": "2026-11-21",
      "moved_days": 0,
      "depends_on_predicted_holiday": false
    },
    {
      "jalali": "1405-09-30",
      "iso": "2026-12-21",
      "scheduled_iso": "2026-12-21",
      "moved_days": 0,
      "depends_on_predicted_holiday": false
    },
    {
      "jalali": "1405-10-30",
      "iso": "2027-01-20",
      "scheduled_iso": "2027-01-20",
      "moved_days": 0,
      "depends_on_predicted_holiday": false
    }
  ],
  "calendar_data_version": "iran-2026.10.01"
}
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/schedules/preview" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rule":"last-business","from":"1405-07-01","count":4}'
```

### حساب و کلید حساب‌ها و کلیدهای API.

POST `/v1/tenants` ساختن حساب و نخستین کلید API (ویژه‌ی اپراتور) نیازمند توکن اپراتور

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `name` | `string` | الزامی |  |
| `billing_email` | `string` | اختیاری |  |
| `environment` | `Environment` | اختیاری | مقدارها: `live`، `test` |

#### پاسخ‌ها

- **۲۰۱** `TenantCreated`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `forbidden` این اعتبارنامه اجازه‌ی انجام این کار را ندارد.
- **۴۰۹** `idempotency_conflict` این Idempotency-Key پیش‌تر با درخواست دیگری به کار رفته است. `idempotency_in_progress` درخواستی با همین Idempotency-Key هنوز در حال پردازش است.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

فراخوانی واقعی روی api.taghvim.dev بازنشانی

این عملیات ویژه‌ی اپراتور سرویس است و توکن اپراتور لازم دارد.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/tenants" \
  -H "Authorization: Bearer $TAGHVIM_OPERATOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Clinic","billing_email":"billing@example.com","environment":"test"}'
```

GET `/v1/me` حساب و کلیدی که این درخواست را فرستاده است نیازمند کلید API

#### پاسخ‌ها

- **۲۰۰** `Me`
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/me" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

POST `/v1/keys` ساختن کلید API نیازمند کلید API

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `name` | `string` | اختیاری |  |
| `environment` | `Environment` | اختیاری | مقدارها: `live`، `test` |

#### پاسخ‌ها

- **۲۰۱** `ApiKeyWithSecret`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۹** `idempotency_conflict` این Idempotency-Key پیش‌تر با درخواست دیگری به کار رفته است. `idempotency_in_progress` درخواستی با همین Idempotency-Key هنوز در حال پردازش است.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/keys" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"server","environment":"live"}'
```

GET `/v1/keys` فهرست کلیدهای API نیازمند کلید API

#### پاسخ‌ها

- **۲۰۰** `ApiKeyList`
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/keys" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

DELETE `/v1/keys/{id}` باطل کردن کلید API نیازمند کلید API

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `ApiKey`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۴۰۹** `idempotency_conflict` این Idempotency-Key پیش‌تر با درخواست دیگری به کار رفته است. `idempotency_in_progress` درخواستی با همین Idempotency-Key هنوز در حال پردازش است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`id` مسیر، الزامی

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X DELETE "https://api.taghvim.dev/v1/keys/{id}" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### مصرف و پلن پلن‌ها، مصرف اندازه‌گیری‌شده و خروجی صورت‌حساب.

GET `/v1/usage` مصرف در یک دوره نیازمند کلید API

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `period` | پرس‌وجو | `string` | اختیاری |  |

#### پاسخ‌ها

- **۲۰۰** `Usage`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۲۲** `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`period` پرس‌وجو

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/usage?period=1405-07" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

GET `/v1/usage/export` خروجی صورت‌حساب یک دوره نیازمند کلید API

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `period` | پرس‌وجو | `string` | اختیاری |  |
| `format` | پرس‌وجو | `object` | اختیاری |  |

#### پاسخ‌ها

- **۲۰۰** `UsageExport`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۲۲** `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`period` پرس‌وجو `format` پرس‌وجو

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/usage/export?period=1405-07&format=json" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

GET `/v1/plans` پلن‌ها و قیمت‌ها نیازمند کلید API

#### پاسخ‌ها

- **۲۰۰** `PlanList`
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/plans" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

GET `/v1/subscription` اشتراک فعلی نیازمند کلید API

#### پاسخ‌ها

- **۲۰۰** `Subscription`
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/subscription" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

GET `/v1/admin/billing-export` خروجی صورت‌حساب همه‌ی حساب‌ها (ویژه‌ی اپراتور) نیازمند توکن اپراتور

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `period` | پرس‌وجو | `string` | اختیاری |  |

#### پاسخ‌ها

- **۲۰۰** `BillingExport`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `forbidden` این اعتبارنامه اجازه‌ی انجام این کار را ندارد.
- **۴۲۲** `out_of_range` مقدار واردشده بیرون از بازه‌ی پشتیبانی‌شده است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`period` پرس‌وجو

فراخوانی واقعی روی api.taghvim.dev بازنشانی

این عملیات ویژه‌ی اپراتور سرویس است و توکن اپراتور لازم دارد.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/admin/billing-export?period=1405-07" \
  -H "Authorization: Bearer $TAGHVIM_OPERATOR_TOKEN"
```

### خرید پلن خرید پلن: پرداخت، تأیید پرداخت و رسید.

POST `/v1/payment-intents` ساختن درخواست پرداخت برای خرید پلن نیازمند کلید API

برای پلن انتخاب‌شده درخواست پرداخت می‌سازد و نشانی صفحه‌ی پرداخت را برمی‌گرداند. تا پیش از راه‌اندازی پرداخت آنلاین، پاسخ خطای payments\_not\_configured است.

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `plan_id` | `string` | الزامی |  |
| `mobile_number` | `string` | اختیاری |  |

#### پاسخ‌ها

- **۲۰۱** `PaymentIntent`
- **۴۰۰** `idempotency_key_required` این عملیات به سرآیند Idempotency-Key نیاز دارد. `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۴۰۹** `idempotency_conflict` این Idempotency-Key پیش‌تر با درخواست دیگری به کار رفته است. `idempotency_in_progress` درخواستی با همین Idempotency-Key هنوز در حال پردازش است. `plan_unchanged` حساب شما هم‌اکنون روی همین پلن یا پلن بالاتری است.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۴۲۲** `plan_not_purchasable` این پلن را نمی‌توان به‌صورت آنلاین خرید.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.
- **۵۰۲** `payment_provider_error` درگاه پرداخت خطا برگرداند.
- **۵۰۳** `payments_not_configured` پرداخت آنلاین هنوز راه‌اندازی نشده است.

#### امتحان کنید

بدنه‌ی درخواست

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/payment-intents" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"plan_builder"}'
```

GET `/v1/payment-intents/{id}` وضعیت درخواست پرداخت نیازمند کلید API

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `PaymentIntent`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`id` مسیر، الزامی

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/payment-intents/{id}" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

POST `/v1/payment-intents/{id}/verify` تأیید پرداخت از درگاه نیازمند کلید API

اگر بازگشت از درگاه گم شده باشد، این عملیات وضعیت پرداخت را از درگاه می‌پرسد و در صورت تأیید، پلن را ارتقا می‌دهد.

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `PaymentIntent`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۴۰۹** `idempotency_conflict` این Idempotency-Key پیش‌تر با درخواست دیگری به کار رفته است. `idempotency_in_progress` درخواستی با همین Idempotency-Key هنوز در حال پردازش است. `payment_amount_mismatch` مبلغ تأییدشده با مبلغ درخواست پرداخت یکسان نیست. `payment_intent_state` وضعیت درخواست پرداخت اجازه‌ی این کار را نمی‌دهد.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.
- **۵۰۲** `payment_provider_error` درگاه پرداخت خطا برگرداند.
- **۵۰۳** `payments_not_configured` پرداخت آنلاین هنوز راه‌اندازی نشده است.

#### امتحان کنید

`id` مسیر، الزامی

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/payment-intents/{id}/verify" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

POST `/v1/payment-intents/{id}/cancel` لغو درخواست پرداخت نیازمند کلید API

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `PaymentIntent`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۴۰۹** `idempotency_conflict` این Idempotency-Key پیش‌تر با درخواست دیگری به کار رفته است. `idempotency_in_progress` درخواستی با همین Idempotency-Key هنوز در حال پردازش است. `payment_intent_state` وضعیت درخواست پرداخت اجازه‌ی این کار را نمی‌دهد.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`id` مسیر، الزامی

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/payment-intents/{id}/cancel" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

GET `/v1/billing/callback/vandar` بازگشت پرداخت‌کننده از درگاه بدون کلید

پرداخت‌کننده پس از پرداخت به این نشانی برمی‌گردد. این بازگشت فقط یک نشانه است: پرداخت تنها پس از تأیید مستقیم از درگاه و برابری مبلغ، موفق ثبت می‌شود.

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `token` | پرس‌وجو | `string` | الزامی |  |
| `payment_status` | پرس‌وجو | `string` | اختیاری |  |

#### پاسخ‌ها

- **۲۰۰**
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`token` پرس‌وجو، الزامی `payment_status` پرس‌وجو

فراخوانی واقعی روی api.taghvim.dev بازنشانی

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/billing/callback/vandar"
```

GET `/v1/receipts/{id}` دریافت رسید نیازمند کلید API

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `Receipt`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`id` مسیر، الزامی

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/receipts/{id}" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

### رویدادها گزارش رویدادها و انواع رویداد.

GET `/v1/event-log` گزارش رویدادهای حساب نیازمند کلید API

رویدادهای ثبت‌شده‌ی حساب، تازه‌ترین در ابتدا. شناسه‌ی هر رویداد با evtlog\_ آغاز می‌شود؛ evt\_ برای رویدادهای تقویم کنار گذاشته شده است.

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `type` | پرس‌وجو | `EventType` | اختیاری |  |
| `limit` | پرس‌وجو | `integer` | اختیاری |  |

#### پاسخ‌ها

- **۲۰۰** `EventList`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`type` پرس‌وجو `limit` پرس‌وجو

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/event-log" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

GET `/v1/event-log/{id}` یک رویداد از گزارش رویدادها نیازمند کلید API

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `Event`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`id` مسیر، الزامی

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/event-log/{id}" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

GET `/v1/event-types` انواع رویداد بدون کلید

#### پاسخ‌ها

- **۲۰۰** `EventTypeList`
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

فراخوانی واقعی روی api.taghvim.dev بازنشانی

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/event-types"
```

### وب‌هوک نشانی‌های وب‌هوک امضاشده و گزارش تحویل.

POST `/v1/webhooks` ساختن نشانی وب‌هوک نیازمند کلید API

#### بدنه‌ی درخواست

| نام | نوع | الزام | توضیح |
| --- | --- | --- | --- |
| `url` | `string` | الزامی |  |
| `event_types` | `EventType[]` | الزامی |  |
| `description` | `string` | اختیاری |  |

#### پاسخ‌ها

- **۲۰۱** `WebhookWithSecret`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۰۹** `idempotency_conflict` این Idempotency-Key پیش‌تر با درخواست دیگری به کار رفته است. `idempotency_in_progress` درخواستی با همین Idempotency-Key هنوز در حال پردازش است. `webhook_limit_reached` به سقف تعداد نشانی‌های وب‌هوک رسیده‌اید.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۴۲۲** `webhook_url_rejected` نشانی وب‌هوک باید یک نشانی عمومی HTTPS باشد.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/webhooks" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/taghvim","event_types":["taghvim.event.payment.intent.verified.v1"]}'
```

GET `/v1/webhooks` فهرست نشانی‌های وب‌هوک نیازمند کلید API

#### پاسخ‌ها

- **۲۰۰** `WebhookList`
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/webhooks" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

GET `/v1/webhooks/{id}` دریافت نشانی وب‌هوک نیازمند کلید API

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `Webhook`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`id` مسیر، الزامی

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/webhooks/{id}" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

DELETE `/v1/webhooks/{id}` غیرفعال کردن نشانی وب‌هوک نیازمند کلید API

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `Webhook`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۴۰۹** `idempotency_conflict` این Idempotency-Key پیش‌تر با درخواست دیگری به کار رفته است. `idempotency_in_progress` درخواستی با همین Idempotency-Key هنوز در حال پردازش است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`id` مسیر، الزامی

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X DELETE "https://api.taghvim.dev/v1/webhooks/{id}" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

POST `/v1/webhooks/{id}/rotate-secret` تعویض کلید امضا نیازمند کلید API

کلید تازه می‌سازد؛ کلید قبلی تا پایان دوره‌ی هم‌پوشانی هم امضا می‌کند.

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `WebhookWithSecret`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۴۰۹** `idempotency_conflict` این Idempotency-Key پیش‌تر با درخواست دیگری به کار رفته است. `idempotency_in_progress` درخواستی با همین Idempotency-Key هنوز در حال پردازش است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`id` مسیر، الزامی

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/webhooks/{id}/rotate-secret" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

GET `/v1/webhooks/{id}/deliveries` گزارش تحویل‌های یک وب‌هوک نیازمند کلید API

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۰** `DeliveryList`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`id` مسیر، الزامی

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/webhooks/{id}/deliveries" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY"
```

POST `/v1/webhooks/{id}/test` ارسال تحویل آزمایشی نیازمند کلید API

#### پارامترها

| نام | جایگاه | نوع | الزام | توضیح |
| --- | --- | --- | --- | --- |
| `id` | مسیر | `string` | الزامی |  |

#### پاسخ‌ها

- **۲۰۲** `Event`
- **۴۰۰** `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۰۱** `key_revoked` این کلید API باطل شده است. `unauthorized` برای این درخواست کلید API معتبر لازم است.
- **۴۰۳** `entitlement_required` پلن فعلی شما این قابلیت را ندارد.
- **۴۰۴** `not_found` منبع خواسته‌شده پیدا نشد.
- **۴۰۹** `idempotency_conflict` این Idempotency-Key پیش‌تر با درخواست دیگری به کار رفته است. `idempotency_in_progress` درخواستی با همین Idempotency-Key هنوز در حال پردازش است.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

`id` مسیر، الزامی

فراخوانی واقعی روی api.taghvim.dev بازنشانی

فراخوانی واقعی روی حساب شما اجرا می‌شود و در مصرف شما به حساب می‌آید.

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/webhooks/{id}/test" \
  -H "Authorization: Bearer $TAGHVIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### استاندارد اتصال پرداخت استاندارد اتصال پرداخت برای ساخت آداپتور خودتان.

GET `/v1/connectors/payment/standard` استاندارد اتصال پرداخت بدون کلید

#### پاسخ‌ها

- **۲۰۰** `PaymentConnectorStandard`
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

فراخوانی واقعی روی api.taghvim.dev بازنشانی

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl "https://api.taghvim.dev/v1/connectors/payment/standard"
```

POST `/v1/connectors/payment/manifests/validate` بررسی مانیفست آداپتور بدون کلید

#### بدنه‌ی درخواست

#### پاسخ‌ها

- **۲۰۰** `ManifestValidation`
- **۴۰۰** `invalid_json` بدنه‌ی درخواست JSON معتبر نیست. `validation_failed` درخواست با قرارداد API هم‌خوان نیست.
- **۴۱۳** `payload_too_large` حجم بدنه‌ی درخواست بیش از حد مجاز است.
- **۴۱۵** `unsupported_media_type` بدنه‌ی درخواست را با نوع `application/json` بفرستید.
- **۵۰۰** `internal_error` خطای پیش‌بینی‌نشده‌ای رخ داد.

#### امتحان کنید

بدنه‌ی درخواست

فراخوانی واقعی روی api.taghvim.dev بازنشانی

وضعیت: **—**

پاسخ رونوشت

```
پاسخ پس از ارسال اینجا نمایش داده می‌شود.
```

curl جاوااسکریپت پایتون

curl رونوشت

```
curl -X POST "https://api.taghvim.dev/v1/connectors/payment/manifests/validate" \
  -H "Content-Type: application/json" \
  -d '{}'
```

این مشخصات همان قرارداد رسمی api.taghvim.dev است. عملیات‌های تقویم را کد خود موتور در مرورگر شما اجرا می‌کند و تا «فراخوانی واقعی» را نزنید، هیچ درخواستی از این صفحه بیرون نمی‌رود.

محیط تست زمانی

## برای آزمودن آینده، لازم نیست منتظرش بمانید.

با ساعت آزمایشی، ساعت محیط تست را نگه دارید، تنظیم کنید یا جلو ببرید و ببینید سررسیدها، یادآورها، برنامه‌ها و گردش‌کارها در آینده چه می‌کنند.

ساعت محیط تست **۱۴۰۵/۰۷/۰۱، ساعت ۰۹:۰۰**

یک ساعت جلو یک روز جلو یک روز کاری جلو ۳۰ روز جلو بازنشانی

1. هنوز زمانی جلو نرفته است.

فضای کاری نمونه: ۴ یادآور، ۲ برنامه و ۱ سررسید؛ روزهای کاری از موتور تقویم.

آزمودن یک یادآور یک‌ماهه نباید یک ماه طول بکشد.

کاربردها

## یک موتور زمان، برای ده‌ها مدل کسب‌وکار.

نرم‌افزار سرویسی فین‌تک و بانک سلامت منابع انسانی و حقوق حقوقی و انطباق لجستیک عامل‌های هوشمند

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

- ۱ نرم‌افزار نوبت‌دهی
- ۲ مدیریت ارتباط با مشتری
- ۳ مدیریت پروژه
- ۴ بازارگاه آنلاین

تاریخ‌های پیش رو، به حساب موتور تقویم موتور تقویم

**نخستین روز آزاد**

**شنبه ۱۱ مهر ۱۴۰۵**

**پیگیری**

**دوشنبه ۱۳ مهر ۱۴۰۵**

**تمدید اشتراک**

**شنبه ۹ آبان ۱۴۰۵**

هر نقش، یک نما

## هر کس در سازمان همان چیزی را می‌بیند که به کارش می‌آید.

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

توسعه‌دهنده مدیر محصول مالی و حسابداری منابع انسانی پشتیبانی عامل هوشمند

**نما: ترمینال و مستندات** نمونه؛ تاریخ‌ها را موتور تقویم حساب می‌کند

**درخواست**

`POST /v1/business-days/add`

**۳۰ روز کاری پس از امروز**

**پنجشنبه ۱۴ آبان ۱۴۰۵**

**زمان پاسخ**

**در مرورگر، بدون شبکه**

کارش منطق تاریخ را نمی‌نویسد؛ فراخوانی‌اش می‌کند.

عملیات‌های API

- `POST /v1/business-days/add`
- `POST /v1/dates/resolve`
- `GET /v1/holidays`

از چه چیزهایی استفاده می‌کند

- API
- SDK
- CLI
- محیط تست

نتیجه یک فراخوانی، به‌جای یک کتابخانه‌ی تاریخ و فایل دستی تعطیلات.

سازمانی

## از نخستین فراخوانی API تا راه‌اندازی در کل سازمان.

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

- سازمان
- واحد کسب‌وکار الف
- فضای کاری ۱
- فضای کاری ۲
- شریک تجاری
- فضای کاری مشتری

برای B2B، B2B2C و شبکه‌های چندلایه، از روز اول. روی هر سطح بزنید تا کنسول مدیریت آن را ببینید.

**کنسول مدیریت (نمونه)** سازمان نمونه

اعضا و نقش‌ها سیاست‌ها ردپای حسابرسی

- **مریم احمدی** _مالک_
- **رضا کریمی** _مدیر_

مزایا

## هر چیزی که لازم نیست بسازید، سود خالص شماست.

۱

مزیت ۱: زمان مهندسی

### منطق زمان را یک‌بار به ما بسپارید.

به‌جای نگهداری این‌ها:

- تبدیل تاریخ شمسی
- داده‌ی تعطیلات
- تداخل رزروها
- تلاش‌های دوباره
- سررسیدها
- تکرار
- اجرای برنامه‌ها

فقط یک سکو را به محصولتان وصل می‌کنید.

۲

مزیت ۲: یکدستی

### همه‌ی تیم‌ها یک تعریف از «زمان» دارند.

دیگر هیچ‌کدام از این‌ها جداگانه حساب نمی‌کند:

- بک‌اند
- موبایل
- مالی
- عملیات
- عامل هوشمند

۳

مزیت ۳: عرضه‌ی سریع‌تر

### قابلیت تازه را از اجزای پایه‌ی آماده بسازید.

۴

مزیت ۴: ریسک عملیاتی کمتر

### ایمنی در برابر تکرار، رسید، نسخه‌بندی و حسابرسی از ابتدا در طراحی بوده‌اند.

۵

مزیت ۵: آماده برای عامل‌ها

### همان زیرساختی که آدم‌ها به کار می‌برند، برای عامل‌های هوشمند هم آماده است.

بازگشت سرمایه

## هزینه‌ی «خودمان می‌سازیم» را حساب کنید.

ورودی‌های شما

تعداد توسعه‌دهندگان درگیر ساعت توسعه‌ی اولیه ساعت نگهداری در ماه میانگین هزینه‌ی هر ساعت _تومان_ تعداد محصولات یا تیم‌ها

برآورد ماهانه‌ی شما از هزینه‌ی ما (اشتراک و مصرف) _تومان_ قیمت پلن‌ها را از ما بپرسید و برآورد خودتان را اینجا وارد کنید تا مقایسه کامل شود.

هزینه‌ی تخمینی ساخت داخلی **—** ساعت توسعه‌ی اولیه × هزینه‌ی هر ساعت

هزینه‌ی سالانه‌ی نگهداری **—** ساعت نگهداری در ماه × ۱۲ × هزینه‌ی هر ساعت

هزینه‌ی تکرار منطق در ۳ محصول **—** (ساخت + نگهداری سالانه) × (تعداد محصولات − ۱)

سهم هر توسعه‌دهنده از ساعت‌های اولیه **—**

**ساخت داخلی**

مهندسی، نگهداری و تکرار

**اشتراک ما**

هزینه‌ی پیش‌بینی‌پذیر اشتراک و مصرف

قرار نیست ما در هر حالتی از کد داخلی ارزان‌تر باشیم. قرار است هزینه‌ی ساخت، نگهداری، یکدستی و ریسک زیرساخت زمان را **دیدنی و قابل مقایسه** کنیم.

همه‌ی عددها از ورودی‌های خود شما حساب می‌شوند؛ هزینه‌ی خرابی‌ها و رخدادها در این مدل نیامده است.

کارهای عقب‌افتاده

## این‌ها دیگر در فهرست کارهای شما نیستند.

- تبدیل تاریخ شمسی
- به‌روزرسانی تعطیلات
- شمارش روز کاری
- موتور دسترس‌پذیری
- قفل رزرو
- تکرار
- قاعده‌های سررسید
- زمان‌بند
- تلاش دوباره‌ی یادآورها
- تحویل وب‌هوک
- برنامه‌ی عامل‌ها
- شبیه‌سازی زمان

**محصولتان را عرضه کنید**

اطمینان‌پذیری

## زیرساخت زمان باید پیش‌بینی‌پذیر باشد.

**نسخه‌دار**

ساختار داده، رویداد، API و رفتار، بی‌نسخه‌ی تازه تغییر نمی‌کنند.

**امن در تکرار**

تلاش دوباره هیچ عملیاتی را دو بار انجام نمی‌دهد.

**رویدادمحور**

تغییرهای مهم را می‌شود دنبال و بازپخش کرد.

**رسیددار**

هر عملیات مهم نتیجه و ردی دارد که می‌شود بررسی‌اش کرد.

**سیاست‌محور**

عملیات حساس می‌تواند به سیاست، دامنه‌ی دسترسی و تأیید وابسته باشد.

**بازسازی‌پذیر**

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

مقایسه

## کتابخانه‌ی تاریخ، نرم‌افزار نوبت‌دهی، یا زیرساخت زمان؟

همه‌ی ردیف‌ها فقط تفاوت‌ها

- کتابخانه‌ی تاریخ شمسی **۱** قابلیت کامل از ۱۳
- نرم‌افزار نوبت‌دهی **۳** قابلیت کامل از ۱۳
- زیرساخت زمان ما **۱۳** قابلیت کامل از ۱۳

| قابلیت | کتابخانه‌ی تاریخ شمسی | نرم‌افزار نوبت‌دهی | زیرساخت زمان ما |
| --- | --- | --- | --- |
| شمسی و میلادی | دارد | گاهی | دارد |
| تعطیلات | محدود | گاهی | دارد |
| روزهای کاری | محدود | محدود | دارد |
| زمان‌بندی منابع | — | دارد | دارد |
| API رزرو | — | وابسته به محصول | دارد |
| سررسیدها | — | — | دارد |
| تکرار | در حد کتابخانه | دارد | دارد |
| زمان‌بندی عامل‌ها | — | — | دارد |
| MCP | — | — | دارد |
| ویجت‌ها | — | دارد | دارد |
| وب‌هوک و رویداد | — | گاهی | دارد |
| ساعت آزمایشی | — | — | دارد |
| ساختن محصول خودتان روی آن | محدود | محدود | **بله** |

ما جای محصول شما را نمی‌گیریم؛ زیرساختی هستیم که محصول شما روی آن ساخته می‌شود.

قیمت‌گذاری

## رایگان شروع کنید و هر وقت لازم شد، بزرگ‌تر شوید.

### رایگان

بدون کارت بانکی

- API
- SDK
- MCP
- ویجت‌های پایه
- تقویم ایران
- تبدیل تاریخ
- تعطیلات
- روزهای کاری
- محیط تست

رایگان شروع کنید

### سازنده

برای توسعه‌دهندگان مستقل و محصولات کوچکِ در حال اجرا.

با ما تماس بگیرید

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

ثبت در فهرست دسترسی زودهنگام

### استارتاپ

با ما تماس بگیرید

- دسترس‌پذیری
- رزرو
- منابع
- زمان‌بندی عامل‌ها
- ویجت‌های بی‌نشان تجاری

ثبت در فهرست دسترسی زودهنگام

### کسب‌وکار

با ما تماس بگیرید

- کنترل دسترسی نقش‌محور و حسابرسی
- سیاست‌های پیشرفته
- تقویم‌های سازمانی
- پشتیبانی با اولویت

ثبت در فهرست دسترسی زودهنگام

### سازمانی

با ما تماس بگیرید

- SLA سفارشی
- گزینه‌های اختصاصی یا خصوصی
- بسته‌ها و اتصال‌دهنده‌های سفارشی
- راه‌اندازی همراه با پشتیبانی

ثبت در فهرست دسترسی زودهنگام

شروع رایگان است؛ برای پلن‌های بالاتر و سازمانی با ما تماس بگیرید.

برای توسعه‌دهندگان

## یک کار، شش رابط.

API TypeScript Python CLI MCP ویجت

http رونوشت

```
POST /v1/reservations
```

رابط عوض می‌شود؛ قرارداد عوض نمی‌شود.

داشبورد

## همه‌چیز را ببینید، حتی اگر فقط با API کار می‌کنید.

**تقویم.dev™** محیط تست `ten_acme` داده‌ی نمایشی

نمای کلی تقویم‌ها قاعده‌ها وب‌هوک‌ها عامل‌ها مصرف

مصرف این ماه

**۱٫۲۸** از ۲ میلیون عملیات

رویدادهای اخیر

1. `taghvim.event.reservation.confirmed.v1`
2. `taghvim.event.schedule.triggered.v1`
3. `taghvim.event.deadline.created.v1`

سلامت سرویس‌های متصل

تقویم گوگل _✓_ وب‌هوک‌ها _✓_

نمای محصول

## همان موتور، درون اپلیکیشن، ایمیل و ترمینال شما.

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

بانک نمونه نمونه

### انتقال وجه زمان‌بندی‌شده

**از حساب**

جاری ۰۱۲۳

**به**

شرکت پارس‌ابزار

تاریخ واریز

انجام انتقال

ثبت انتقال

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

**یادآور در ایمیل و روی گوشی** نمونه

**سامانه‌ی قراردادهای نمونه** noreply@example.com

### یادآوری: سررسید قرارداد، ۱۳ مهر ۱۴۰۵

سلام خانم رضایی،

قرارداد نمونه‌ی ۱۲۴۰ روز **دوشنبه ۱۳ مهر ۱۴۰۵** سررسید می‌شود. این یادآور ۳ روز کاری پیش از سررسید فرستاده شده است.

قراردادها · اکنون **سررسید نزدیک است**

قرارداد ۱۲۴۰: ۱۳ مهر ۱۴۰۵

متن و نام‌ها نمونه‌اند؛ تاریخ سررسید را موتور تقویم حساب می‌کند.

جست‌وجو

## زمان فقط حساب نمی‌شود؛ پیدا هم می‌شود.

**جست‌وجو** داده‌ی نمایشی

رزروهای لغوشده‌ی هفته‌ی گذشته برای اتاق ۳ سررسیدهای فعال قراردادها در این هفته اجراهای ناموفق عامل‌ها در ماه جاری

«رزروهای لغوشده‌ی هفته‌ی گذشته برای اتاق ۳»

- **نوع:** رزرو
- **وضعیت:** لغوشده
- **منبع:** اتاق ۳
- **بازه:** هفته‌ی گذشته

`rsv_8f21` **اتاق ۳** لغوشده ۱۴۰۵/۰۷/۰۳، ساعت ۱۰:۰۰

`rsv_8f37` **اتاق ۳** لغوشده ۱۴۰۵/۰۷/۰۵، ساعت ۱۴:۳۰

`rsv_9a04` **اتاق ۳** لغوشده ۱۴۰۵/۰۷/۰۷، ساعت ۰۹:۰۰

بازارچه

## از هسته شروع کنید؛ با بسته‌ها گسترش دهید.

### ساخت خود ما

- بسته‌ی پایه‌ی تقویم ایران
- بسته‌ی زمان‌بندی
- بسته‌ی سررسید
- بسته‌ی عامل‌ها
- بسته‌ی توسعه‌دهنده

روی هر بسته بزنید تا محتوایش را ببینید.

### در آینده

- بسته‌ی تقویم بانکی
- بسته‌ی مهلت‌های قانونی
- بسته‌ی حقوق و دستمزد
- بسته‌ی زمان‌بندی درمانی
- اتصال‌دهنده‌ها
- ویجت‌ها

بازارچه برای گسترش زیست‌بوم است، نه شرطی برای اینکه از روز اول بتوانید از ما استفاده کنید.

سناریوهای نمونه

## سه سناریوی نمونه

این‌ها سناریوهای فرضی‌اند، نه نظر یا تجربه‌ی مشتری واقعی.

نمونه‌ی فرضی

### «یک سرویس نوبت‌دهی آنلاین»

**قبل:** تقویم شمسی، دسترس‌پذیری، یادآور و منطق تداخل، در سه سرویس جدا.

**بعد:** تیم محصول فقط گردش‌کار و تجربه‌ی مشتری را می‌سازد.

نمونه‌ی فرضی

### «یک فین‌تک»

**قبل:** تسویه، صورت‌حساب و عملیات هر کدام روز کاری را جور دیگری می‌شمارند.

**بعد:** یک بسته‌ی تقویم و یک محاسبه‌ی مرجع.

نمونه‌ی فرضی

### «یک سکوی عامل‌های هوشمند»

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

**بعد:** برنامه‌ی هر عامل دیدنی است، تابع سیاست است و سنجیده می‌شود.

پرسش‌ها

## پرسش‌های پرتکرار

آیا شما یک تقویم آنلاین هستید؟

نه. ما زیرساختی هستیم برای ساختن قابلیت‌های زمان و زمان‌بندی درون محصول‌های دیگر.

فقط به کار تاریخ شمسی می‌آیید؟

نه. اولویت طراحی ما ایران است، اما مدل زمانی ما شمسی، میلادی و قمری را پوشش می‌دهد.

آیا باید از ویجت‌های شما استفاده کنم؟

نه. ویجت یک رابط اختیاری است. می‌توانید فقط از API، SDK یا MCP استفاده کنید و رابط کاربری را خودتان بسازید.

MCP به چه کاری می‌آید؟

عامل هوشمند با ابزارهای نسخه‌دار و سیاست‌محور ما می‌تواند دسترس‌پذیری را بررسی کند، رزرو بسازد یا سررسید و برنامه‌ی زمانی تعریف کند.

با تقویم گوگل یا Outlook کار می‌کنید؟

اتصال‌دهنده‌ها داده‌ی مرجع ما را با سرویس‌های بیرونی همگام می‌کنند. وضعیت و قابلیت دقیق هر اتصال‌دهنده در مستندات همان اتصال‌دهنده می‌آید.

جای Calendly یا نرم‌افزار نوبت‌دهی را می‌گیرید؟

ما زیرساختی هستیم که می‌شود محصولی مثل آن‌ها را رویش ساخت؛ خودمان لزوماً نرم‌افزار نوبت‌دهی آماده برای کسب‌وکارها نیستیم.

تعطیلات چطور مدیریت می‌شوند؟

با بسته‌های تقویم نسخه‌دار، همراه با منشأ داده و امکان بازنویسی برای هر سازمان.

اگر یک درخواست دو بار فرستاده شود، چه می‌شود؟

عملیات‌های مهمی که چیزی را تغییر می‌دهند در برابر تکرار ایمن‌اند؛ تلاش دوباره به عملیات تکراری نمی‌رسد.

می‌شود آینده را آزمود؟

بله؛ محیط تست زمانی و ساعت آزمایشی برای نگه داشتن و جلو بردن زمان ساخته شده‌اند.

برای سازمان‌های بزرگ مناسب است؟

بله؛ چندمستأجری، جداسازی فضاهای کاری، سیاست‌ها، حسابرسی و رسیدها، و تقویم‌ها و اتصال‌دهنده‌های سفارشی بخشی از مسیر سازمانی‌اند.

## کارهای زمان را از فهرست عقب‌افتاده‌هایتان خط بزنید.

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

رایگان شروع کنید مستندات

بدون کارت بانکی · دسترسی زودهنگام · آزمایشگاه همین حالا روی این صفحه

رایگان شروع کنید