查詢發票日期的匯率

使用 API

1. 設定你的 API 金鑰 取得免費金鑰，並存放在環境變數 NARWHAL_API_KEY 中。腳本會讀取該變數，並透過 Authorization: Bearer YOUR_KEY 標頭傳送金鑰。Narwhal 的 REST API 與 MCP 使用同一組金鑰；這裡的請求發送至 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. 將發票金額乘以匯率 用回傳的匯率換算發票金額。對於日期為 2026 年 10 月 10 日的發票，腳本回傳 2026 年 10 月 9 日與匯率 1.1206。輸出結果會把觀測日期與換算後的金額放在一起。如果有數百張發票，請使用帶七天視窗快取的腳本。

使用試算表或不寫程式的方式

如果只有少量發票，可以用一個存放已取得匯率的試算表，包含一欄日期與一欄匯率。套用查詢之前，先把日期依遞增順序排序。將發票日期放在 A2，並在公式中用 dates 和 rates 表示對應的欄。

=LOOKUP(A2, dates, rates)

近似比對會回傳不晚於 A2 的最近日期的匯率。因此週六的發票會使用此前有匯率的那一天，無需另寫週末公式。把發票金額乘以回傳的匯率，並使用你需要的幣別方向的匯率。試算表方式與腳本遵循相同的規則：選取截至發票日期的最後一筆可用觀測值。請在會計政策中寫明這條週末與假日規則。

各種情況適合的方式

稅務機關或查核人員接受哪一種匯率，取決於你的會計政策。該政策可能要求使用發票日期、付款日期、月平均匯率或央行匯率。在使用日期查詢之前，請先確定適用哪一種。Narwhal 提供的是市場每日觀測匯率；如果政策要求法定匯率，請使用主管機關公布的匯率。這裡依發票日期的計算，適用於政策要求採用該日期與這些市場觀測值的情形。

應該依哪個貨幣對方向請求？

請求時把發票幣別作為基礎幣別，把要換算成的幣別作為報價幣別。對於以 EUR 開立、要換算成 USD 的發票，請以 EUR 為基礎幣別、USD 為報價幣別。回傳的匯率是每 EUR 兌多少 USD，所以把 EUR 發票金額乘以該匯率。

基礎幣別放在 observations 端點的路徑中，報價幣別則放在 currencies 參數裡。在 Python 呼叫中，發票日期之後的基礎幣別與報價幣別參數就是同樣的選擇。把匯率放入試算表時也要維持這個方向，這樣 EUR 發票的查詢結果就是每 EUR 兌多少 USD。

可以用 convert 端點查詢發票日期的匯率嗎？

過去的發票日期請使用 observations，因為 convert 端點沒有日期參數。GET /v1/fx/convert?from=EUR&to=USD&amount=12500 只依目前匯率換算，不會選取發票日期當天適用的觀測值。對於有日期的發票，請求 observations 的時間範圍，並把金額乘以該日期當天或之前的最後一個匯率。

為什麼回應是從我請求的日期之後才開始？

依發票查詢時，範圍需要包含發票日期，以及在該日期沒有匯率時可用的更早觀測值。所有帳戶都可讀取完整歷史。

錯誤使用 application/problem+json，包含 status、code、detail 和 request_id；請求失敗時請閱讀錯誤詳情。

實例：2026 年 10 月 10 日開立的 EUR 12,500 發票

從發票日期 2026 年 10 月 10 日（週六）與金額 EUR 12,500 開始。請求截至該日期的七天視窗。由於發票日期落在週末，取此前的最後一筆觀測值：2026 年 10 月 9 日（週五）。當天的 EUR/USD 匯率是每 EUR 兌 USD 1.1206。

依 2026 年 10 月 9 日的匯率，把 EUR 12,500 乘以 1.1206，得到 2026 年 10 月 10 日發票的金額 USD 14,007.50。腳本會把觀測日期輸出為 2026-10-09，把換算後的金額輸出為 14007.5 USD。