عرض العطل الرسمية للرواتب بحسب الدولة والسنة

الحصول على قائمة وطنية لدولة واحدة

يعيد GET /v1/calendars/holidays/{country}/{year} عطل دولة ما لسنة معينة. يُبقي المعامل الاختياري scope نوعًا واحدًا من العطل. يطلب هذا الطلب إندونيسيا لعام 2026 ويُبقي national_public فقط.

curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/calendars/holidays/IDN/2026?scope=national_public"

{
  "country": "IDN",
  "coverage": [
    {
      "scope": "national_public",
      "subdivision_codes": []
    }
  ],
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year’s Day",
      "holiday_key": "new_years_day",
      "local_name": "Tahun Baru 2026 Masehi",
      "scope": "national_public",
      "subdivision_codes": []
    },
    {
      "date": "2026-01-16",
      "name": "Isra and Mi’raj",
      "holiday_key": "isra_and_miraj",
      "local_name": "Isra Mikraj Nabi Muhammad S.A.W.",
      "scope": "national_public",
      "subdivision_codes": []
    }
  ]
}

تبيّن قائمة coverage ما يحويه التقويم: نطاق واحد هو national_public مع قائمة subdivision_codes فارغة. القائمة الفارغة في أي إدخال تعني أن العطلة تسري على مستوى الدولة كلها. ويحمل local_name الاسم باللغة المحلية عند توفره. وتضم الاستجابة الكاملة 17 تاريخًا.

الحصول على قائمة إقليمية لدولة أخرى

ليست كل العطل وطنية. يطلب هذا الطلب أستراليا لعام 2026 دون scope.

curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/calendars/holidays/AUS/2026"

{
  "country": "AUS",
  "coverage": [
    {
      "scope": "bank",
      "subdivision_codes": [
        "AU-NSW"
      ]
    },
    {
      "scope": "regional_public",
      "subdivision_codes": [
        "AU-NSW"
      ]
    }
  ],
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year’s Day",
      "holiday_key": "new_years_day",
      "scope": "regional_public",
      "subdivision_codes": [
        "AU-NSW"
      ]
    },
    {
      "date": "2026-01-26",
      "name": "Australia Day",
      "holiday_key": "australia_day",
      "scope": "regional_public",
      "subdivision_codes": [
        "AU-NSW"
      ]
    }
  ]
}

هنا يحمل كل إدخال subdivision_codes بقيمة AU-NSW، وتسرد coverage النطاقين bank وregional_public، وكلاهما لـ AU-NSW فقط. يغطي التقويم ولاية نيو ساوث ويلز. ولا يحوي شيئًا عن الولايات الأسترالية الأخرى، لذا يحتاج نظام الرواتب الذي لديه موظفون في فيكتوريا إلى مصدر آخر لها. وتحمل الإدخالات أيضًا observed: فـ Additional Day for Boxing Day في 28 ديسمبر يوم عمل بديل عن 26 ديسمبر الذي يصادف يوم سبت.

عدّ العطل التي تنطبق على كل موظف

1. احصل على مفتاح API احصل على مفتاح API من صفحة التسجيل واحفظه في NARWHAL_API_KEY.
2. ربط كل دولة بالتقسيم الإداري للموظف يربط البرنامج النصي IDN بلا تقسيم إداري وAUS بـ AU-NSW. استخدم التقسيم الإداري من سجل الموظف.
3. الاحتفاظ بالإدخالات المنطبقة وتجميعها حسب النطاق ينطبق الإدخال عندما تكون قائمة subdivision_codes فارغة أو تتضمن التقسيم الإداري للموظف. يجمّع البرنامج النصي التواريخ حسب scope ويعدّ كم منها يقع في أيام الأسبوع، لأن العطل في نهاية الأسبوع لا تُنقص يوم عمل.
   Python، العطل حسب النطاق لدولتين

   import os
   from collections import defaultdict
   from datetime import date
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   
   
   def year_list(country, year):
       r = requests.get(
           f"https://api.narwhalapi.com/v1/calendars/holidays/{country}/{year}",
           headers=HEADERS,
           timeout=10,
       )
       r.raise_for_status()
       return r.json()
   
   
   for country, region in (("IDN", None), ("AUS", "AU-NSW")):
       data = year_list(country, 2026)
       print(country, [(c["scope"], c["subdivision_codes"]) for c in data["coverage"]])
       dates = defaultdict(set)  # scope -> dates that apply to this employee
       for h in data["holidays"]:
           if not h["subdivision_codes"] or region in h["subdivision_codes"]:
               dates[h["scope"]].add(h["date"])
       for scope, days in sorted(dates.items()):
           weekdays = [d for d in days if date.fromisoformat(d).weekday() < 5]
           print("  ", scope, len(days), "dates,", len(weekdays), "on weekdays")

IDN [('collective_leave', []), ('national_public', [])]
   collective_leave 8 dates, 8 on weekdays
   national_public 17 dates, 13 on weekdays
AUS [('bank', ['AU-NSW']), ('regional_public', ['AU-NSW'])]
   bank 1 dates, 1 on weekdays
   regional_public 13 dates, 9 on weekdays

عدد أيام الأسبوع هو الرقم الذي تقارنه بتقويم الرواتب. لدى إندونيسيا 21 تاريخًا في أيام الأسبوع عبر النطاقين، ولدى نيو ساوث ويلز 10. أما كون يوم collective_leave أو عطلة bank إجازة مدفوعة في عقودك فمرده إلى سياستك والقواعد المحلية. تضع الواجهة وسمًا لكل يوم ولا تحدد الأجر.

مثال تطبيقي: أسبوع عيد الفطر في إندونيسيا

تقع كلتا تاريخي national_public في عطلة نهاية الأسبوع، لذا لا يُظهر الطلب بـ scope=national_public أي يوم عمل ضائع في ذلك الأسبوع. أما أيام الأسبوع الثلاثة، الجمعة 20 والإثنين 23 والثلاثاء 24 مارس، فتظهر فقط ضمن collective_leave. وكان نظام رواتب يقتصر على العطل الوطنية سيفوّتها. لهذا يقرأ البرنامج النصي القائمة كلها ويجمّعها حسب النطاق.

ماذا تعني النطاقات لحساب الرواتب؟

national_public عطلة للبلد كله. ويضم collective_leave أيام cuti bersama في إندونيسيا، وهي أيام إضافية يسردها التقويم ضمن نطاق مستقل. وتحمل إدخالات regional_public وbank رموز تقسيمات إدارية توضح أين تنطبق.

اطلب السنة دون scope وجمّع حسبه في الشيفرة كما يفعل البرنامج النصي، لترى كل أنواع الأيام. أضف scope إلى الطلب فقط عندما تحتاج قاعدة رواتب واحدة إلى ذلك النوع وحده.

عندما تشير قاعدة إلى عطلة بعينها، اعتمد holiday_key مفتاحًا لها لا name. ضمن الدولة الواحدة يسمّي المفتاح عطلة واحدة، فقاعدة christmas_day تلتقط تلك العطلة وحدها من القائمة المعادة، أما الاسم فنص للعرض قد يختلف من دولة إلى أخرى. ويُستخدم المفتاح نفسه للنوع نفسه من الأيام في دول أخرى، وهذا مفيد حين تغطي سياسة واحدة عدة دول.

كيف أحصل على عطل ولاية أو منطقة واحدة فقط؟

لا تملك نقطة نهاية السنة معاملًا للتقسيم الإداري، لذا صفِّ في الشيفرة: احتفظ بالإدخالات التي تكون subdivision_codes فيها فارغة أو تتضمن الرمز، مثل AU-NSW. اقرأ coverage أولًا، فهو يبيّن أي التقسيمات الإدارية يغطيها التقويم أصلًا.

ماذا يحدث عندما لا تكون لدولة ما عطل في نطاق معين؟

تعيد الواجهة استجابة مشكلة بحالة 404 ورمز calendar_not_published، ويذكر حقل detail فيها الدولة والسنة والنطاق المطلوب. وقد أعادتها طلبات المملكة المتحدة مع scope=regional_public، لأن إدخالات المملكة المتحدة تستخدم النطاق bank. اطلب دون scope لترى النطاقات الموجودة.