---
name: karteset-invoicing
description: >-
  Issue Israeli tax documents (חשבונית מס-קבלה 320, חשבונית מס 305, חשבונית זיכוי 330)
  through the Karteset API. Use whenever the user wants to bill a customer, turn an order/sale
  into an invoice or receipt, fetch a document, or download its PDF.
---

# כרטסת — הפקת חשבוניות מ-Claude Code

הסקיל הזה מלמד את Claude Code להפיק מסמכים חשבונאיים ישראליים דרך ה‑API של **כרטסת** —
בקריאת REST אחת מקבלים **חשבונית מס‑קבלה (320)** חוקית עם מספר רץ, רישום בספרים, ומספר הקצאה אוטומטי.

> איך משתמשים: שמרו קובץ זה כ‑`.claude/skills/karteset/SKILL.md` בפרויקט (סקיל), **או** כ‑`CLAUDE.md`.
> אחר כך פשוט בקשו מ‑Claude Code בשפה חופשית, למשל: *"הנפק חשבונית מס‑קבלה ללקוח דני כהן על הזמנה #1042, 2 יחידות במחיר 250 ₪, שולם באשראי"*.

---

## 1. הגדרה חד‑פעמית (API key)

1. ב‑כרטסת: **הגדרות → API** (זמין בתוכנית **איקומרס**) → צרו מפתח. המפתח מוצג **פעם אחת** — שמרו אותו.
   - `ks_live_…` = חי · `ks_test_…` = בדיקות.
2. שמרו את המפתח כמשתנה סביבה (אל תכתבו אותו בקוד):
   ```bash
   export KARTESET_API_KEY="ks_live_xxxxxxxxxxxxxxxxxxxx"
   ```

**Base URL:** `https://hash.karteset.co.il/api/v1`
**אימות:** בכל בקשה — הכותרת `Authorization: Bearer $KARTESET_API_KEY`

⚠️ **אבטחה:** לעולם אל תטמיע את המפתח בקוד/גיט. קרא אותו מ‑`KARTESET_API_KEY` בלבד.

---

## 2. הפעולה העיקרית — הפקת חשבונית מס‑קבלה (320)

`POST /v1/tax-receipts`

גוף הבקשה (JSON):
```json
{
  "customer": {
    "name": "דני כהן",
    "tax_id": "123456782",
    "email": "danny@example.com",
    "address": "הרצל 10", "city": "תל אביב", "zip": "6100000", "country": "IL"
  },
  "items": [
    { "description": "חולצה כחולה", "sku": "SHIRT-BLUE", "variant": "מידה: L",
      "quantity": 2, "unit_price": 250.00 }
  ],
  "payment": { "method": "credit", "reference": "טרנזקציה 88231" },
  "shipping": { "amount": 25.00 },
  "source":   { "platform": "החנות שלי", "order_no": "1042", "url": "https://mystore.co.il/orders/1042" },
  "currency": "ILS",
  "date": "2026-09-06"
}
// הערה: השדה "date" הוא תאריך ההזמנה לאסמכתא בלבד. מסמך המס מונפק תמיד בתאריך הנוכחי
// (חובת הנפקה כרונולוגית רציפה ודיווח בתקופת המע״מ הפתוחה).
```

דוגמת curl:
```bash
curl -X POST https://hash.karteset.co.il/api/v1/tax-receipts \
  -H "Authorization: Bearer $KARTESET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{ "customer": {"name":"דני כהן","tax_id":"123456782"},
        "items": [{"description":"חולצה כחולה","quantity":2,"unit_price":250}],
        "payment": {"method":"credit"},
        "source": {"order_no":"1042"} }'
```

תשובה (201):
```json
{
  "id": "ad205ee3-...", "number": "320-000045", "doc_type": 320,
  "amount_before_vat": 525.00, "vat": 94.50, "total": 619.50, "currency": "ILS",
  "exchange_rate": 1.0, "total_ils": 619.50,
  "allocation_number": "…", "pdf_url": "https://hash.karteset.co.il/api/v1/documents/ad205ee3-.../pdf",
  "issued_at": "2026-09-06T09:12:00Z"
}
```

**מה לעשות עם התשובה:** שמרו את `id` ואת `number` אצל ההזמנה במערכת של המשתמש, והציגו/שמרו את `pdf_url`.

---

## 3. שדות מלאים

**customer** — `name` (חובה), `tax_id` (ע.מ/ח.פ, 9 ספרות), `email`, `phone`, `mobile`, `address`, `city`, `zip`, `country` (ברירת מחדל `IL`).
**items[]** — `description` (חובה), `sku` (מק"ט — נשמר לקטלוג), `barcode`, `url`, `variant` (וריאציה — מתווספת לתיאור), `quantity` (ברירת מחדל 1), `unit_price`, `vat_rate` (אופציונלי — ראו מע"מ למטה).
**payment** — `method`: `credit` | `cash` | `bank` | `transfer`; `reference`. (רק ב‑tax‑receipts; ב‑invoices אין payment.)
**shipping** — `amount`, `vat_rate` (אופציונלי) — נוסף כשורת "דמי משלוח".
**source** — `platform`, `order_no`, `url` — פרטי ההזמנה במערכת המקור (חשוב ל‑idempotency).
**date** — תאריך ההזמנה, **אסמכתא בלבד**. המסמך מונפק תמיד בתאריך הנוכחי (חובת הנפקה כרונולוגית רציפה + דיווח בתקופת המע"מ הפתוחה). **currency** — `ILS` (ברירת מחדל) / `USD` / `EUR` / `GBP`. **notes**.

---

## 4. מע"מ — אוטומטי

- אם לא שולחים `vat_rate` בשורה — כרטסת קובעת אוטומטית: **18% ללקוח בישראל**, **0% ליצוא** (לקוח עם `country` שאינו `IL`).
- אפשר לכפות `vat_rate` בשורה (למשל `0` לפריט פטור). אל תחשבו מע"מ בעצמכם — שלחו `unit_price` **לפני מע"מ** וכרטסת תחשב.

---

## 5. מטבע זר

- שלחו `currency` (`ILS`/`USD`/`EUR`/`GBP`) והמחירים ב-`items` **באותו מטבע**. **אל תשלחו שקלים ואל תשלחו שער חליפין** — כרטסת ממירה לבד לפי שער בנק ישראל של יום ההפקה.
- ה-PDF מציג את הסכום המקורי + "שער חליפין" + "שווי בש"ח" (דרישה חוקית). התשובה מחזירה גם `exchange_rate` וגם `total_ils`.
- מטבע לא נתמך (שאין לו שער) מחזיר שגיאה נקייה `400` — לא רישום שגוי.

---

## 5. מניעת כפילויות (Idempotency) — חשוב

כדי לא להפיק את אותה חשבונית פעמיים (למשל אם ניסיון קודם נכשל ברשת):
- שלחו כותרת `Idempotency-Key` ייחודית לכל הזמנה (למשל `order-<order_no>`). קריאה חוזרת עם אותו מפתח תחזיר את המסמך שכבר הופק — בלי כפילות.
- גם `source.order_no` משמש כהגנה: אם כבר הופקה חשבונית לאותו מספר הזמנה, כרטסת תחזיר אותה במקום ליצור חדשה.

**כלל ל‑Claude Code:** כשמפיקים חשבונית להזמנה — תמיד כללו `Idempotency-Key: order-<order_no>` ו‑`source.order_no`.

---

## 6. מסמכים נוספים

- `POST /v1/invoices` — **חשבונית מס (305)**: אותו גוף כמו tax‑receipts אבל **בלי `payment`** (חיוב ללא קבלה).
- `POST /v1/credit-notes` — **חשבונית זיכוי (330)**: כמו חשבונית, עם `original_number` שמפנה למספר החשבונית המקורית.
- `GET /v1/documents/{id}` — פרטי מסמך. `GET /v1/documents/{id}/pdf` — קובץ ה‑PDF (עם אותו מפתח Bearer).

---

## 7. שגיאות

תשובת שגיאה: `{ "detail": { "code": "...", "message": "..." } }`.
- `401` — מפתח חסר/שגוי. `403` — התוכנית אינה כוללת API (נדרש איקומרס). `429` — יותר מדי בקשות.
- `400 invalid_request` — גוף בקשה שגוי (הודעה בעברית עם הסיבה).
טפלו בשגיאות והציגו את `message` למשתמש; אל תנסו שוב ללא `Idempotency-Key`.

---

## 8. הנחיות ל‑Claude Code (חשוב)

- כשהמשתמש מבקש להפיק חשבונית/קבלה, או להמיר הזמנה/מכירה למסמך — השתמש ב‑`POST /v1/tax-receipts` (או `/invoices` אם אין תשלום).
- קרא את מפתח ה‑API מ‑`KARTESET_API_KEY` בלבד. אם חסר — בקש מהמשתמש להגדירו.
- שלח `unit_price` **לפני מע"מ**; אל תחשב מע"מ ידנית.
- תמיד צרף `Idempotency-Key` ו‑`source.order_no` כשמדובר בהזמנה.
- אחרי הצלחה — דווח למשתמש את `number` ו‑`total`, ושמור/הצג את `pdf_url`.
- אל תמציא מספרי מסמך/הקצאה — הם מגיעים מהתשובה בלבד.
- לבדיקות השתמש במפתח `ks_test_…`. עבור לחי (`ks_live_…`) רק כשהמשתמש מאשר.

תיעוד מלא ומעודכן: https://karteset.co.il/developers