أضف أيام عمل إلى تاريخ

أضف أيام عمل باستخدام واجهة API

استخدم GET /v1/calendars/holidays/{country}/{year} للحصول على تواريخ العطلات للدولة والسنة اللتين يتطلبهما حسابك. تحتفظ دالة Python بتلك التواريخ في مجموعة وتقارن بها كل تاريخ تمر عليه. لا يُحتسب التاريخ إلا إذا كان من الاثنين إلى الجمعة وغير موجود في مجموعة العطلات. تترك التواريخ المتجاوزة عدد أيام العمل المتبقية دون تغيير.

1. اضبط مفتاح API الخاص بك احصل على مفتاح API مجاني واحفظه في متغير البيئة NARWHAL_API_KEY. يقرأ البرنامج النصي ذلك المتغير ويرسل المفتاح بصيغة Authorization: Bearer YOUR_KEY إلى https://api.narwhalapi.com.
2. اختر تاريخ البداية والدولة مرّر تاريخ البداية وأيام العمل المراد إضافتها ورمز الدولة إلى add_business_days؛ وتستخدم الدالة USA افتراضيًا. تاريخ البداية هو اليوم 0، لذا تتقدم الدالة قبل تحديد ما إذا كان التاريخ يُحتسب ضمن الإجمالي.
3. نفّذ الحساب لإضافة خمسة أيام عمل إلى الجمعة 20 نوفمبر 2026 في الولايات المتحدة، استخدم الاستدعاء في نهاية البرنامج النصي. يطبع 2026-11-30، بعد تجاوز عطلات نهاية الأسبوع وعيد الشكر يوم الخميس 26 نوفمبر 2026.
   Python، إضافة أيام عمل إلى تاريخ

   import os
   from datetime import date, timedelta
   import requests
   
   API = "https://api.narwhalapi.com"
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   
   
   def holidays(country: str, year: int) -> set[str]:
       r = requests.get(
           f"{API}/v1/calendars/holidays/{country}/{year}", headers=HEADERS, timeout=10
       )
       r.raise_for_status()
       return {h["date"] for h in r.json()["holidays"]}
   
   
   def add_business_days(start: date, n: int, country: str = "USA") -> date:
       off, loaded, day = set(), set(), start
       while n > 0:
           day += timedelta(1)
           if day.year not in loaded:
               off |= holidays(country, day.year)
               loaded.add(day.year)
           if day.weekday() < 5 and day.isoformat() not in off:
               n -= 1
       return day
   
   
   print(add_business_days(date(2026, 11, 20), 5))

تُحمَّل كل سنة مرة واحدة فقط خلال الحساب. عند الانتقال إلى 1 يناير، تطلب الدالة تقويم العطلات لتلك السنة قبل احتساب أي تواريخ فيها. تسجل المجموعة loaded السنوات الموجودة لديها، بينما تحتفظ off بتواريخ عطلاتها. يستمر التقدم حتى يكتمل عدد أيام العمل المطلوبة، ثم يُعاد التاريخ الذي وصل إليه الحساب.

تقرأ الدالة holidays المصفوفة holidays في الاستجابة وتأخذ date من كل سجل. يقارن الحساب تلك القيم مع day.isoformat()، بينما يحدد day.weekday() شرط يوم الأسبوع. يجب تحقق الشرطين قبل إنقاص n. تظل العطلة التي تقع في نهاية الأسبوع تاريخًا متجاوزًا: تتقدم الحلقة يومًا تقويميًا في كل مرة، ولا يمكن لذلك التاريخ أن يقلل العدد المتبقي. القيمة المعادة هي التاريخ الذي يصل إليه الحساب عند اكتمال العد.

استخدم Excel أو Google Sheets

في Excel أو Google Sheets، ضع 26 نوفمبر 2026 في النطاق المسمى Holidays واستخدم WORKDAY مع تاريخ البداية وعدد أيام العمل. عند إضافة خمسة أيام عمل إلى الجمعة 20 نوفمبر 2026، تعيد الصيغة 30 نوفمبر 2026. يحدد نطاق العطلات التواريخ التي يجب تجاوزها إلى جانب عطلات نهاية الأسبوع، لذا ضمّن تواريخ العطلات التي تنطبق على حسابك.

=WORKDAY(DATE(2026,11,20), 5, Holidays)

نسّق خلية النتيجة كتاريخ. تعيد WORKDAY رقمًا تسلسليًا، لذا فإن تنسيق التاريخ للخلية هو ما يجعل النتيجة تظهر كتاريخ تقويمي. استخدم WORKDAY.INTL عندما يتطلب حسابك أيامًا أخرى لعطلة نهاية الأسبوع. اجعل تاريخ البداية وعدد أيام العمل ونطاق العطلات مطابقين للحساب الذي تريده؛ فالصيغة تستخدم تواريخ العطلات التي تقدمها. في صيغة المثال، يحدد DATE(2026,11,20) تاريخ البداية ويحدد 5 عدد أيام العمل. يشير Holidays إلى النطاق الذي يحتوي على 26 نوفمبر 2026. لاستخدام جدول البيانات مع تاريخ بداية آخر، غيّر تاريخ البداية المدخل وقدّم العطلات المنطبقة.

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

ماذا لو كان تاريخ البداية عطلة أو في نهاية الأسبوع؟

اليوم 1 هو أول يوم عمل بعد تاريخ البداية. إضافة يوم عمل واحد إلى السبت 28 نوفمبر 2026 تعطي الاثنين 30 نوفمبر 2026: يُتجاوز الأحد، ويكون الاثنين يوم العمل الذي طلبت إضافته. تنطبق القاعدة نفسها عندما يكون تاريخ البداية نفسه عطلة. يبدأ العد بعد ذلك التاريخ، مع تجاوز عطلات نهاية الأسبوع وتواريخ العطلات خلاله.

هل يمكنني طرح أيام عمل؟

نعم. ارجع إلى الخلف باستخدام timedelta(-1)، مع تجاوز عطلات نهاية الأسبوع وتواريخ العطلات، أو استخدم =WORKDAY(start, -5, Holidays) في جدول بيانات. تطرح تلك الصيغة خمسة أيام عمل من تاريخ البداية باستخدام نطاق العطلات المقدَّم. في Python، طبّق قاعدة الرجوع إلى الخلف عند تعديل الدالة؛ فالبرنامج النصي المقدَّم يتقدم إلى الأمام.

ماذا لو لم يكن للسنة تقويم عطلات منشور؟

تعيد واجهة API القيمة 404 calendar_not_published لتلك الدولة والسنة. يثير raise_for_status() في البرنامج النصي خطأً لهذه الاستجابة، لذا تتوقف الدالة المقدَّمة عندها. يمكنك تعديلها للاعتماد على عطلات نهاية الأسبوع فقط مع تمييز النتيجة، أو إعادة المحاولة لاحقًا. إذا اعتمدت على عطلات نهاية الأسبوع فقط، فميّز التاريخ المعاد حتى تظل طريقة تعامل الحساب مع العطلات واضحة.

مثال تطبيقي: 5 أيام عمل بعد الجمعة 20 نوفمبر 2026

ابدأ بالجمعة 20 نوفمبر 2026 بوصفه اليوم 0. تجاوز عطلة نهاية الأسبوع، ثم احسب الاثنين 23 نوفمبر والثلاثاء 24 نوفمبر والأربعاء 25 نوفمبر بوصفها أيام العمل 1 و2 و3. الخميس 26 نوفمبر هو عيد الشكر في الولايات المتحدة، لذا يبقى العدد عند 3. الجمعة 27 نوفمبر هو يوم العمل 4.

تجاوز السبت 28 والأحد 29 نوفمبر 2026. الاثنين 30 نوفمبر هو يوم العمل 5، فتكون النتيجة 2026-11-30. دون عطلة عيد الشكر، سيُحتسب الخميس 26 نوفمبر بوصفه يوم العمل 4 والجمعة 27 نوفمبر بوصفه يوم العمل 5، لتكون النتيجة الجمعة 27 نوفمبر 2026 بدلًا من ذلك.