API v1

Karteset API למפתחים

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

אימות

כל בקשה נדרשת למפתח 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`	מומלץ	מזהה ייחודי לעסקה (למשל מספר הזמנה). קריאה חוזרת עם אותו מפתח מחזירה את אותה חשבונית — בלי כפילות.

גוף הבקשה

{
  "customer": {
    "name": "רוני כהן",          // חובה
    "tax_id": "312345678",        // ע.מ/ח.פ — אופציונלי
    "is_business": false,          // ברירת מחדל: true אם יש tax_id
    "email": "r@example.com",      // אופציונלי (לשליחת המסמך)
    "phone": "050-0000000",        // אופציונלי
    "address": "הרצל 1, תל אביב",  // אופציונלי
    "country": "IL"                // ברירת מחדל IL; מדינה אחרת = יצוא (מע״מ 0%)
  },
  "items": [
    { "description": "מנוי שנתי", "quantity": 1, "unit_price": 1000, "vat_rate": 18 }
  ],
  "payment": { "method": "credit", "reference": "txn_88213" },  // credit|cash|bank|transfer
  "currency": "ILS",
  "date": "2026-09-03",           // אופציונלי (ברירת מחדל: היום)
  "notes": "תודה על הרכישה"       // אופציונלי
}

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

דוגמה

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": "ILS",
  "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).

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 › שאלה למפתחים ›