Makor API#

הפקת מסמכים עסקיים ישראליים חוקיים דרך HTTP: חשבוניות מס עם מספר הקצאה בזמן אמת מרשות המסים, קבלות עם ניכוי מס במקור, חשבוניות זיכוי, קבצי PDF חתומים דיגיטלית, וייצוא מבנה אחיד. את הכול אפשר לבדוק בסביבת ניסוי מבודדת לחלוטין לפני מעבר לייצור.

כתובת בסיס (ייצור)https://makor.all-good.co.il/api/v1
כתובת בסיס (ניסוי)https://sandbox.makor.all-good.co.il/api/v1
סוג תוכןapplication/json; charset=utf-8
אימותAuthorization: Bearer mk_live_… / mk_test_…
שגיאותapplication/problem+json (RFC 9457)
סכמה/api/openapi.json · /api/docs

הפקת חשבונית בקריאה אחת

צרו מפתח API בהגדרות → API ושלחו מסמך. עם ?issue=true נוצרת הטיוטה, מוקצה לה מספר, מתבצעת פנייה לרשות המסים כשנדרש, והמסמך מרונדר, נחתם ומופק — הכול בבקשה אחת.

curl
# Sandbox host + sandbox key. Swap both together to go live.
curl -X POST 'https://sandbox.makor.all-good.co.il/api/v1/businesses/{business_id}/documents?issue=true' \
  -H 'Authorization: Bearer mk_test_1a2b3c4d5e6f...' \
  -H 'Idempotency-Key: invoice-2026-0001' \
  -H 'Content-Type: application/json' \
  -d '{
    "doc_type": 305,
    "issue_date": "2026-08-07",
    "customer_name": "לקוח לדוגמה",
    "customer_tax_id": "123456782",
    "lines": [
      { "description": "ייעוץ טכנולוגי", "quantity": 1, "unit_price_agorot": 600000 }
    ]
  }'
201 Created
HTTP/1.1 201 Created

{
  "id": "019fdad4-b4bb-70ce-94fd-8164faf6f426",
  "doc_type": 305,
  "doc_type_name_he": "חשבונית מס",
  "doc_type_name_en": "Tax Invoice",
  "series": "A",
  "doc_number": 1,
  "status": "issued",
  "issue_date": "2026-08-07",
  "customer_name": "לקוח לדוגמה",
  "customer_tax_id": "123456782",
  "subtotal": 600000,
  "discount_total": 0,
  "taxable_amount": 600000,
  "vat_rate_bp": 1800,
  "vat_amount": 108000,
  "total": 708000,
  "withholding_amount": 0,
  "allocation_status": "approved",
  "allocation_number": "20260807123456782000000001",
  "is_sandbox": true,
  "language": "he",
  "parent_id": null,
  "open_balance": null
}
Node.js
const KEY = process.env.MAKOR_API_KEY;        // mk_live_… or mk_test_…
const BUSINESS = process.env.MAKOR_BUSINESS_ID;

// The key prefix and the base URL must always agree.
const BASE_URL = KEY.startsWith("mk_test_")
  ? "https://sandbox.makor.all-good.co.il/api/v1"
  : "https://makor.all-good.co.il/api/v1";

const res = await fetch(
  `${BASE_URL}/businesses/${BUSINESS}/documents?issue=true`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      doc_type: 320,
      issue_date: new Date().toISOString().slice(0, 10),
      customer_name: "לקוח לדוגמה",
      lines: [{ description: "מנוי חודשי", quantity: 1, unit_price_agorot: 19900 }],
      payments: [{ method: "card", amount_agorot: 23482, card_brand: "Visa" }],
    }),
  }
);

if (res.status === 202) {
  const held = await res.json();
  console.log(held.rejection_code, held.decisions);
} else if (!res.ok) {
  const problem = await res.json();
  throw new Error(`${problem.code}: ${problem.detail}`);
}
Python
import os, uuid, httpx

KEY = os.environ["MAKOR_API_KEY"]
BUSINESS = os.environ["MAKOR_BUSINESS_ID"]

# The key prefix and the base URL must always agree.
BASE_URL = (
    "https://sandbox.makor.all-good.co.il/api/v1" if KEY.startswith("mk_test_") else "https://makor.all-good.co.il/api/v1"
)

with httpx.Client(
    base_url=BASE_URL,
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
) as client:
    r = client.post(
        f"/businesses/{BUSINESS}/documents",
        params={"issue": True},
        headers={"Idempotency-Key": str(uuid.uuid4())},
        json={
            "doc_type": 305,
            "issue_date": "2026-08-07",
            "customer_tax_id": "123456782",
            "customer_name": "לקוח לדוגמה",
            "lines": [
                {"description": "ייעוץ", "quantity": 1, "unit_price_agorot": 600000}
            ],
        },
    )

    if r.status_code == 202:
        held = r.json()
        client.post(
            f"/businesses/{BUSINESS}/documents/{held['id']}/allocation-decision",
            json={"choice": "continue"},
        )
    else:
        r.raise_for_status()

אימות#

מקור משתמשת במפתחות API אטומים כטוקן נשיאה (Bearer). אין שלב החלפת טוקן ואין מה לרענן — המפתח שיצרתם הוא בדיוק מה שנשלח בכל בקשה.

header
Authorization: Bearer mk_live_9f8e7d6c5b4a3928170615243342516071829304
קידומתסביבההתנהגות
mk_live_ייצורתקף רק מול https://makor.all-good.co.il/api/v1. יוצר מסמכים אמיתיים: צורך מהמספור החוקי, פונה לרשות המסים, ומופיע בדוחות ובמבנה האחיד.
mk_test_סביבת ניסויתקף רק מול https://sandbox.makor.all-good.co.il/api/v1. יוצר מסמכי ניסוי בלבד — ראו סביבת ניסוי.
המפתח מוצג פעם אחת בלבד
המפתח המלא מוחזר רק בתשובה שיוצרת אותו; מקור שומרת ממנו רק תקציר SHA-256. להחלפת מפתח: צרו חדש ובטלו את הישן — הביטול נכנס לתוקף מיידית (בקשות נוספות יקבלו 401).

מצבי כשל

401 Unauthorized
FLOW-401
מפתח חסר, פגום, לא מוכר או מבוטל.
404 Not Found
FLOW-404
המפתח תקין אך שייך לעסק אחר מזה שב-{business_id} שבנתיב. גישה לעסק זר מדווחת כ”לא נמצא” ולא כ”אסור”, כדי שמחזיקי מפתחות לא יוכלו לגלות אילו עסקים קיימים.
403 Forbidden
FLOW-403
האימות הצליח, אך למפתח חסרה ההרשאה שה-endpoint דורש.

הרשאות (Scopes)#

כל endpoint מצהיר על הרשאה אחת בדיוק. מפתח מקבל את ההרשאות המינימליות שביקשתם; אם לא ציינתם הרשאות, הוא מקבל את המקסימום שתפקידכם מתיר.

הרשאהמה היא מתירה
documents:readצפייה ברשימת מסמכים, קריאת מסמך והורדת PDF
documents:writeיצירה, הפקה, ביטול, מחיקת טיוטות, החלטות הקצאה וקישורי שיתוף
customers:readצפייה בלקוחות ובהסכמתם למשלוח מסמכים
customers:writeיצירה, עדכון והשבתה של לקוחות; רישום הסכמה
items:readצפייה בקטלוג הפריטים
items:writeיצירה, עדכון והשבתה של פריטים
reports:readדוחות הכנסות, מע"מ וניכוי במקור
export:readהפקה והורדה של קבצי מבנה אחיד
מפתחות של רואה חשבון מוגבלים בצד השרת
מפתח שנוצר בידי משתמש שתפקידו accountant מצומצם להרשאות קריאה בלבד, ללא קשר למה שהבקשה ביקשה. התשובה מחזירה את ההרשאות שניתנו בפועל — קראו אותן ואל תניחו.

סביבת ניסוי#

התנסות בלי להפיק אף פעם חשבונית אמיתית. לסביבת הניסוי יש כתובת API נפרדת ומפתחות נפרדים, כך שאי אפשר לבלבל בין השתיים — אבל היא עדיין החשבון והנתונים שלכם, בלי הרשמה נוספת.

סביבהכתובת בסיסמפתח
ייצורhttps://makor.all-good.co.il/api/v1mk_live_…
ניסויhttps://sandbox.makor.all-good.co.il/api/v1mk_test_…
הכתובת והמפתח חייבים להתאים
מפתח mk_test_ מול כתובת הייצור נדחה ב-403, וכך גם מפתח mk_live_ מול כתובת הניסוי — עם הודעה שמפנה לכתובת הנכונה. זו הסיבה שאי אפשר להפיק חשבונית אמיתית בטעות בזמן פיתוח: צריך לטעות בשני מקומות בו-זמנית.
דרך ה-API

צרו מפתח עם "sandbox": true וקראו לכתובת הניסוי. כל קריאה פועלת על נתוני ניסוי — בלי פרמטרים נוספים.

דרך האפליקציה

הגדרות → סביבת ניסוי → כניסה למצב ניסוי. באנר כתום מסמן את הסשן וכל מה שתיצרו הוא מסמך ניסוי.

מה הבידוד אומר בפועל

מספור נפרד
מובטח
מסמכי ניסוי שואבים מסדרת מספור משלהם לכל סוג מסמך. המספור החוקי והרציף שלכם לעולם לא מתקדם בגלל ניסוי.
אין תעבורה לרשות המסים
מובטח
בקשות הקצאה למסמכי ניסוי נענות בסימולטור דטרמיניסטי ולעולם לא נשלחות לרשות — גם בסביבת ייצור.
מחוץ לספרים
מובטח
מסמכי ניסוי לא מופיעים בדוחות הכנסות, מע"מ וניכוי במקור, ולא בייצוא המבנה האחיד.
מסומן בבירור
מובטח
כל PDF של ניסוי נושא חותמת אלכסונית "SANDBOX — אינו מסמך חשבונאי", וה-API מחזיר is_sandbox: true.
עיוורון דו-כיווני
מובטח
מפתח ייצור מקבל 404 על מסמך ניסוי ולהפך; קריאות רשימה מחזירות תמיד סביבה אחת בלבד.

טריגרים דטרמיניסטיים להקצאה

כדי לתרגל כל תוצאה אפשרית מרשות המסים לפי דרישה, סביבת הניסוי בוחרת את התשובה לפי שתי ספרות האגורות האחרונות של הסכום לפני מע"מ. כך אפשר לבנות ולבדוק את זרימת הדחייה בלי לחכות לסירוב אמיתי.

הסכום מסתיים בהתוצאה המדומהHTTP
…60מעוכב לבדיקה, קוד 460 — זרימת ארבע ההחלטות202
…61קיימת חשבונית לא מאושרת שממתינה להחלטה, קוד 461202
…03תקלה טכנית — המסמך מופק עם failed_retro_pending201
כל סכום אחראושר, עם מספר הקצאה מדומה בן 26 ספרות201
לדוגמה: unit_price_agorot: 600060 (₪6,000.60) מפעיל עיכוב בקוד 460, בעוד 600000 יאושר.

מוסכמות#

כמה כללים תקפים בכל ה-API. הבנה שלהם מראש חוסכת את רוב ההפתעות באינטגרציה.

כסף
מספר שלם באגורות
כל הסכומים הם מספרים שלמים באגורות (1/100 ₪). ₪1,180.00 הם 118000. אל תשלחו מספרים עשרוניים ואל תשלחו סכום מע"מ — המע"מ מחושב בשרת.
מע"מ
מחושב בשרת
מחושב לפי השיעור החוקי בתוקף בתאריך issue_date (18% מ-1.1.2025), פעם אחת לכל קבוצת שיעור ברמת המסמך עם עיגול half-up — במכוון לא פר שורה, כדי למנוע סחף אגורות. עוסק פטור ומלכ"ר מקבלים אפס.
תאריכים
YYYY-MM-DD
תאריכי לוח בלבד, ללא אזור זמן. חותמות זמן בתשובות הן ISO-8601 ב-UTC; המספור ותקופות הדיווח לפי שעון ישראל.
מזהים
UUIDv7
מזהים ממויינים לפי זמן, כך שסדר לקסיקוגרפי שווה לסדר יצירה — זה מה שמאפשר עימוד יציב בקורסור.
מספרי זיהוי
מחרוזת, 9 ספרות
ח.פ / מספר עוסק / ת.ז — בדיוק תשע ספרות כולל ספרת ביקורת, שנבדקת ביצירת העסק (FLOW-BIZ-002).
טקסט בעברית
UTF-8
שלחו עברית כמות שהיא ב-JSON. הרינדור מטפל בכיווניות, וייצוא המבנה האחיד ממיר ל-ISO-8859-8 כפי שהתקן מחייב.

שגיאות#

השגיאות תואמות ל-RFC 9457 בפורמט application/problem+json. הסתמכו על שדה code היציב ולא על הטקסט החופשי. כל שגיאה כוללת detail באנגלית ו-detail_he בעברית שניתן להציג ישירות למשתמש הקצה.

problem+json
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://makor.all-good.co.il/dev#errors",
  "title": "Payment lines (5000) must sum to document total (11800)",
  "status": 422,
  "code": "FLOW-DOC-011",
  "detail": "Payment lines (5000) must sum to document total (11800)",
  "detail_he": "סכום אמצעי התשלום חייב להיות שווה לסכום המסמך (כולל שורת ניכוי במקור)"
}
סטטוסמשמעות
400 / 422הפרת ולידציה או כלל עסקי — ראו אינדקס הקודים למטה
401האימות נכשל (מפתח חסר, לא מוכר או מבוטל)
403מאומת אך חסרה ההרשאה הנדרשת, או תפקיד לקריאה בלבד
404המשאב לא קיים, או שייך לעסק או לסביבה אחרת
409התנגשות מצב — למשל הפקת מסמך שכבר אינו טיוטה
202לא שגיאה: החשבונית עוכבה ברשות המסים וממתינה להחלטתכם
ולידציה ברמת השדה שמבוצעת בשכבת הסכמה (טיפוסים, תבניות, אורכים) מחזירה 422 תקני של הפריימוורק עם מערך detail, ללא קוד FLOW-*. כללים עסקיים תמיד מחזירים FLOW-*.

אידמפוטנטיות#

יצירת מסמך היא הקריאה האחת שאסור לחזור עליה בטעות — כפילות תצרוך מספר מסמך חוקי שאי אפשר להשתמש בו שוב.

Idempotency-Key
כותרת, מחרוזתרשות
שלחו ערך ייחודי (UUID עובד מצוין) ב-POST /documents. ניסיון חוזר עם אותו מפתח יחזיר את התשובה המקורית — אותו מסמך, אותו מספר — במקום ליצור מסמך שני. המפתחות נשמרים 48 שעות.
מצבתוצאה
אותו מפתח, אותו גוף בקשה, הושלםהתשובה המקורית מוחזרת כמות שהיא
אותו מפתח, גוף בקשה שונה422 FLOW-IDEM-001 — מפתח יכול לתאר בקשה אחת בלבד
אותו מפתח בזמן שהבקשה הראשונה עדיין רצה409 FLOW-IDEM-002 — נסו שוב בעוד רגע
בלי מפתח אידמפוטנטיות, timeout ברשת משאיר אתכם בלי דרך לדעת אם החשבונית הופקה. בייצור — תמיד שלחו מפתח.

עימוד#

קריאות רשימה שיכולות לגדול ללא גבול משתמשות בעימוד מבוסס קורסור, שנשאר נכון גם בזמן שמופקים מסמכים חדשים.

response
{
  "items": [ /* … */ ],
  "next_cursor": "019fdad4-b4bb-70ce-94fd-8164faf6f426"
}
limit
מספר שלם= 50
גודל עמוד, מקסימום 200.
cursor
מחרוזת (uuid)רשות
העבירו את next_cursor מהתשובה הקודמת כדי לקבל את העמוד הבא. התוצאות מסודרות מהחדש לישן; null אומר שהגעתם לסוף. קורסור לא תקין מחזיר 422 FLOW-PAGE-001.
לקוחות ופריטים משתמשים בחיפוש פשוט עם limit ו-q במקום קורסור — אלה אוספים קטנים שמנוהלים ידנית.

מספרי הקצאה#

במסגרת רפורמת חשבוניות ישראל, חשבונית מס מעל הסף הקבוע בחוק חייבת לשאת מספר הקצאה שמתקבל מרשות המסים בזמן אמת. בלעדיו הקונה אינו יכול לנכות מס תשומות, ומאוגוסט 2025 ההוצאה גם אינה מוכרת לצורכי מס הכנסה. מקור מבצעת את ההליך הזה בתוך קריאת ההפקה.

מתי זה חל

סוג המסמך
305 / 320
חשבונית מס וחשבונית מס/קבלה בלבד. חשבוניות זיכוי ומסמכים ללא מע"מ לעולם אינם עוברים אישור.
הסכום
≥ הסף
הסכום לפני מע"מ שווה או גבוה מהסף שבתוקף בתאריך ההפקה — ₪5,000 מ-1.6.2026 (₪10,000 מ-1.1.2026, ₪20,000 מ-1.1.2025, ₪25,000 מ-5.5.2024).
הצד שכנגד
עסק לעסק
לקוח עסקי: customer_tax_id הופך לחובה מעל הסף (FLOW-DOC-040).

תוצאות אפשריות

HTTPallocation_statusמה קרה
201approvedאושר. allocation_number מכיל את מספר האישור המלא בן 26 הספרות; ב-PDF מודפסות תשע הספרות הימניות תחת ”מספר הקצאה“.
201not_requiredמתחת לסף, לקוח פרטי, או סוג מסמך שאינו בגדר החובה.
201failed_retro_pendingרשות המסים לא הייתה זמינה. התקנות מתירות להפיק בכל זאת; מקור מבקשת הקצאה רטרואקטיבית שוב ושוב (מותר עד שנה).
202rejectedעוכב לבדיקה (קוד 460 או 461). למסמך הוקצה מספר אך הוא לא הופק — הוא נשאר pending עד שתבחרו מסלול.
202 Accepted
HTTP/1.1 202 Accepted

{
  "id": "019fdad4-...",
  "status": "pending",
  "doc_number": 42,
  "allocation_status": "rejected",
  "allocation_decision_required": true,
  "rejection_code": 460,
  "rejection_message": "Data is correct but invoice was not approved",
  "decisions": ["cancel", "continue", "reverse_charge", "object"]
}

טיפול בחשבונית מעוכבת

ארבע האפשרויות הבאות הן החלופות הקבועות בחוק. חובה לבחור אחת — המסמך לא יכול להישאר תלוי באוויר — וההחלטה מדווחת בחזרה לרשות.

choiceמה קורההמשמעות
cancelהמסמך עובר לסטטוס מבוטלהמספר נשמר כמסמך מבוטל — לא ממוחזר לעולם, כך שהסדרה נשארת רציפה.
continueמופק ללא מספר הקצאהב-PDF מודפס הכיתוב המחייב "אין לנכות מס תשומות בגין חשבונית זו" — הלקוח לא יוכל לנכות מס תשומות.
reverse_chargeנשלח מחדש כהיפוך חיובחשבונית עצמית בשיעור מע"מ אפס: הלקוח מדווח על העסקה. מקבלת מספר הקצאה משלה.
objectמוגשת השגה רשמיתהמסמך נשאר pending עם allocation_status: objection עד להכרעת הרשות.
curl
curl -X POST 'https://makor.all-good.co.il/api/v1/businesses/{business_id}/documents/{document_id}/allocation-decision' \
  -H 'Authorization: Bearer mk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ "choice": "continue" }'
למה חשבונית שנדחתה שומרת על מספרה
המספר מוקצה לפני הפנייה לרשות, מפני שבקשת האישור חייבת לכלול את מספר החשבונית. לפי הוראות ניהול ספרים מסמך מבוטל נשאר בסדרה ואינו משחרר את מספרו — וזה בדיוק מה ששומר על הרצף ועל יכולת הביקורת.

אובייקט המסמך#

מוחזר מכל קריאה שקשורה למסמכים. הסכומים באגורות; שדות כספיים תמיד קיימים, גם כשערכם אפס.

id
string (uuid)חובה
מזהה קבוע.
doc_type
integerחובה
קוד סוג המסמך — ראו סוגי מסמכים. אלה בדיוק הקודים של תקן המבנה האחיד.
doc_type_name_he / _en
stringחובה
שם סוג המסמך לתצוגה, מוכן להדפסה.
series
stringחובה
סדרת מספור, ברירת מחדל "A".
doc_number
integer | nullחובה
מוקצה בהפקה ולא ניתן לשינוי אחריה; null כל עוד המסמך טיוטה.
status
stringחובה
draft · pending · issued · cancelled.
customer_id / customer_name / customer_tax_id
string | nullחובה
תצלום של פרטי הלקוח שהוקפא בהפקה — עריכה מאוחרת של כרטיס הלקוח לא משנה מסמך שהופק.
issue_date / due_date
date | nullחובה
תאריכי לוח.
subtotal
integerחובה
סכום שורות המסמך לפני הנחת מסמך, ללא מע"מ.
discount_total
integerחובה
הנחה ברמת המסמך.
taxable_amount
integerחובה
בסיס המע"מ אחרי חלוקת ההנחה — זה הסכום שנבדק מול סף ההקצאה.
vat_rate_bp
integerחובה
שיעור בנקודות בסיס; 1800 = 18%. אפס כשהמסמך אינו נושא מע"מ.
vat_amount
integerחובה
המע"מ המחושב.
total
integerחובה
סה"כ כולל מע"מ.
withholding_amount
integerחובה
סכום שורות התשלום מסוג ניכוי מס במקור.
allocation_status
stringחובה
ראו סטטוסי הקצאה.
allocation_number
string | nullחובה
מספר האישור המלא בן 26 ספרות. מדפיסים את תשע הספרות האחרונות.
language
stringחובה
he או en — קובע את שפת רינדור המסמך.
parent_id
string | nullחובה
בחשבונית זיכוי: החשבונית המזוכה.
is_sandbox
booleanרשות
true עבור מסמכי ניסוי.
open_balance
integer | nullרשות
רק בקריאת מסמך בודד של חשבונית או חשבונית עסקה שהופקה: סה"כ פחות כל מה שכבר נסגר בקבלות ובזיכויים.
lines[] / payments[]
arrayרשות
נכללים רק בקריאת מסמך בודד, לא ברשימות.

ערכים אפשריים#

אוצר מילים קבוע שחוזר בכל ה-API.

סוגי מסמכים

קודשםEnglishהערות
10הצעת מחירQuoteללא השפעה חשבונאית
100הזמנהOrderללא השפעה חשבונאית
200תעודת משלוחDelivery note
300חשבונית עסקהProformaדרישת תשלום שאינה יוצרת אירוע מע"מ — הדפוס של בסיס מזומן
305חשבונית מסTax invoiceמספר הקצאה מעל הסף
320חשבונית מס/קבלהInvoice-receiptמחייבת תשלומים; ההקצאה חלה
330חשבונית זיכויCredit noteמחייבת parent_id; לעולם ללא הקצאה
400קבלהReceiptמחייבת תשלומים; סוגרת חשבוניות דרך linked_invoices
405קבלה על תרומהDonation receiptעמותות בלבד, סדרה נפרדת
סוג הישות קובע אילו קודים מותר להפיק
עוסק פטור — 10, 100, 200, 300, 400 בלבד; אינו רשאי להפיק חשבונית מס כלל (FLOW-DOC-001).
עוסק מורשה / חברה / שותפות — הכול חוץ מ-405.
עמותה — 10, 300, 400, 405 בלבד; ללא מע"מ.

סטטוס מסמך

ערךמשמעות
draftניתן לעריכה, ללא מספר, ללא תוקף משפטי
pendingממוספר ומוקפא; ממתין לאישור או להחלטה
issuedסופי ובלתי ניתן לשינוי
cancelledבוטל; המספר נשמר בסדרה

סטטוס הקצאה

ערךמשמעות
not_requiredמחוץ לחובת ההקצאה
pendingהבקשה בדרך
approvedאושר, המספר נשמר
rejectedמעוכב — נדרשת החלטה
rejected_continueהופק ללא אישור, עם הכיתוב המשפטי
reverse_chargeהופק כהיפוך חיוב
objectionהוגשה השגה, ממתין להכרעה
failed_retro_pendingתקלה טכנית; ניסיון רטרואקטיבי בתור

אמצעי תשלום

ערךשדות נוספים
cash
chequeמחייב cheque_number; מומלץ גם bank_code, branch, account, paid_date
cardcard_brand, card_last4, installments
bank_transfertransfer_ref
appביט, פייבוקס וכדומה
withholdingניכוי מס במקור — לא כסף שהתקבל, אך מסלק את החוב ונספר בסכום
other

טיפול מע"מ

ערךמשמעות
standardחייב מע"מ בשיעור מלא (18%)
exemptעסקה פטורה — מחוץ לבסיס המע"מ
zeroמע"מ בשיעור אפס, למשל יצוא

סוגי ישות

ערךבעברית
osek_paturעוסק פטור
osek_mursheעוסק מורשה
companyחברה בע"מ
partnershipשותפות
amutaעמותה / מלכ"ר

מסמכים#

ליבת ה-API. כל הנתיבים יחסיים לכתובת הבסיס ומשויכים לעסק.

POST/businesses/{business_id}/documentsdocuments:write

יוצר טיוטה, ועם ?issue=true מריץ את מלוא צינור ההפקה: ולידציה → הקצאת מספר רציף → אישור מול רשות המסים → רינדור PDF וחתימה דיגיטלית. מחזיר 201, או 202 כשהרשות מעכבת את החשבונית.

פרמטרים וכותרות

issue
boolean= false
להפיק מיד במקום להשאיר טיוטה.
sandbox
boolean= false
יצירת מסמך ניסוי. מתעלמים ממנו במפתחות API — הסביבה של המפתח תמיד גוברת.
Idempotency-Key
כותרתרשות
מומלץ בחום בכל פעם שמשתמשים ב-issue=true.

גוף הבקשה

doc_type
integerחובה
אחד מקודי סוגי המסמכים.
issue_date
dateחובה
קובע את שיעור המע"מ ואת סף ההקצאה שיחולו.
customer_id
string (uuid)רשות
לקוח קיים; השם, מספר הזיהוי והכתובת מועתקים למסמך בהפקה.
customer_name
stringרשות
לקוח חד-פעמי, או דריסה של השם השמור.
customer_tax_id
string (9 ספרות)רשות
חובה מעל סף ההקצאה (FLOW-DOC-040).
lines[]
arrayרשות
description (חובה, ≤500), quantity (חובה, > 0), unit_price_agorot (חובה, ≥ 0), unit, discount_agorot, vat_treatment, item_id. נדרש לכל סוג מסמך חוץ מקבלות טהורות.
payments[]
arrayרשות
method ו-amount_agorot חובה. נדרש עבור 320, 400 ו-405, וסכומם חייב להיות שווה בדיוק לסכום המסמך (FLOW-DOC-011).
linked_invoices[]
arrayרשות
{ invoice_id, amount_agorot } — החשבוניות שהקבלה סוגרת, במלואן או בחלקן. נבדק מול היתרה הפתוחה של כל חשבונית תחת נעילת שורה, כך שקבלות מקבילות לא יכולות לסגור יתר.
parent_id
string (uuid)רשות
חובה בחשבונית זיכוי (330): החשבונית המזוכה.
document_discount_agorot
integer= 0
הנחה על כלל המסמך, מחולקת יחסית על בסיס המע"מ.
due_date
dateרשות
תאריך לתשלום שיודפס על המסמך.
language
string= "he"
he או en — בוחר את שפת רינדור ה-PDF.
series
string= "A"
סדרת מספור חלופית (למשל לפי סניף). כל סדרה רציפה בפני עצמה.
notes / footer_text
stringרשות
טקסט חופשי שיודפס על המסמך.
קבלה שסוגרת חשבונית, עם ניכוי במקור
{
  "doc_type": 400,
  "issue_date": "2026-08-07",
  "customer_id": "019fda...",
  "payments": [
    { "method": "bank_transfer", "amount_agorot": 112100, "paid_date": "2026-08-07" },
    { "method": "withholding",   "amount_agorot": 5900 }
  ],
  "linked_invoices": [
    { "invoice_id": "019fdac1-...", "amount_agorot": 118000 }
  ]
}
למה שורות התשלום חייבות להסתכם בסה"כ
ניכוי מס במקור אינו כסף שקיבלתם, אבל הוא כן מסלק את החוב. רישומו כשורת תשלום מסוג withholding הוא מה שמאזן את הקבלה — בדוגמה למעלה ₪1,121.00 הגיעו בהעברה ו-₪59.00 נוכו במקור, ויחד הם סוגרים חשבונית של ₪1,180.00.
POST/businesses/{business_id}/documents/{document_id}/issuedocuments:write

מפיק טיוטה קיימת — אותו צינור ואותה סמנטיקה של 201/202 כמו יצירה עם ?issue=true. הפקה של מסמך שאינו טיוטה מחזירה 409 FLOW-DOC-060, וכך גם נראית בקשה כפולה.

POST/businesses/{business_id}/documents/{document_id}/allocation-decisiondocuments:write
choice
stringחובה
אחד מ-cancel, continue, reverse_charge, object.
reason
string ≤500רשות
נשמר על המסמך בעת ביטול.

תקף רק כשהמסמך pending וסטטוס ההקצאה שלו rejected או objection; אחרת 409 FLOW-ALLOC-001. אם גם בקשת היפוך החיוב נדחית תקבלו 409 FLOW-ALLOC-002.

GET/businesses/{business_id}/documentsdocuments:read

פרמטרים וכותרות

doc_type
integerרשות
סינון לפי קוד סוג.
status
stringרשות
draft · pending · issued · cancelled.
from_date / to_date
dateרשות
סינון לפי issue_date, כולל.
limit
integer= 50
מקסימום 200.
cursor
stringרשות
מתוך next_cursor הקודם.
sandbox
boolean= false
קריאות עם סשן מחליפות סביבה; מפתחות API נעולים לסביבה שלהם.

מחזיר { items, next_cursor }, מהחדש לישן. פריטי הרשימה אינם כוללים lines, payments ו-open_balance — לשם כך קראו מסמך בודד.

GET/businesses/{business_id}/documents/{document_id}documents:read

המסמך המלא, כולל lines[], payments[] ו — בחשבוניות ובחשבוניות עסקה שהופקו — open_balance.

POST/businesses/{business_id}/documents/{document_id}/canceldocuments:write
reason
string ≤500רשות
נרשם על המסמך וביומן הביקורת.
המספר נשמר — ביטול לעולם לא משחרר אותו לשימוש חוזר. מסמך שכבר מקושרות אליו קבלות או זיכויים אינו ניתן לביטול כלל (409 FLOW-DOC-064); יש להפיק חשבונית זיכוי במקום. אם המקור כבר הגיע ללקוח, חשבונית זיכוי היא ממילא הכלי הנכון מבחינה משפטית.
DELETE/businesses/{business_id}/documents/{document_id}documents:write

מוחק טיוטה. כל מסמך שכבר ממוספר מחזיר 409 FLOW-DOC-065 — מסמכים שהופקו הם בלתי ניתנים לשינוי ומבוטלים או מזוכים, לעולם לא נמחקים.

GET/businesses/{business_id}/documents/{document_id}/pdfdocuments:read

מחזיר application/pdf. הקריאה הראשונה מרנדרת וחותמת דיגיטלית את המקור ושומרת אותו; כל קריאה נוספת מחזירה בדיוק את אותם בייטים, מפני שהקובץ החתום הוא המקור המשפטי. הוסיפו ?copy=true לרינדור העתק. לטיוטה אין PDF (409 FLOW-PDF-001).

POST/businesses/{business_id}/documents/{document_id}/sharedocuments:write

יוצר — או מחזיר את הקיים — קישור ציבורי ללקוח: { token, url }. הדף נמצא בכתובת /d/{token}, אינו דורש התחברות, מוגש עם noindex, ומציע את ה-PDF בכתובת /d/{token}/pdf. ניתן לשתף רק מסמכים שהופקו או בוטלו (409 FLOW-SHARE-001).

לקוחות#

GET/businesses/{business_id}/customerscustomers:read

פרמטרים וכותרות

q
stringרשות
חיפוש חופשי בשם, במספר הזיהוי ובאימייל.
limit
integer= 50
מקסימום 200.
POST/businesses/{business_id}/customerscustomers:write
name
string ≤200חובה
שם לתצוגה.
tax_id
string (9 ספרות)רשות
יידרש בהמשך אם תפיקו ללקוח חשבונית מעל סף ההקצאה.
email / phone
stringרשות
משמשים למשלוח מסמכים.
address_street / _house / _city / _zip
stringרשות
מודפסים על המסמכים.
country_code
string (2)= "IL"
ISO 3166-1 alpha-2.
withholding_rate_bp
integer 0–5000= 0
שיעור ניכוי במקור ברירת מחדל בנקודות בסיס (500 = 5%), למילוי מראש בקבלות.
notes
string ≤1000רשות
הערה פנימית.
GET/businesses/{business_id}/customers/{customer_id}customers:read
PATCH/businesses/{business_id}/customers/{customer_id}customers:write

עדכון חלקי. עריכת לקוח לעולם אינה משנה מסמכים שכבר הופקו עבורו — הם נושאים תצלום מוקפא.

DELETE/businesses/{business_id}/customers/{customer_id}customers:write

מחיקה רכה (השבתה). ההיסטוריה נשמרת לתקופת השמירה הקבועה בחוק.

פריטים#

קטלוג אופציונלי למילוי מהיר של שורות מסמך.

GET/businesses/{business_id}/itemsitems:read

פרמטרים וכותרות

q
stringרשות
חיפוש לפי שם.
limit
integer= 100
מקסימום 500.
POST/businesses/{business_id}/itemsitems:write
name
string ≤200חובה
שם הפריט.
name_en
stringרשות
משמש במסמכים באנגלית.
sku
string ≤20רשות
מק"ט פנימי.
unit
string= "יחידה"
יחידת מידה.
unit_price_agorot
integer= 0
מחיר ברירת מחדל.
vat_treatment
string= "standard"
standard · exempt · zero.
description
string ≤500רשות
תיאור מורחב.
PATCH/businesses/{business_id}/items/{item_id}items:write
DELETE/businesses/{business_id}/items/{item_id}items:write

מספור#

סדרות מספור הן לפי עסק, סוג מסמך וסדרה, והן רציפות לחלוטין — החוק מחייב רצף, איסור שימוש חוזר באותה שנת מס, ושמסמך מבוטל ישמור על מספרו.

GET/businesses/{business_id}/numbering

מציג את הסדרות האמיתיות (סדרות הניסוי פרטיות): doc_type, doc_type_name_he, series, next_number, configured_start, locked.

PUT/businesses/{business_id}/numbering
doc_type
integerחובה
הסוג שאת סדרתו אתם מגדירים.
starting_number
integer ≥ 1חובה
המספר הראשון שיופק. עוברים מפנקס ידני שהקבלה האחרונה בו הייתה 143? הזינו 144.
series
string= "A"
הסדרה שיש להגדיר.
לבעלים בלבד, ומותר רק לפני הפקת המסמך הראשון באותה סדרה — לאחר מכן היא נעולה (409 FLOW-NUM-002), מפני ששינוי רטרואקטיבי היה שובר את הרצף שהחוק מחייב.

דוחות#

צבירות על מסמכים אמיתיים שהופקו. חשבוניות זיכוי מקוזזות; מסמכי ניסוי לעולם אינם נספרים.

GET/businesses/{business_id}/reports/incomereports:read

פרמטרים וכותרות

from_date
dateחובה
כולל.
to_date
dateחובה
כולל.

מחזיר monthly[] (month, total_agorot, vat_agorot), by_type[] ו-total_agorot.

GET/businesses/{business_id}/reports/vatreports:read

מע"מ עסקאות לפי חודש: periods[] עם taxable_agorot ו-output_vat_agorot, בתוספת total_output_vat_agorot.

GET/businesses/{business_id}/reports/withholdingreports:read

מס שנוכה במקור לפי לקוח — הנתונים שמאחורי התאמת טופס 806 השנתית: customers[] ו-total_withheld_agorot.

מבנה אחיד#

ייצוא הספרים הסטטוטורי שמוגדר בהוראות ניהול ספרים, מפרט גרסה 1.31 — הקבצים שמבקר או רואה החשבון שלכם יבקשו.

POST/businesses/{business_id}/exports/unified-formatexport:read
from_date
dateחובה
כולל.
to_date
dateחובה
כולל; אסור שיקדם ל-from_date (FLOW-EXP-001).

בונה את INI.TXT ואת BKMVDATA.TXT (רוחב קבוע, ISO-8859-8, CRLF) בתוך מבנה התיקיות המחייב OPENFRMT/{vat}.{yy}/{MMDDhhmm}, ומחזיר export_id, folder_name, record_counts ואת closing_report — לכל סוג מסמך, הכמות והסכום שרואה החשבון מתאים מולם.

GET/businesses/{business_id}/exports/unified-format/{export_id}/downloadexport:read

מחזיר את קובץ ה-ZIP. חברי צוות בתפקיד רואה חשבון יכולים לייצא גם בלי יכולת להפיק מסמכים — זו בדיוק מטרת התפקיד.

Webhooks#

הירשמו לאירועים במקום לתשאל בלולאה. כל משלוח חתום ב-HMAC וכל ניסיון נרשם.

POST/businesses/{business_id}/webhooks
url
string (https)חובה
כתובת היעד.
events
string[]חובה
לפחות שם אירוע אחד; שמות לא מוכרים נדחים עם 422 FLOW-WH-001.

לבעלים בלבד. התשובה כוללת את סוד החתימה secret — מוצג פעם אחת.

אירוענשלחמטען
document.issuedכןdocument_id, doc_type, doc_number, total_agorot, allocation_status
allocation.rejectedכןdocument_id, rejection_code
document.cancelledשמור
allocation.approvedשמור
allocation.retro_assignedשמור
payment.linkedשמור
export.readyשמור
ita.authorization_expiringשמור
אירועים שמסומנים שמור ניתנים כבר היום להרשמה אך עדיין אינם נשלחים — הרשמה עכשיו אומרת שתקבלו אותם ברגע שיושקו, בלי שינוי אצלכם.
delivery
POST https://your-app.example/hooks/makor
X-Makor-Event: document.issued
X-Makor-Signature: t=1786000000,v1=6f2b...c91

{
  "event": "document.issued",
  "created_at": "2026-08-07T12:31:07.481Z",
  "data": {
    "document_id": "019fdad4-...",
    "doc_type": 305,
    "doc_number": 42,
    "total_agorot": 708000,
    "allocation_status": "approved"
  }
}

אימות החתימה

חשבו HMAC-SHA256(secret, "{t}.{raw body}") על גוף הבקשה הגולמי — פענוח ה-JSON וסריאליזציה מחדש משנים את הבייטים ושוברים את ההשוואה. השוו בזמן קבוע ודחו חותמות זמן ישנות.

Node.js
import crypto from "node:crypto";

export function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("=").map((s) => s.trim()))
  );
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSec) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(parts.v1, "hex")
  );
}
Python
import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(kv.split("=", 1) for kv in header.split(","))
    ts = int(parts["t"])
    if abs(time.time() - ts) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{ts}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])
GET/businesses/{business_id}/webhooks
GET/businesses/{business_id}/webhooks/{webhook_id}/deliveries

חמישים הניסיונות האחרונים עם event_type, status, response_status ו-attempt — המקום הראשון לבדוק כשאינטגרציה משתתקת.

DELETE/businesses/{business_id}/webhooks/{webhook_id}
ענו מהר, עבדו אחר כך
המשלוח פג אחרי 5 שניות. אשרו מיד עם 2xx ובצעו את העיבוד אסינכרונית; התייחסו לכל אירוע כאילו הוא עלול להישלח פעמיים והשתמשו ב-document_id כמפתח.

מפתחות API#

מפתחות מנוהלים בידי משתמשים מחוברים, לא בידי מפתחות אחרים.

POST/businesses/{business_id}/api-keys
name
string ≤100חובה
תווית שתוצג בממשק.
scopes
string[]רשות
ברירת מחדל: המקסימום שתפקידכם מתיר. הרשאה לא מוכרת מחזירה 422 FLOW-KEY-001.
sandbox
boolean= false
יצירת מפתח mk_test_ הקשור לנתוני ניסוי.

מחזיר את key (הסוד המלא, פעם אחת), key_id, ההרשאות שניתנו scopes ו-sandbox.

GET/businesses/{business_id}/api-keys

מטא-דאטה בלבד — key_id, name, scopes, sandbox, last_used_at, revoked. הסודות אינם ניתנים לאחזור לעולם.

DELETE/businesses/{business_id}/api-keys/{key_id}

מבטל מיידית. נדרש תפקיד בעלים או עובד.

אינדקס קודי שגיאה#

כל שגיאת כלל עסקי שה-API יכול להחזיר. הקודים יציבים בין גרסאות — הסתמכו עליהם.

קודHTTPמשמעות ואיך לתקן
FLOW-401401נדרש אימות — מפתח חסר, לא מוכר או מבוטל.
FLOW-403403חסרה הרשאה, או תפקיד לקריאה בלבד שמנסה לכתוב.
FLOW-404404לא נמצא, או שייך לעסק או לסביבה אחרת.
FLOW-AUTH-001409האימייל כבר רשום.
FLOW-AUTH-002401אימייל או סיסמה שגויים.
FLOW-AUTH-003403החשבון מושבת.
FLOW-BIZ-001422סוג ישות לא מוכר.
FLOW-BIZ-002422מספר הזיהוי נכשל בבדיקת ספרת ביקורת.
FLOW-BIZ-003409המשתמש כבר חבר או כבר הוזמן.
FLOW-BIZ-004403לא ניתן להסיר את חברות הבעלים.
FLOW-DOC-000422קוד סוג מסמך לא מוכר.
FLOW-DOC-001422סוג הישות אינו רשאי להפיק סוג מסמך זה — למשל עוסק פטור שמנסה להפיק חשבונית מס.
FLOW-DOC-002422למסמך אין שורות.
FLOW-DOC-010422לקבלה אין שורות תשלום.
FLOW-DOC-011422שורות התשלום אינן מסתכמות בסכום המסמך — זכרו שניכוי במקור נספר כשורת תשלום.
FLOW-DOC-012422לתשלום בצ'ק חסר cheque_number.
FLOW-DOC-020422לחשבונית זיכוי חסר parent_id.
FLOW-DOC-021422ניתן לזכות רק חשבונית מס או חשבונית מס/קבלה.
FLOW-DOC-022422רק קבלות יכולות לסגור חשבוניות.
FLOW-DOC-030422סכום חשבונית שלילי — יש להפיק חשבונית זיכוי במקום.
FLOW-DOC-040422customer_tax_id הוא חובה מעל סף ההקצאה.
FLOW-DOC-050404ה-customer_id אינו קיים בעסק הזה.
FLOW-DOC-060409המסמך אינו טיוטה — לרוב בקשת הפקה כפולה.
FLOW-DOC-061404המסמך לא נמצא.
FLOW-DOC-062409לא ניתן להשלים הפקה מהסטטוס הנוכחי של המסמך.
FLOW-DOC-063409טיוטה נמחקת, לא מבוטלת.
FLOW-DOC-064409למסמך מקושרות קבלות או זיכויים — יש לזכות אותו במקום לבטל.
FLOW-DOC-065409רק טיוטות ניתנות למחיקה.
FLOW-LINK-001422החשבונית המקושרת לא נמצאה.
FLOW-LINK-002422יעד הקישור אינו מסמך שהופק.
FLOW-LINK-003422קבלות יכולות לסגור רק חשבוניות מס או חשבוניות עסקה.
FLOW-LINK-004422סכום הקישור חייב להיות חיובי.
FLOW-LINK-005422סכום הקישור עולה על היתרה הפתוחה של החשבונית — קראו קודם את open_balance.
FLOW-ALLOC-001409המסמך אינו ממתין להחלטת הקצאה.
FLOW-ALLOC-002409גם בקשת היפוך החיוב נדחתה.
FLOW-NUM-001422סוג המסמך אינו זמין לסוג הישות הזה.
FLOW-NUM-002409המספור נעול — כבר הופקו מסמכים בסדרה זו.
FLOW-IDEM-001422מפתח אידמפוטנטיות שומש עם גוף בקשה שונה.
FLOW-IDEM-002409הבקשה המקורית עדיין בעיבוד — נסו שוב בעוד רגע.
FLOW-PAGE-001422קורסור עימוד פגום.
FLOW-PDF-001409לטיוטות אין PDF.
FLOW-SHARE-001409ניתן לשתף רק מסמכים שהופקו.
FLOW-EXP-001422טווח תאריכים לא חוקי לייצוא.
FLOW-KEY-001422התבקשה הרשאה לא מוכרת.
FLOW-WH-001422שם אירוע webhook לא מוכר.
FLOW-ITA-001409קריאת ה-OAuth של רשות המסים אינה רלוונטית במצב הנוכחי.

מגבלות וגרסאות#

ניהול גרסאות
/api/v1
הגרסה נמצאת בנתיב. שינויים מוסיפים (שדות, endpoints וערכים חדשים) יוצאים בלי העלאת גרסה — פרסו בזהירות והתעלמו משדות לא מוכרים.
הגבלת קצב
אין אכיפה
אין מכסה קשיחה כיום. שמרו על מקביליות סבירה; ההפקה מסודרת במכוון בטור לכל סדרת מספור, כך שהפקה מקבילה של אותו סוג מסמך לא תזרז דבר.
גודל בקשה
מעשי
אין תקרה קבועה, אך שמרו על מספר שורות סביר במסמך — הוא צריך להתרנדר לקובץ PDF להדפסה.
שמירת נתונים
7 שנים
מסמכים שהופקו והמקורות החתומים שלהם נשמרים לתקופה הקבועה בחוק ואינם ניתנים למחיקה דרך ה-API.
משהו לא ברור או חסר?
המדריך האינטראקטיבי בכתובת /api/docs נוצר מהסכמה החיה ותמיד תואם לגרסה שרצה — אם הדף הזה והסכמה אי פעם סותרים, הסכמה קובעת.