API v1

Karteset API למפתחים

יש לכם מערכת סגורה — קופה, ERP או מערכת פנימית — בלי WooCommerce או אתר? חברו אותה ל-Karteset והפיקו חשבונית מס-קבלה אוטומטית בקריאת REST אחת. כרטסת מטפלת במע״מ, במספור ובדיווח — אתם רק שולחים את פרטי העסקה.

🤖

משתמשים ב-Claude Code? חברו בדקה

הורידו את קובץ ההרחבה של כרטסת, העלו אותו ל-Claude Code שלכם (כ-CLAUDE.md או כ-Skill), והוא יידע להפיק חשבוniות וקבלות מול ה-API של כרטסת בשפה חופשית — בלי לכתוב קוד. למשל: "הנפק חשבונית מס-קבלה על הזמנה #1042".

⬇ הורדת קובץ ל-Claude Code

שמרו כ-.claude/skills/karteset/SKILL.md (סקיל) או כ-CLAUDE.md בפרויקט · דורש מפתח API (איקומרס)

אימות

כל בקשה נדרשת למפתח API ב-Authorization: Bearer. מפיקים מפתח ב-המערכת → הגדרות → API (זמין בתוכנית איקומרס). המפתח מוצג פעם אחת — שמרו אותו במקום מאובטח. מפתחות ks_live_… חיים, ks_test_… לבדיקות.

Authorization: Bearer ks_live_xxxxxxxxxxxxxxxxxxxx

Base URL

https://hash.karteset.co.il/api

הפקת חשבונית מס-קבלה

POST /v1/tax-receipts

מפיק חשבונית מס-קבלה (מסמך 320), רושם אותה בספרים, מעדכן את כרטיס הלקוח, ומחזיר קישור ל-PDF.

כותרות

כותרת	חובה	תיאור
`Authorization`	כן	`Bearer <api_key>`
`Idempotency-Key`	מומלץ	מזהה ייחודי לעסקה (למשל מספר הזמנה). קריאה חוזרת עם אותו מפתח מחזירה את אותה חשבונית — בלי כפילות.

גוף הבקשה

{
  "source": {                      // מאיפה הגיעה ההזמנה (אופציונלי, מומלץ)
    "platform": "MyShop",
    "url": "https://myshop.com/orders/5567",
    "order_no": "5567"             // מספר ההזמנה באתר — משמש גם למניעת כפילות
  },
  "customer": {
    "name": "דנה לוי",            // חובה
    "tax_id": "312345678",         // ע.מ/ח.פ — אופציונלי (יש → נחשב עסק)
    "is_business": false,
    "email": "dana@example.com",
    "phone": "03-1112222",
    "mobile": "050-9998888",
    "address": "הרצל 10",          // רחוב
    "city": "תל אביב",
    "zip": "6120101",
    "country": "IL"                // מדינה אחרת = יצוא (מע״מ 0%)
  },
  "items": [
    {
      "description": "חולצה",
      "sku": "SH-RED-L",           // מק"ט — מוצר נוצר/מקושר אוטומטית בקטלוג
      "barcode": "7290000012345",
      "url": "https://myshop.com/p/shirt",   // עמוד המוצר
      "variant": "מידה L · אדום",  // וריאציה — נוסף לתיאור השורה
      "quantity": 2, "unit_price": 80, "vat_rate": 18
    }
  ],
  "shipping": { "amount": 25 },    // עלות משלוח → שורת "דמי משלוח" (אופציונלי)
  "payment": { "method": "credit", "reference": "txn_88213" },  // credit|cash|bank|transfer
  "currency": "ILS",               // ILS | USD | EUR | GBP — שולחים מחירים במטבע הזה (ראו "מטבע זר")
  "date": "2026-09-03",            // תאריך ההזמנה (אסמכתא בלבד) — המסמך תמיד מונפק בתאריך הנוכחי
  "notes": "תודה על הרכישה"
}

💡 מע״מ: אם vat_rate לא נשלח — נגזר אוטומטית: לקוח בישראל 18%, לקוח בחו״ל (יצוא) 0%. שליחת vat_rate מפורש גוברת.

🔎 לקוח/פריט לא קיימים? נוצרים אוטומטית ומקושרים — לקוח לפי ע.מ→מייל→שם, מוצר לפי מק"ט→ברקוד. שום בקשה לא נכשלת כי הם חדשים.
♻️ מניעת כפילות: עדיף לשלוח Idempotency-Key. אם לא — הזמנה עם אותו source.order_no לא תיצור חשבונית כפולה.

דוגמה

curl -X POST https://hash.karteset.co.il/api/v1/tax-receipts \
  -H "Authorization: Bearer ks_live_xxxx" \
  -H "Idempotency-Key: order-10245" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "name": "רוני כהן", "email": "r@example.com", "country": "IL" },
    "items": [ { "description": "מנוי שנתי", "quantity": 1, "unit_price": 1000, "vat_rate": 18 } ],
    "payment": { "method": "credit", "reference": "txn_88213" }
  }'

תשובה — 201 Created

{
  "id": "ad205ee3-…",
  "number": "2026-000451",
  "doc_type": 320,
  "amount_before_vat": 1000.0,
  "vat": 180.0,
  "total": 1180.0,                 // הסכום במטבע המסמך (currency)
  "currency": "ILS",
  "exchange_rate": 1.0,            // שער מול ש״ח (במטבע זר: השער של בנק ישראל ליום ההפקה)
  "total_ils": 1180.0,            // הערך בש״ח שנרשם בספרים (במטבע זר: total × exchange_rate)
  "customer_id": "38b0f062-…",
  "allocation_number": null,
  "pdf_url": "https://hash.karteset.co.il/api/v1/documents/ad205ee3-…/pdf",
  "issued_at": "2026-09-03T13:40:05Z"
}

חשבונית מס (305)

POST /v1/invoices — מפיק חשבונית מס (חיוב ללא קבלה). אותו גוף בקשה כמו tax-receipts, אבל ללא payment (זו לא קבלה).

חשבונית זיכוי (330)

POST /v1/credit-notes — מפיק חשבונית מס זיכוי. הוסיפו original_number כדי לקשר לחשבונית המקורית. ללא payment.

{ "customer": {...}, "items": [ {...} ], "original_number": "2026-000451" }

שליפת מסמך ו-PDF

GET /v1/documents/{id} — מחזיר את פרטי המסמך.
GET /v1/documents/{id}/pdf — מחזיר את קובץ ה-PDF (עם אותו מפתח Bearer).

מטבע זר

שולחים currency (ILS / USD / EUR / GBP) והמחירים ב-items באותו מטבע — בלי לשלוח שקלים ובלי לשלוח שער חליפין. כרטסת מטפלת בהמרה לבד:

שאלה	תשובה
מקבל מטבע זר בלי שגיאה?	✅ כן — ILS/USD/EUR/GBP (שער בנק ישראל, מתעדכן יומית). מטבע לא-נתמך מחזיר `400 invalid_request` נקי, לא קריסה.
המסמך מציג שווי בש״ח + שער?	✅ כן — ה-PDF מציג את הסכום במטבע המקורי, ובנוסף "שער חליפין" ו"שווי בש״ח" (דרישה חוקית לחשבונית ישראלית).
צריך לשלוח סכום בש״ח / exchange_rate?	❌ לא — שולחים רק מטבע + סכומים. השער נמשך אוטומטית מבנק ישראל לפי יום ההפקה.

בתשובה מקבלים גם את המטבע המקורי וגם את הערך בש״ח:

# בקשה — רק מטבע וסכומים
{ "currency": "USD",
  "customer": { "name": "John Smith", "country": "US" },
  "items": [ { "description": "Consulting", "quantity": 1, "unit_price": 100 } ] }

# תשובה
{ "total": 100.0, "currency": "USD",
  "exchange_rate": 3.7210,     # שער בנק ישראל ליום ההפקה
  "total_ils": 372.10,         # הערך שנרשם בספרים (בש״ח)
  ... }

🧾 הספרים תמיד בש״ח: ההמרה נעשית לפי שער בנק ישראל של יום ההפקה (לא יום ההזמנה). לקוח בחו״ל (country ≠ IL) → מע״מ 0% (יצוא) אוטומטית.

Webhooks

קבלו התראה בזמן אמת. מגדירים כתובת ב-הגדרות → API → Webhooks ובוחרים אירועים. כרטסת שולחת POST עם גוף { "event": "...", "data": {...} } וחתימה.

אירועים

event	מתי
`document.issued`	מסמך הופק (גם דרך ה-API וגם במערכת)
`document.canceled`	מסמך בוטל

אימות חתימה

כל בקשה כוללת כותרת X-Karteset-Signature = hex HMAC-SHA256 של גוף הבקשה עם ה-secret שקיבלתם ביצירת ה-webhook. אמתו כדי לוודא שהבקשה הגיעה מכרטסת:

# Python
import hmac, hashlib
expected = hmac.new(secret.encode(), request_body_bytes, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(expected, request.headers["X-Karteset-Signature"])

🔁 מסירה נכשלת (לא 2xx) נכנסת לתור ניסיונות חוזרים עם backoff (עד 6 ניסיונות). החזירו 200 כדי לאשר קבלה.

שגיאות

קוד	code	מתי
401	`unauthorized`	מפתח חסר/לא תקין
403	`plan_required`	התוכנית אינה איקומרס
422	`allocation_required`	חשבונית מעל הסף לעוסק מורשה מחייבת מספר הקצאה (ראו למטה)
429	`rate_limited`	חריגה ממגבלת הקצב (120 בקשות/דקה)
400	`invalid_request`	נתונים חסרים/שגויים, או מטבע לא-נתמך שאין לו שער חליפין

מגבלת מספר הקצאה

⚠️ חשבונית מס-קבלה מעל סף רשות המסים ללקוח עוסק מורשה מחייבת מספר הקצאה. כרגע ה-API מחזיר שגיאה allocation_required במקרה זה — יש להפיק מסמך כזה במערכת ידנית. בקרוב: משיכת מספר ההקצאה אוטומטית בזמן ההפקה (חיבור שע"ם), שקוף לכם. לקוחות פרטיים וסכומים מתחת לסף — עוברים חלק.

להפקת מפתח API › שאלה למפתחים ›