مرجع API لاشتراكات التقويم

أنشئ موجز ICS قابلًا للإلغاء للإصدارات الاقتصادية أو الإجازات الرسمية أو كليهما.

أنشئ اشتراكًا

استخدم مفتاح Bearer الخاص بـ Narwhal لطلب الإنشاء. نظرة عامة على المنتج ‏←

POST /v1/calendars/subscriptions

curl --request POST \
  --url "https://api.narwhalapi.com/v1/calendars/subscriptions" \
  --header "Authorization: Bearer $NARWHAL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"countries":["USA"],"start_date":"2026-09-01","end_date":"2026-12-31","include_releases":true,"include_holidays":true}'

حقول الطلب

حقل	قاعدة
`countries`	قائمة مطلوبة من 1–50 رمز دولة ISO alpha-3.
`start_date / end_date`	نافذة تاريخ شاملة مطلوبة بين 1900 و2200 وبفاصل أقصاه 366 يومًا.
`include_releases / include_holidays`	قيم منطقية اختيارية؛ القيمة الافتراضية لكليهما true. يجب أن يبقى أحدهما على الأقل true.
`families`	فئات إصدارات اختيارية: `gdp`, `prices`, `labour`, `trade`, `yield_curve`. احذف المعلمة أو استخدم قائمة فارغة لتضمين جميع الفئات. وللموجز الذي يقتصر على العطلات، اضبط `include_releases` على false.
`scope`	معرّف نطاق اختياري غير فارغ، يصل إلى 64 حرفًا.

يمكن لاشتراكات العطلات فقط استخدام دول العطلات المنشورة خارج مجموعة دول الإصدارات الاقتصادية.

استجابة نموذجية

استجابة توضيحية. احفظ عنوان URL للرمز عند إنشاء الاشتراك؛ تعيده استجابة الإنشاء مرة واحدة.

تم الإنشاء

{
  "subscription_id": "example-subscription",
  "url": "https://api.narwhalapi.com/v1/calendars/subscriptions/EXAMPLE_TOKEN.ics",
  "expires_at": "2026-12-31T23:59:59Z",
  "refresh_note": "calendar clients control refresh latency"
}

subscription_id يحدد السجل المطلوب إلغاؤه. expires_at هو الطابع الزمني لانتهاء الصلاحية؛ ويتحكم عميل التقويم في زمن التحديث.

التحديث والإلغاء

يجلب عميل التقويم الموجز باستخدام GET /v1/calendars/subscriptions/{token}.ics. يدعم الموجز التحديث باستخدام ETag. تعامل مع عنوان URL الخاص برمزه كبيان سري؛ إذ يمكن لأي شخص يملكه قراءة الموجز حتى انتهاء الصلاحية أو الإلغاء.

استخدم مفتاح Bearer الخاص بك مع DELETE /v1/calendars/subscriptions/{subscription_id} لإلغائه. تُرجع رموز الموجز المنتهية الصلاحية أو الملغاة أو غير المعروفة 404. ولا يتضمن الموجز مفتاح API الخاص بك أبدًا.