أداة التقويم الفارسي

اعرض التقويم الشمسي والهجري والميلادي في موقعك

المميزات

✓التاريخ الشمسي والهجري والميلادي
✓عرض المناسبات والعطلات
✓دعم الوضع الفاتح والداكن والتلقائي
✓قابل للتخصيص: اللغة والمظهر والموضع
✓خفيف وسريع — بدون تبعيات
✓متوافق مع Shadow DOM — بدون تعارض CSS
✓دعم RTL و LTR

API للمطورين

استخدم API العام من Emrooz للحصول على كتالوجات التقويم، وسوم الأحداث المحلية، خلاصات العطل، وأداة التقويم القابلة للتضمين. مفاتيح المطورين تفتح حدود طلبات أعلى وإدارة webhooks.

عنوان الأساس

https://api.emrooz.app/api/v1

نموذج المصادقة

✓تستخدم مفاتيح Developer API البادئة `emz_`. يعيد `POST /developer/register` قيمة `api_key` مرة واحدة فقط؛ خزّنها بأمان لأنها لا يمكن استرجاعها لاحقاً.
✓مرّر مفاتيح المطور عبر ترويسة `X-API-Key` أو معامل الاستعلام `api_key`. المفتاح مطلوب لـ `/developer/me` و`/developer/rotate-key` وإدارة webhooks؛ وهو اختياري على endpoints كتالوج التقويم العام وخلاصات العطل.
✓تستخدم مفاتيح Embed البادئة `emb_`. يتحقق `POST /embed/validate-key` من المفتاح وhost، ويفحص النطاقات المسموحة، ويسجل تحميل الأداة، ويفرض حدود الدقيقة والشهر.
✓مفاتيح المطور المجانية محدودة بـ 60 طلباً في الدقيقة. خطة `calendar_data` محدودة بـ 1000 طلب في الدقيقة وهي مطلوبة لاستخدام webhooks.

إنشاء مفتاح Developer API

curl -X POST https://api.emrooz.app/api/v1/developer/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Calendar Integration",
    "email": "[email protected]",
    "company": "Example Co",
    "website": "https://example.com"
  }'

استدعاء endpoint كتالوج عام بمفتاح مطور

curl https://api.emrooz.app/api/v1/calendar/public-events?locale=en \
  -H "X-API-Key: emz_your_api_key_here"

Endpoints العامة

الطريقة	المسار	الوصف
POST	/developer/register	ينشئ مفتاح Developer API. تتضمن الاستجابة `api_key` مرة واحدة فقط، مع بادئة المفتاح والخطة وحد الطلبات.
GET	/developer/plans	يعرض خطط المطورين المتاحة، حدود الطلبات والميزات المضمنة.
GET	/developer/me	يعيد ملف المفتاح الحالي واشتراكات webhook النشطة. يتطلب مفتاح Developer API.
POST	/developer/rotate-key	يدوّر المفتاح الحالي ويعيد `api_key` الجديد مرة واحدة فقط. يتطلب مفتاح Developer API.
GET	/calendar/public-events/manifest	يعيد بيانات كتالوج التقويم العام، بما في ذلك الإصدار الحالي وبيانات offset الخاصة بالتقويم.
GET	/calendar/public-events/tags	يعيد وسوم الأحداث العامة باللغة المطلوبة. يدعم معامل `locale`.
GET	/calendar/public-events	يعيد كتالوج الأحداث العامة المنشورة. يدعم فلاتر `locale` و`country_code` و`region` و`tag`.
GET	/feeds/holidays/{country}/{calendar}.ics	يعيد خلاصة iCalendar للعطل. مفتاح المطور يتيح الخلاصة المجمعة `country=all`.
POST	/embed/validate-key	يتحقق من مفتاح أداة `emb_` لhost محدد ويعيد بيانات الخطة، white-label، لون accent والحصة المتبقية.

Webhooks

ينشر backend حالياً webhook واحداً لتغيّر الكتالوج. اشترك به عندما يحتاج التكامل إلى تحديث بيانات التقويم العام المخزنة بعد تغيّر إصدار الكتالوج.

اسم الحدث

calendar.version_bump

متى يعمل

يعمل عندما يتم bump لإصدار كتالوج التقويم العام، بما في ذلك تغييرات الكتالوج من الإدارة، تحديثات offset للتقويم الهجري، والتحديثات المجدولة للنشر.

إنشاء اشتراك webhook

curl -X POST https://api.emrooz.app/api/v1/developer/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: emz_your_api_key_here" \
  -d '{
    "url": "https://example.com/webhooks/emrooz",
    "event": "calendar.version_bump"
  }'

مثال payload مرسل

{
  "event": "calendar.version_bump",
  "data": {
    "version": 42,
    "updated_at": "2026-06-12T15:30:00+00:00",
    "events_count": 384
  },
  "timestamp": "2026-06-12T15:30:01+00:00"
}

Endpoints إدارة webhook

الطريقة	المسار	الوصف
POST	/developer/webhooks	ينشئ اشتراك webhook لـ `calendar.version_bump`. يتطلب خطة المطور `calendar_data`. تعيد الاستجابة `secret` مرة واحدة فقط.
DELETE	/developer/webhooks/{webhook}	يحذف اشتراك webhook واحداً يملكه مفتاح المطور الحالي.

الإرسال والتحقق

✓تتضمن طلبات webhook في جسم JSON الحقول `event` و`data` و`timestamp`، إضافة إلى الترويستين `X-Emrooz-Event` و`X-Emrooz-Signature`.
✓`X-Emrooz-Signature` هو توقيع HMAC-SHA256 لجسم JSON باستخدام `secret` الخاص بالـ webhook الذي يعاد عند الإنشاء.
✓يستخدم الإرسال timeout مدته 10 ثوانٍ. أي استجابة غير 2xx أو خطأ شبكة يزيد `failure_count`؛ وبعد 10 حالات فشل يتم تعطيل الاشتراك.
✓Job الإرسال لا يطبق إعادة محاولة تلقائية للرسائل الفاشلة.

بداية سريعة

بعد الحصول على مفتاح API، ضع هذا الكود في أي مكان في صفحة HTML الخاصة بك:

بالنسبة لعمليات التضمين على المواقع الخارجية، تكون سمة data-key مطلوبة. تحتفظ المفاتيح المجانية بتذييل Emrooz، بينما تفعّل المفاتيح الاحترافية الوضع الأبيض واللون المخصص من الخادم.

<div id="emrooz-widget"></div>
<script src="https://emrooz.app/embed.js"
  data-key="emb_your_api_key_here">
</script>

التخصيص

يمكن تخصيص الأداة عبر سمات data-* وإعدادات مفتاح API:

السمة	النوع	الافتراضي	الوصف
data-theme	"light" \| "dark" \| "auto"	"auto"	سمة الأداة
data-locale	"fa" \| "en" \| "ar"	"fa"	اللغة ونوع الأرقام
data-target	CSS selector	"#emrooz-widget"	حاوية الأداة
data-key	string	(required)	مفتاح API للحصة الشهرية والميزات المدفوعة (بدون علامة تجارية، لون مخصص)

أمثلة

الوضع الداكن:

<div id="emrooz-widget"></div>
<script src="https://emrooz.app/embed.js"
  data-key="emb_your_api_key_here"
  data-theme="dark">
</script>

اللغة الإنجليزية:

<div id="emrooz-widget"></div>
<script src="https://emrooz.app/embed.js"
  data-key="emb_your_api_key_here"
  data-locale="en"
  data-theme="light">
</script>

مفتاح احترافي:

<div id="emrooz-widget"></div>
<script src="https://emrooz.app/embed.js"
  data-key="emb_your_pro_key_here"
  data-theme="auto">
</script>
<!-- White-label + accent color are configured on the API key -->

معاينة

الأداة أدناه يتم تحميلها مباشرة من emrooz.app:

التسعير

الخطة المجانية للمواقع الشخصية والخطة الاحترافية للأعمال

مجاني

$0/ شهريًا

✓10,000 تحميل شهريًا
✓تذييل بعلامة إمروز
✓الوضع الفاتح والداكن والتلقائي
✓دعم RTL/LTR
✓Shadow DOM معزول

اتصل بنا

احترافي

موصى به

$9/ شهريًا

✓100,000 تحميل شهريًا
✓بدون علامة تجارية
✓لون مخصص من الخادم
✓دعم ذو أولوية
✓جميع ميزات الخطة المجانية

احصل على مفتاح API

الاستخدام مع مفتاح API:

<div id="emrooz-widget"></div>
<script src="https://emrooz.app/embed.js"
  data-key="emb_your_api_key_here"
  data-theme="auto">
</script>