shekel-currency-converter

谢克尔货币转换器

说明

步骤 1：识别转换请求

解析用户的请求，提取：

• 源货币和目标货币（至少一个应为 NIS/ILS）
• 要转换的金额
• 日期（当前日期或特定历史日期，税务转换时尤为重要）
• 用途（一般信息还是税务相关的代表性汇率）

常见货币代码：

代码	货币	希伯来语
ILS	以色列新谢克尔	shekel chadash
USD	美元	dolar
EUR	欧元	euro
GBP	英镑	lira sterling
JPY	日元	yen
CHF	瑞士法郎	frank shveitzi

步骤 2：获取汇率

当前汇率（实时 JSON 端点）： 旧版 XML 源 currency.xml 已失效（现在会重定向到 JSON API），因此不要解析 XML。获取 JSON 端点并读取 exchangeRates 数组。

Fetch: https://www.boi.org.il/PublicApi/GetExchangeRates
Parse JSON: response.exchangeRates is an array of objects.
Each object: key (currency code), currentExchangeRate (NIS per "unit"),
             unit (1, 10, or 100), currentChange (percent move vs. previous
             publication), lastUpdate (ISO timestamp).

示例对象：{"key":"USD","currentExchangeRate":2.972,"unit":1,"currentChange":-0.47,"lastUpdate":"2026-08-26T12:22:04Z"}。其中，currentChange 是每日变动百分比，而非绝对的 NIS 变化值，且不会用于转换计算。

汇率日期应取自 lastUpdate，绝不能使用系统时钟。“最近发布”并不等同于“今天”。在下一次汇率发布之前，端点会继续提供上一次发布的数据，因此当天发布前发出的任何请求都会返回前一个工作日的汇率。由于税务所用的 shaar yatzig 会标注日期，若将其标记为今天，就会错误地注明所用汇率对应的日期；这是税务转换绝不能出现的错误。如果响应中没有 lastUpdate，则不要报告日期：说明无法确定发布日期。

历史日期／税务日期汇率（SDMX 系列）： JSON 端点的 ?date= 参数会被忽略，始终返回最近发布的汇率。对于特定过去日期（税务所需的汇率），请改用以色列银行 SDMX EXR 系列：

Fetch: https://edge.boi.gov.il/FusionEdgeServer/sdmx/v2/data/dataflow/BOI.STATISTICS/EXR/1.0/RER_<CUR>_ILS?startPeriod=YYYY-MM-DD&endPeriod=YYYY-MM-DD&format=csv
Replace <CUR> with the currency code (e.g., RER_USD_ILS, RER_EUR_ILS).
Parse CSV: read OBS_VALUE keyed by TIME_PERIOD.

该系列不包含非发布日（周六、周日和节假日）。如果指定日期没有对应记录，则向前查找该日期当天或之前最近的已发布日期，并告知用户所用汇率对应的日期。

步骤 3：计算转换

If converting FROM NIS:
  result = amount / rate * unit

If converting TO NIS:
  result = amount * rate / unit

If converting between two foreign currencies:
  nis_amount = amount * rate_source / unit_source
  result = nis_amount / rate_target * unit_target

**两种外币之间的转换结果是推算值，并非已发布的汇率。**以色列银行仅发布各货币兑谢克尔的汇率，不发布其他汇率，因此通过两个谢克尔汇率相除得出的 USD/EUR 数值，从未由以色列银行设定、发布或标注日期。应将其标记为推算值，绝不能称为 shaar yatzig；对于税务金额，应分别按各自的代表性汇率将每笔外币金额换算成谢克尔，而不是进行交叉换算。如果有日期的交叉换算需要使用两个不同发布日期的汇率，则不要为其标注单一日期：应分别列出每个汇率。

有些低面值货币的发布精度非常粗略。黎巴嫩镑的发布汇率为每 10 单位 0.0003，只保留 1 位有效数字，因此换算总额的误差范围约为正负 17%。该发布值是官方代表性汇率，因此使用它并没有错，但不要将换算总额表述得精确到 agora。

注意：以色列银行的汇率表示每单位（或每若干单位）外币可兑换多少 NIS。 示例（仅作说明；请获取实时／指定日期的汇率）：USD 汇率约为 2.97，单位 = 1 表示 1 USD 约等于 2.97 NIS。 示例（仅作说明）：JPY 汇率约为 1.87，单位 = 100 表示 100 JPY 约等于 1.87 NIS。 注意小单位货币的精度：黎巴嫩镑的汇率按 4 位小数显示时会呈现为 0.0000 NIS，尽管换算总额是正确的；因此应提高精度，而不是报告零汇率。

第 4 步：呈现结果

格式应包含：

• 换算后的金额（NIS 保留 2 位小数，其他货币采用适当精度）
• 所用汇率及其发布日期（取自 lastUpdate 或 SDMX TIME_PERIOD），而不是查询日期。如果调用者询问的是今天的汇率，而今天的汇率尚未发布，请明确说明，不要把上一期发布的汇率说成是今天的汇率
• 此技能不是交易行情源，不是银行或信用卡换算汇率，也不涵盖加密货币。参考汇率每个工作日发布一次，供参考和报告使用
• 来源：“Bank of Israel representative rate (shaar yatzig)”
• 注意事项：“仅供参考的代表性汇率。实际银行汇率可能有所不同。”

哪一天的汇率适用（税务）

• **境外收入：**适用收入确认／收到之日的代表性汇率。
• **境外支出：**适用付款日的代表性汇率。
• **年末重估：**资产负债表项目适用 12 月 31 日的代表性汇率。这是账簿核算口径；无需记账的个人适用不同规则，因此不要据此建议私人客户申报个人境外存款的汇兑收益。
• **境外证券或其他境外资产的资本利得：**涉及两个不同日期，而不是一个日期。按取得日的代表性汇率换算成本，按处置日的汇率换算所得款项，然后根据这两个谢克尔金额计算谢克尔利得。按单一日期将外币净收益换算为谢克尔，是另一种通常低估金额的算法，也是这方面最常见的错误。
• **外币贷款：**每项交易（提款、每次还款）都应按该交易发生时的汇率换算，而不是在年末一次性换算余额；商业贷款的汇兑差额属于融资项目，并非一次性的年度调整。
• 进口增值税（需视货物或服务而定）：
  • 进口货物经进口报关单（rashimon）清关：海关计税价值采用海关汇率（shaar hamekhes），该汇率由以色列税务局每周发布，并非单纯的代表性汇率。**请从以色列税务局查询相关周发布的海关汇率，不要自行推算。**常见说法是海关汇率比代表性汇率高 0.5%，但以色列税务局的汇率服务屏蔽了机器人，无法通过此技能进行机器验证，因此任何推算值都应视为未经确认，并应引用已发布的汇率。对于货物进口增值税，绝不要把单纯的 shaar yatzig 作为适用汇率。
  • 进口服务（反向征收增值税，例如境外 SaaS 或海外承包商）：增值税按相关日期的单纯 BOI 代表性汇率计算，不加任何海关上调幅度。海关汇率仅适用于以 rashimon 报关的货物。

示例

示例 1：美元兑换谢克尔

用户说：“把 1000 美元换算成谢克尔” 结果：“1,000 USD = X NIS（按 Bank of Israel 当前代表性汇率；引用具体金额前，请先获取带日期的汇率）。”

示例 2：历史汇率

用户说：“2026 年 1 月 1 日的美元汇率是多少？” 结果：获取 SDMX RER_USD_ILS 序列。2026 年 1 月 1 日不是发布日，因此报告该日期当日或之前最近一次发布的汇率（2026 年首个观测值为 2026 年 1 月 2 日），并说明所用日期。

示例 3：税务相关汇率

用户说：“我需要用于 2025 年 12 月增值税申报的 EUR 汇率。” 结果：从 SDMX 序列中提供相关交易日期的代表性汇率，并注明这是税务用途的官方汇率。若涉及进口增值税，请特别告知用户查询每周发布的海关汇率。

随附资源

脚本

• scripts/fetch_rates.py - 获取以色列银行官方代表性汇率（shaar yatzig），并执行与 NIS 之间的货币兑换。当前汇率使用实时 JSON 端点，历史日期查询使用 SDMX EXR 系列（并按发布日期逐日回溯）。获取失败时会明确报错（打印错误并以非零状态退出），绝不会用示例汇率替代真实兑换；示例输出仅可通过显式指定 --demo 获取。运行：python scripts/fetch_rates.py --help

参考资料

• references/boi-api-guide.md - 以色列银行汇率 API 文档：实时 JSON 端点及其字段、SDMX EXR 历史系列、更新计划和进口增值税海关汇率注意事项。排查 API 调用问题或了解汇率发布时间时请查阅。
• references/currency-codes.md - 支持的货币代码、希伯来语名称、NIS 典型汇率范围和单位值（对 JPY 和其他多单位货币尤为重要）。解析用户的货币请求或处理基于单位的兑换时请查阅。

参考链接

资源	URL
BOI 汇率页面	https://www.boi.org.il/en/economic-roles/financial-markets/exchange-rates/
实时 JSON 汇率端点	https://www.boi.org.il/PublicApi/GetExchangeRates
BOI SDMX EXR 历史系列	https://edge.boi.gov.il/FusionEdgeServer/sdmx/v2/data/dataflow/BOI.STATISTICS/EXR/1.0/RER_USD_ILS

推荐的 MCP 服务

如需获取实时汇率数据，请将此技能与以下服务配合使用：

MCP 服务	提供内容	安装
boi-exchange	以色列银行针对已发布货币提供的官方每日代表性汇率（sha'ar yatzig）、历史汇率系列、汇率变动计算，以及通过 BOI SDMX API 直接进行货币兑换。无需 API 密钥。	安装 boi-exchange

如果可以使用 boi-exchange MCP，请使用其工具进行实时兑换，而不要使用上述静态参考表。该 MCP 提供官方代表性汇率（shaar yatzig），以色列税务规则要求在交易日期使用该汇率。

注意事项

• NIS 的官方货币代码为 ILS（ISO 4217），但以色列人通常称其为 “shekel” 或 “shekalim”。Agent 可能无法将 “NIS” 识别为有效货币代码，或将其与 1985 年以前的 “Old Shekel”（IS）混淆。
• 以色列银行每天为每种货币发布一个代表性汇率（不区分买入价和卖出价）；周一至周四在 15:15 之后不久发布，周五（及节假日前夕）在 12:15 之后不久发布。周六、周日和以色列节假日不设汇率。Agent 可能在发布时间之前获取汇率，得到上次发布的汇率，却没有提示该汇率已过时。
• 只有以色列银行正式发布的货币才有代表性汇率（目前为 14 种：USD、GBP、JPY、EUR、AUD、CAD、DKK、NOK、ZAR、SEK、CHF、JOD、LBP、EGP）。此技能不是适用于全球所有货币的通用外汇兑换工具。
• NIS 的格式是在数字前放置谢克尔符号，千位使用逗号，小数使用句点（例如，1,234.56）。Agent 可能会使用欧洲格式（1.234,56），或将符号放在数字后面。
• 用于税务计算时，以色列法律要求使用交易具体日期的 BOI 代表性汇率（sha'ar yatzig），而非实时外汇汇率。进口商品的增值税应使用税务局发布的每周海关汇率；进口服务（反向征收增值税）应使用普通代表性汇率。Agent 可能会使用不符合税务申报法律要求的实时汇率。

故障排查

错误：“所选日期无可用汇率”

原因：所选日期为星期六、星期日、以色列节假日或未来日期。 解决方案：使用 SDMX 系列中所选日期当日或之前最近一次发布的汇率。以色列银行在星期一至星期四（15:15 之后不久）和星期五（12:15 之后不久）发布汇率，星期六、星期日和节假日除外。

错误：“不支持该货币”

原因：以色列银行不会发布该货币的代表性汇率（仅涵盖列出的 14 种货币）。 解决方案：建议使用 USD 或 EUR 作为中间货币进行兑换。