كيف تجد سعر الصرف بتاريخ معين لفاتورة

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

1. اضبط مفتاح API الخاص بك احصل على مفتاح مجاني واحفظه في متغير البيئة NARWHAL_API_KEY. يقرأ النص البرمجي هذا المتغير ويرسل المفتاح في ترويسة Authorization: Bearer YOUR_KEY. استخدم المفتاح نفسه مع REST API وMCP في Narwhal؛ والطلب هنا يذهب إلى REST API.
2. طلب تاريخ الفاتورة والأيام السابقة له استخدم GET /v1/fx/rates/EUR/observations مع currencies=USD وstart_date وend_date. اجعل تاريخ النهاية هو تاريخ الفاتورة واطرح سبعة أيام للحصول على تاريخ البداية، كما يفعل النص البرمجي. يتيح هذا النطاق أن تتضمن الاستجابة يومًا سابقًا له سعر عندما تقع الفاتورة في عطلة نهاية الأسبوع أو عطلة رسمية.
3. قراءة آخر مشاهدة شغّل النص البرمجي بلغة Python مع تاريخ الفاتورة والعملة الأساسية وعملة التسعير. تأخذ الدالة آخر صف في observations وتعيد تاريخه وسعره معًا. احتفظ بهما معًا: تاريخ الفاتورة هو التاريخ الذي سألت عنه، أما التاريخ المعاد فيحدد المشاهدة المستخدمة في التحويل.
   Python، السعر في تاريخ الفاتورة أو قبله

   import os
   from datetime import date, timedelta
   import requests
   
   
   def rate_on(invoice: date, base: str, quote: str) -> tuple[str, float]:
       """The rate for the invoice date, or for the last day with a rate before it
       (weekends, holidays)."""
       start = invoice - timedelta(days=7)
       r = requests.get(
           f"https://api.narwhalapi.com/v1/fx/rates/{base}/observations",
           params={
               "currencies": quote,
               "start_date": start.isoformat(),
               "end_date": invoice.isoformat(),
               "limit": 100,
           },
           headers={"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"},
           timeout=10,
       )
       r.raise_for_status()
       last = r.json()["observations"][-1]
       return last["date"], float(last["rates"][0]["rate"])
   
   
   day, rate = rate_on(date(2026, 10, 10), "EUR", "USD")  # 10 October 2026 is a Saturday
   print(day, rate, "-> EUR 12,500 =", round(12500 * rate, 2), "USD")

4. اضرب مبلغ الفاتورة في السعر استخدم السعر المعاد لتحويل مبلغ الفاتورة. بالنسبة إلى الفاتورة المؤرخة 10 أكتوبر 2026، يعيد النص البرمجي تاريخ 9 أكتوبر 2026 وسعرًا قدره 1.1206. وتجمع النتيجة المطبوعة تاريخ المشاهدة مع المبلغ المحوَّل. وإذا كانت لديك مئات الفواتير، فاستخدم النص البرمجي مع ذاكرة تخزين مؤقت لنوافذ السبعة أيام.

نفّذ ذلك في جدول بيانات أو دون شيفرة

إذا كانت لديك فواتير قليلة، فاستخدم جدولًا للأسعار التي جلبتها، يضم عمودًا للتواريخ وعمودًا للأسعار. رتّب التواريخ تصاعديًا قبل تطبيق البحث. ضع تاريخ الفاتورة في A2، واستخدم dates وrates للعمودين المقابلين في الصيغة.

=LOOKUP(A2, dates, rates)

تعيد المطابقة التقريبية سعر آخر تاريخ يقع في A2 أو قبله. ولذلك تستخدم فاتورة يوم السبت اليوم السابق الذي له سعر، دون صيغة منفصلة لعطلة نهاية الأسبوع. اضرب مبلغ الفاتورة في السعر المعاد، مستخدمًا أسعار اتجاه العملة الذي تحتاجه. ويتبع مسار الجدول القاعدة نفسها التي يتبعها النص البرمجي: اختيار آخر مشاهدة متاحة حتى تاريخ الفاتورة. اذكر قاعدة عطلة نهاية الأسبوع والعطلات الرسمية هذه في سياستك المحاسبية.

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

يعتمد السعر الذي تقبله الجهة الضريبية أو المدقق على سياستك المحاسبية. قد تتطلب السياسة تاريخ الفاتورة أو تاريخ الدفع أو المتوسط الشهري أو سعر البنك المركزي. حدّد أيّها ينطبق قبل استخدام البحث بالتاريخ. تقدم Narwhal أسعار المشاهدة اليومية في السوق؛ وعندما تتطلب السياسة سعرًا قانونيًا، فاستخدم السعر الذي تنشره الجهة المختصة. ويُطبَّق حساب تاريخ الفاتورة هنا عندما تتطلب سياستك هذا التاريخ وهذه المشاهدات السوقية.

أي اتجاه لزوج العملات يجب أن أطلبه؟

اطلب عملة الفاتورة كعملة أساسية، والعملة التي تريد التحويل إليها كعملة تسعير. فبالنسبة إلى فاتورة بالعملة EUR تُحوَّل إلى USD، اطلب EUR كعملة أساسية وUSD كعملة تسعير. السعر المعاد هو USD لكل EUR، ولذلك اضرب مبلغ فاتورة EUR في ذلك السعر.

تظهر العملة الأساسية في مسار نقطة نهاية observations، وتوضع عملة التسعير في المعامل currencies. وفي استدعاء Python، تمثل وسيطتا العملة الأساسية وعملة التسعير بعد تاريخ الفاتورة الاختيارين نفسيهما. حافظ على هذا الاتجاه عند وضع الأسعار في الجدول، ليعيد البحث USD لكل EUR في فاتورة بالعملة EUR.

هل يمكنني استخدام نقطة نهاية convert لتاريخ فاتورة؟

استخدم observations لتاريخ فاتورة سابق، لأن نقطة نهاية convert لا تحتوي على معامل للتاريخ. فالطلب GET /v1/fx/convert?from=EUR&to=USD&amount=12500 يحوّل بالسعر الحالي فقط، ولا يختار المشاهدة التي كانت سارية في تاريخ الفاتورة. وللفاتورة المؤرخة، اطلب نطاق observations واضرب المبلغ في آخر سعر في ذلك التاريخ أو قبله.

لماذا تبدأ الاستجابة بعد التاريخ الذي طلبته؟

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

تستخدم الأخطاء application/problem+json مع status وcode وdetail وrequest_id؛ اقرأ تفاصيل الخطأ عند فشل الطلب.

مثال تطبيقي: فاتورة بمبلغ EUR 12,500 بتاريخ 10 أكتوبر 2026

ابدأ بتاريخ الفاتورة، السبت 10 أكتوبر 2026، والمبلغ EUR 12,500. اطلب نافذة السبعة أيام حتى هذا التاريخ. وبما أن الفاتورة تقع في عطلة نهاية الأسبوع، فخذ آخر مشاهدة سابقة: الجمعة 9 أكتوبر 2026. وسعر EUR/USD في ذلك التاريخ هو 1.1206 USD لكل EUR.

بسعر 9 أكتوبر 2026، اضرب EUR 12,500 في 1.1206 لتحصل على USD 14,007.50 للفاتورة المؤرخة 10 أكتوبر 2026. ويطبع النص البرمجي تاريخ المشاهدة 2026-10-09 والمبلغ المحوَّل 14007.5 USD.