israeli-e-invoice

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Israeli E-Invoice

以色列电子发票

Instructions

操作说明

Step 1: Determine Invoice Type

步骤1：确定发票类型

Ask the user what type of document they need:

Code	Hebrew	English	When to Use
300	hashbonit mas	Tax Invoice	B2B sales, services over threshold
305	hashbonit mas / kabala	Tax Invoice / Receipt	B2C with immediate payment
310	hashbonit zikui	Credit Invoice	Refunds, corrections, returns
320	kabala	Receipt	Payment confirmation only
330	hashbonit proforma	Proforma Invoice	Quotes, pre-billing (no allocation needed)

询问用户需要的文档类型：

代码	希伯来语	中文	使用场景
300	hashbonit mas	税务发票	B2B销售、超阈值服务
305	hashbonit mas / kabala	税务发票/收据	即时付款的B2C交易
310	hashbonit zikui	贷记发票	退款、更正、退货
320	kabala	收据	仅用于付款确认
330	hashbonit proforma	形式发票	报价、预开票（无需分配编号）

Step 2: Collect Required Fields

步骤2：收集必填字段

For all invoice types, gather:

Seller details: Business name, TIN (mispar osek), address, phone
Buyer details: Business name (or individual), TIN (if B2B), address
Transaction: Date, item descriptions, quantities, unit prices
Payment: Method (cash, transfer, check, credit card), terms

所有发票类型均需收集以下信息：

卖家信息：企业名称、纳税人识别号（mispar osek）、地址、电话
买家信息：企业名称（或个人姓名）、纳税人识别号（若为B2B交易）、地址
交易信息：日期、商品描述、数量、单价
付款信息：付款方式（现金、转账、支票、信用卡）、付款条款

Step 3: Calculate VAT

步骤3：计算VAT

Standard Israeli VAT rate: Always verify current rate with the Tax Authority (standard rate is 17% as of 2024-2026, but rates may change)
VAT calculation:
```
vat_amount = net_amount * vat_rate
```
Total:
```
gross_amount = net_amount + vat_amount
```
For VAT-exempt transactions (osek patur), no VAT line -- use receipt (320) instead

以色列标准VAT税率：请始终向税务机关核实当前税率（2024-2026年标准税率为17%，但税率可能变动）
VAT计算公式：
```
vat_amount = net_amount * vat_rate
```
总金额：
```
gross_amount = net_amount + vat_amount
```
免税交易（osek patur）无需VAT项——请改用收据（320）

Step 4: Check Allocation Number Requirement

步骤4：检查分配编号要求

Determine if an allocation number is needed:

Required if: Invoice amount >= current threshold AND invoice type is 300, 305, or 310
Current thresholds: Always verify current thresholds with the Tax Authority, as requirements change over time
Not required for: Receipts (320), proforma (330), invoices below threshold

If allocation number IS required:

Inform user they must request from SHAAM before issuing
Provide the API call structure (see references/shaam-api-reference.md)
The allocation number must appear on the printed/sent invoice

判断是否需要分配编号：

需分配编号的情况：发票金额≥当前阈值，且发票类型为300、305或310
当前阈值：请始终向税务机关核实当前阈值，要求可能随时间变化
无需分配编号的情况：收据（320）、形式发票（330）、低于阈值的发票

若需要分配编号：

告知用户必须先向SHAAM申请才能开具发票
提供API调用结构（详见references/shaam-api-reference.md）
分配编号必须显示在打印/发送的发票上

Step 5: Generate Invoice Document

步骤5：生成发票文档

Create the invoice with all fields formatted per Israeli standards:

Date in both Gregorian (DD/MM/YYYY) and Hebrew calendar
Amounts in NIS (New Israeli Shekel)
VAT breakdown as separate line
Sequential invoice number from seller's series
Allocation number (if applicable)

按照以色列标准格式创建包含所有字段的发票：

同时显示公历（DD/MM/YYYY）和希伯来日历日期
金额以新以色列谢克尔（NIS）为单位
VAT明细单独列示
卖家序列中的连续发票编号
分配编号（如适用）

Step 6: Validate

步骤6：验证

Run validation checks:

All required fields present
TIN format valid (9 digits with check digit)
VAT calculation correct
Invoice number sequential
Date not in the future
Allocation number present if above threshold

If validation fails, report specific errors and how to fix them.

执行验证检查：

所有必填字段是否齐全
纳税人识别号格式是否有效（9位数字含校验位）
VAT计算是否正确
发票编号是否连续
日期是否未超出当前日期
超阈值发票是否包含分配编号

若验证失败，报告具体错误及修复方法。

Examples

示例

Example 1: Simple B2B Tax Invoice

示例1：简单B2B税务发票

User says: "Create a tax invoice for a web development project, 15,000 NIS to ABC Ltd" Actions:

Identify: Tax Invoice (type 300), above threshold -- allocation needed
Collect: Seller and buyer details
Calculate: Net 15,000 + VAT (at current rate) = Total amount
Guide: Request allocation number from SHAAM
Generate: Formatted invoice document Result: Complete tax invoice with all required fields and allocation number guidance

用户需求：“为一个Web开发项目创建税务发票，金额15,000 NIS，客户为ABC有限公司” 操作步骤：

确定类型：税务发票（300型），超阈值——需分配编号
收集信息：卖家和买家详情
计算金额：净额15,000 + VAT（按当前税率）= 总金额
指导操作：向SHAAM申请分配编号
生成文档：格式化的发票文档结果：包含所有必填字段及分配编号指导的完整税务发票

Example 2: Small B2C Receipt

示例2：小额B2C收据

User says: "I need a receipt for a 500 NIS cash payment" Actions:

Identify: Receipt (type 320), below threshold -- no allocation needed
Collect: Seller and buyer details
Generate: Receipt document Result: Simple receipt, no allocation number required

用户需求：“我需要一张500 NIS现金付款的收据” 操作步骤：

确定类型：收据（320型），低于阈值——无需分配编号
收集信息：卖家和买家详情
生成文档：收据文档结果：简单收据，无需分配编号

Example 3: Credit Invoice for Refund

示例3：退款贷记发票

User says: "I need to issue a credit note for invoice #1234, partial refund of 3,000 NIS" Actions:

Identify: Credit Invoice (type 310)
Reference: Original invoice #1234
Calculate: Credit amount with VAT reversal
Check: Allocation requirement based on amount Result: Credit invoice referencing original, with correct VAT reversal

用户需求：“我需要为发票#1234开具贷记单，部分退款3,000 NIS” 操作步骤：

确定类型：贷记发票（310型）
关联原发票：原发票#1234
计算金额：包含VAT冲抵的贷记金额
检查要求：根据金额判断是否需要分配编号结果：关联原发票的贷记发票，VAT冲抵正确

Bundled Resources

捆绑资源

Scripts

脚本

```
scripts/validate_invoice.py
```
— Validates Israeli e-invoice JSON against SHAAM requirements: checks required fields, TIN (mispar osek) format and check digit, invoice type codes, VAT calculation accuracy, and allocation number thresholds. Also referenced in Troubleshooting below. Run:
```
python scripts/validate_invoice.py --help
```

```
scripts/validate_invoice.py
```
— 验证以色列电子发票JSON是否符合SHAAM要求：检查必填字段、纳税人识别号（mispar osek）格式和校验位、发票类型代码、VAT计算准确性及分配编号阈值。以下故障排除部分也会引用该脚本。运行方式：
```
python scripts/validate_invoice.py --help
```

References

参考资料

```
references/shaam-api-reference.md
```
— SHAAM (Tax Authority) API endpoints for requesting allocation numbers, OAuth2 authentication setup, and request/response formats. Consult when integrating with the SHAAM e-invoice API. Also referenced in Step 4 above.
```
references/invoice-types.md
```
— Complete listing of Israeli invoice type codes (300, 305, 310, 320, 330, 400) with required fields per type, VAT applicability, and allocation number requirements. Consult when determining which invoice type to use.
```
references/compliance-timeline.md
```
— Progressive e-invoice mandate timeline per Amendment 157 to the VAT Law, showing threshold reductions from 25,000 NIS down to all invoices. Consult when checking current allocation number thresholds.

```
references/shaam-api-reference.md
```
— SHAAM（税务机关）用于申请分配编号的API端点、OAuth2认证设置及请求/响应格式。集成SHAAM电子发票API时参考。步骤4中也会引用。
```
references/invoice-types.md
```
— 以色列发票类型代码（300、305、310、320、330、400）的完整列表，包含各类型必填字段、VAT适用性及分配编号要求。确定发票类型时参考。
```
references/compliance-timeline.md
```
— 《增值税法》第157修正案规定的电子发票强制推行时间线，展示阈值从25,000 NIS逐步降低至覆盖所有发票的过程。检查当前分配编号阈值时参考。

Gotchas

注意事项

Israeli e-invoices require a SHAAM allocation number (mispar hiktza'a) from the Tax Authority. Agents may generate invoices without this number, making them non-compliant.
The e-invoice XML schema follows the Israeli Tax Authority specification, not the European Peppol or UBL standard. Agents may generate UBL-formatted XML that Israeli systems cannot process.
Starting from 2024, Israeli businesses above the turnover threshold must issue e-invoices. Agents may not check whether the business meets this threshold before skipping e-invoice requirements.
The SHAAM system validates the buyer's tax ID (mispar osek) in real-time. Agents may use placeholder or invalid tax IDs that will be rejected by the validation service.

以色列电子发票需要来自税务机关的SHAAM分配编号（mispar hiktza'a）。若生成的发票无此编号，将不符合合规要求。
电子发票XML架构遵循以色列税务机关规范，而非欧洲Peppol或UBL标准。若生成UBL格式的XML，以色列系统将无法处理。
从2024年起，营业额超阈值的以色列企业必须开具电子发票。若未检查企业是否符合该阈值就跳过电子发票要求，将不符合规定。
SHAAM系统会实时验证买家的纳税人识别号（mispar osek）。若使用占位符或无效的纳税人识别号，将被验证服务拒绝。

Troubleshooting

故障排除

Error: "Invalid TIN format"

错误：“纳税人识别号格式无效”

Cause: Israeli TIN (mispar osek) must be exactly 9 digits with valid check digit Solution: Verify the number with the check digit algorithm. Run scripts/validate_invoice.py for validation.

原因：以色列纳税人识别号（mispar osek）必须为9位数字且包含有效校验位解决方案：使用校验位算法验证编号。运行scripts/validate_invoice.py进行验证。

Error: "Allocation number required"

错误：“需分配编号”

Cause: Invoice amount exceeds current threshold for mandatory allocation Solution: Request allocation number from SHAAM API before issuing invoice. See Step 4.

原因：发票金额超过强制分配编号的当前阈值解决方案：开具发票前通过SHAAM API申请分配编号。详见步骤4。

Error: "VAT rate mismatch"

错误：“VAT税率不匹配”

Cause: Using incorrect VAT rate (rate changes periodically) Solution: Always verify current rate with the Tax Authority. Check their website or contact them directly for the most up-to-date VAT rate.

原因：使用了错误的VAT税率（税率会定期变动）解决方案：始终向税务机关核实当前税率。查看其官网或直接联系获取最新VAT税率。

Error: "Invoice type not suitable"

错误：“发票类型不适用”

Cause: Wrong invoice type selected for the transaction Solution: Review the invoice type table in Step 1. Common mistake: using type 300 when 305 (with receipt) is needed for immediate payment.

原因：为交易选择了错误的发票类型解决方案：查看步骤1中的发票类型表格。常见错误：即时付款交易使用300型而非305型（带收据）。