ضبط تنبيه قبل صدور البيانات الاقتصادية

نفّذ ذلك باستخدام واجهة API

1. احصل على مفتاح API الخاص بك احصل على مفتاح API مجاني واحفظه في متغير البيئة NARWHAL_API_KEY. تُرسل الطلبات إلى https://api.narwhalapi.com مع Authorization: Bearer YOUR_KEY؛ وتقرأ الأمثلة المفتاح من هذا المتغير.
2. إنشاء خلاصة تقويم أرسل POST /v1/calendars/subscriptions مع الدول ونطاق التواريخ. يطلب المثال USA وعائلتي prices وpolicy_rate ودون عطلات رسمية، من 24 أكتوبر 2026 حتى 23 أكتوبر 2027.
   curl، إنشاء خلاصة تقويم

   curl -s -X POST https://api.narwhalapi.com/v1/calendars/subscriptions \
     -H "Authorization: Bearer $NARWHAL_API_KEY" -H "Content-Type: application/json" \
     -d '{"countries":["USA"],"start_date":"2026-10-24","end_date":"2027-10-23",
         "include_holidays":false,"families":["prices","policy_rate"]}'

3. حفظ تفاصيل الاشتراك احفظ subscription_id وurl وexpires_at من الاستجابة. يُعاد عنوان .ics مرة واحدة فقط، فاحتفظ به وتعامل معه كسر.
4. استخدام النص البرمجي اليومي للبريد أو الدردشة لإرسال تنبيه إلى قناة الفريق، شغّل هذا النص البرمجي مرة يوميًا وأرسل مخرجاته عبر webhook الوارد في أداة الدردشة. ويمكنك أيضًا إرسال المخرجات إلى البريد الإلكتروني من كودك الخاص.
   Python، الإصدارات المقررة خلال الـ 24 ساعة القادمة

   import os, sys
   from datetime import datetime, timedelta, timezone
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   COUNTRIES = ["USA", "GBR", "JPN"]
   AHEAD = timedelta(hours=24)
   
   
   def upcoming():
       now = datetime.now(timezone.utc)
       r = requests.get(
           "https://api.narwhalapi.com/v1/economics/calendar",
           headers=HEADERS,
           timeout=10,
           params={
               "countries": COUNTRIES,
               "start_date": now.date().isoformat(),
               "end_date": (now + AHEAD).date().isoformat(),
               "limit": 100,
           },
       )
       r.raise_for_status()
       for x in r.json()["releases"]:
           if x["status"] == "scheduled" and "at" in x:
               at = datetime.fromisoformat(x["at"].replace("Z", "+00:00"))
               if now <= at <= now + AHEAD:
                   yield x, at
   
   
   for release, at in upcoming():
       print(
           f"{release['country']} {release['name']} ({release.get('period')}) "
           f"at {at:%Y-%m-%d %H:%M} UTC"
       )

قدّم من 1 إلى 50 رمز دولة بصيغة alpha-3، وتاريخي بداية ونهاية شاملين لا يفصل بينهما أكثر من 366 يومًا. ويقبل المرشح الاختياري families ما يصل إلى 5 عائلات.

مدة الصلاحية 365 يومًا بعد الإنشاء؛ فتنتهي صلاحية خلاصة أُنشئت في 24 أكتوبر 2026 في 24 أكتوبر 2027. القيمة الافتراضية لكل من include_releases وinclude_holidays هي true، ويجب أن يكون أحدهما على الأقل true. ويوقف المثال العطلات الرسمية ويُبقي الإصدارات مضمّنة.

يقرأ النص البرمجي تقويم USA وGBR وJPN، ثم يطبع الإصدارات المجدولة التي يقع وقت at الخاص بها خلال الـ 24 ساعة القادمة. ويتضمن كل سطر مطبوع الدولة واسم الإصدار والفترة والوقت بتوقيت UTC. ولا يطبع شيئًا إذا لم يكن هناك إصدار مقرر.

يستخدم النص البرمجي UTC لساعته ولطوابع الإصدارات الزمنية. ويغطي طلبه تواريخ التقويم من وقت التشغيل حتى نهاية فترة الـ 24 ساعة القادمة، بحد أقصى 100.

تشمل مقارنة الطوابع الزمنية الحدين معًا. ويُستبعد الإصدار الذي لا يحتوي على الحقل at، وكذلك الإصدار الذي لا تكون حالته scheduled. ويستدعي الطلب raise_for_status() قبل قراءة الاستجابة، فيتوقف عند خطأ HTTP قبل أن يطبع أي إصدارات.

ضبط تذكير دون كود

أضف عنوان الخلاصة إلى تطبيق التقويم كتقويم مشترَك به. في Google Calendar، انتقل إلى Other calendars > From URL والصق عنوان .ics. ويوفر Outlook وApple Calendar خيار الاشتراك في تقويم من الويب. استخدم العنوان الذي أعاده طلب الاشتراك.

تتضمن الخلاصة في المثال إصدارات USA من عائلتي prices وpolicy_rate. ولتضمين العطلات الرسمية أيضًا، استخدم include_holidays بالقيمة true في طلب الإنشاء. ولطلب العطلات وحدها، اجعل include_releases على false واترك include_holidays على true.

اضبط الإشعار الافتراضي لذلك التقويم، مثلًا قبل الإصدار بـ 1 ساعة. فإعداد التذكير يخص تطبيق التقويم. وإنشاء الخلاصة يمنحك عنوان الاشتراك؛ أما إضافته إلى التطبيق وضبط الإشعار فهما الخطوتان اللتان تحوّلانه إلى تذكير شخصي.

راجع وثائق اشتراكات التقويم لطلب الخلاصة. وإذا أردت أوقات الإصدار بمنطقتك الزمنية، فراجع تحويل وقت الإصدار إلى منطقتك الزمنية.

متى تستخدم كل خيار

تُبلغ webhooks عن إضافة إصدار أو نقله أو إلغائه عبر release.scheduled وrelease.rescheduled وrelease.cancelled. كما تُبلغ عن البيانات المنشورة عبر dataset.published. لكنها لا تُطلق مؤقتًا قبل الإصدار. استخدم تذكير التقويم أو النص البرمجي للتنبيه المسبق، واستخدم Webhook عندما تحتاج إلى أحداث التغيير أو النشر هذه.

هل تتحدث الخلاصة عند نقل موعد الإصدار؟

نعم، يعيد تطبيق التقويم جلب الخلاصة وفق جدوله الخاص، وتدعم الخلاصة التحديث عبر ETag. ويأتي التأخير من عميل التقويم. يصل تغيير الموعد إلى التقويم المشترَك به عندما يحدّث التطبيق الخلاصة، والتطبيق هو من يتحكم في وتيرة ذلك.

كيف أوقف خلاصة التقويم؟

استدعِ DELETE /v1/calendars/subscriptions/{subscription_id} لإلغائها. تكون الاستجابة 204 وتتوقف الخلاصة. استخدم subscription_id الذي حفظته من استجابة الإنشاء لهذا الطلب؛ أما عنوان الخلاصة فهو القيمة التي أعطيتها لتطبيق التقويم.

كم طلبًا تستهلك خلاصة التقويم؟

يستهلك إنشاء الخلاصة طلبًا واحدًا، ويستهلك إلغاؤها طلبًا واحدًا. أما عمليات الجلب اللاحقة من تطبيق التقويم فلا تستخدم مفتاح Bearer الخاص بك. أبقِ عنوان الخلاصة سريًا مع أن تطبيق التقويم يستخدم هذا العنوان لجلب التقويم.

مثال تطبيقي: تذكير قبل 1 ساعة من مؤشر أسعار المستهلك الأمريكي

ابدأ بإصدار مؤشر أسعار المستهلك الأمريكي عند 2026-11-10T13:30:00Z. اطرح ساعة واحدة من 13:30 UTC لتحصل على وقت التذكير 12:30 UTC يوم 10 نوفمبر 2026. واضبط الإشعار الافتراضي للتقويم المشترَك به على ساعة واحدة قبل الحدث.

في نيويورك يقع التذكير نفسه عند 07:30 EST يوم 10 نوفمبر 2026، وفي جاكرتا عند 19:30 يوم 10 نوفمبر 2026. هذه هي الأوقات المحلية للتذكير؛ أما الإصدار نفسه فيكون عند 13:30 UTC في ذلك اليوم.