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 נוצרת הטיוטה, מוקצה לה מספר, מתבצעת פנייה לרשות המסים כשנדרש, והמסמך מרונדר, נחתם ומופק — הכול בבקשה אחת.
# 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 }
]
}'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
}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}`);
}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). אין שלב החלפת טוקן ואין מה לרענן — המפתח שיצרתם הוא בדיוק מה שנשלח בכל בקשה.
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. יוצר מסמכי ניסוי בלבד — ראו סביבת ניסוי. |
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/v1 | mk_live_… |
| ניסוי | https://sandbox.makor.all-good.co.il/api/v1 | mk_test_… |
mk_test_ מול כתובת הייצור נדחה ב-403, וכך גם מפתח mk_live_ מול כתובת הניסוי — עם הודעה שמפנה לכתובת הנכונה. זו הסיבה שאי אפשר להפיק חשבונית אמיתית בטעות בזמן פיתוח: צריך לטעות בשני מקומות בו-זמנית.צרו מפתח עם "sandbox": true וקראו לכתובת הניסוי. כל קריאה פועלת על נתוני ניסוי — בלי פרמטרים נוספים.
הגדרות → סביבת ניסוי → כניסה למצב ניסוי. באנר כתום מסמן את הסשן וכל מה שתיצרו הוא מסמך ניסוי.
מה הבידוד אומר בפועל
| מספור נפרד מובטח | מסמכי ניסוי שואבים מסדרת מספור משלהם לכל סוג מסמך. המספור החוקי והרציף שלכם לעולם לא מתקדם בגלל ניסוי. |
| אין תעבורה לרשות המסים מובטח | בקשות הקצאה למסמכי ניסוי נענות בסימולטור דטרמיניסטי ולעולם לא נשלחות לרשות — גם בסביבת ייצור. |
| מחוץ לספרים מובטח | מסמכי ניסוי לא מופיעים בדוחות הכנסות, מע"מ וניכוי במקור, ולא בייצוא המבנה האחיד. |
| מסומן בבירור מובטח | כל PDF של ניסוי נושא חותמת אלכסונית "SANDBOX — אינו מסמך חשבונאי", וה-API מחזיר is_sandbox: true. |
| עיוורון דו-כיווני מובטח | מפתח ייצור מקבל 404 על מסמך ניסוי ולהפך; קריאות רשימה מחזירות תמיד סביבה אחת בלבד. |
טריגרים דטרמיניסטיים להקצאה
כדי לתרגל כל תוצאה אפשרית מרשות המסים לפי דרישה, סביבת הניסוי בוחרת את התשובה לפי שתי ספרות האגורות האחרונות של הסכום לפני מע"מ. כך אפשר לבנות ולבדוק את זרימת הדחייה בלי לחכות לסירוב אמיתי.
| הסכום מסתיים ב | התוצאה המדומה | HTTP |
|---|---|---|
| …60 | מעוכב לבדיקה, קוד 460 — זרימת ארבע ההחלטות | 202 |
| …61 | קיימת חשבונית לא מאושרת שממתינה להחלטה, קוד 461 | 202 |
| …03 | תקלה טכנית — המסמך מופק עם failed_retro_pending | 201 |
| כל סכום אחר | אושר, עם מספר הקצאה מדומה בן 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 בעברית שניתן להציג ישירות למשתמש הקצה.
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 — נסו שוב בעוד רגע |
עימוד#
קריאות רשימה שיכולות לגדול ללא גבול משתמשות בעימוד מבוסס קורסור, שנשאר נכון גם בזמן שמופקים מסמכים חדשים.
{
"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). |
תוצאות אפשריות
| HTTP | allocation_status | מה קרה |
|---|---|---|
| 201 | approved | אושר. allocation_number מכיל את מספר האישור המלא בן 26 הספרות; ב-PDF מודפסות תשע הספרות הימניות תחת ”מספר הקצאה“. |
| 201 | not_required | מתחת לסף, לקוח פרטי, או סוג מסמך שאינו בגדר החובה. |
| 201 | failed_retro_pending | רשות המסים לא הייתה זמינה. התקנות מתירות להפיק בכל זאת; מקור מבקשת הקצאה רטרואקטיבית שוב ושוב (מותר עד שנה). |
| 202 | rejected | עוכב לבדיקה (קוד 460 או 461). למסמך הוקצה מספר אך הוא לא הופק — הוא נשאר pending עד שתבחרו מסלול. |
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 -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" }'אובייקט המסמך#
מוחזר מכל קריאה שקשורה למסמכים. הסכומים באגורות; שדות כספיים תמיד קיימים, גם כשערכם אפס.
idstring (uuid)חובה | מזהה קבוע. |
doc_typeintegerחובה | קוד סוג המסמך — ראו סוגי מסמכים. אלה בדיוק הקודים של תקן המבנה האחיד. |
doc_type_name_he / _enstringחובה | שם סוג המסמך לתצוגה, מוכן להדפסה. |
seriesstringחובה | סדרת מספור, ברירת מחדל "A". |
doc_numberinteger | nullחובה | מוקצה בהפקה ולא ניתן לשינוי אחריה; null כל עוד המסמך טיוטה. |
statusstringחובה | draft · pending · issued · cancelled. |
customer_id / customer_name / customer_tax_idstring | nullחובה | תצלום של פרטי הלקוח שהוקפא בהפקה — עריכה מאוחרת של כרטיס הלקוח לא משנה מסמך שהופק. |
issue_date / due_datedate | nullחובה | תאריכי לוח. |
subtotalintegerחובה | סכום שורות המסמך לפני הנחת מסמך, ללא מע"מ. |
discount_totalintegerחובה | הנחה ברמת המסמך. |
taxable_amountintegerחובה | בסיס המע"מ אחרי חלוקת ההנחה — זה הסכום שנבדק מול סף ההקצאה. |
vat_rate_bpintegerחובה | שיעור בנקודות בסיס; 1800 = 18%. אפס כשהמסמך אינו נושא מע"מ. |
vat_amountintegerחובה | המע"מ המחושב. |
totalintegerחובה | סה"כ כולל מע"מ. |
withholding_amountintegerחובה | סכום שורות התשלום מסוג ניכוי מס במקור. |
allocation_statusstringחובה | ראו סטטוסי הקצאה. |
allocation_numberstring | nullחובה | מספר האישור המלא בן 26 ספרות. מדפיסים את תשע הספרות האחרונות. |
languagestringחובה | he או en — קובע את שפת רינדור המסמך. |
parent_idstring | nullחובה | בחשבונית זיכוי: החשבונית המזוכה. |
is_sandboxbooleanרשות | true עבור מסמכי ניסוי. |
open_balanceinteger | 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 | עמותות בלבד, סדרה נפרדת |
FLOW-DOC-001).סטטוס מסמך
| ערך | משמעות |
|---|---|
| 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 |
| card | card_brand, card_last4, installments |
| bank_transfer | transfer_ref |
| app | ביט, פייבוקס וכדומה |
| withholding | ניכוי מס במקור — לא כסף שהתקבל, אך מסלק את החוב ונספר בסכום |
| other | — |
טיפול מע"מ
| ערך | משמעות |
|---|---|
| standard | חייב מע"מ בשיעור מלא (18%) |
| exempt | עסקה פטורה — מחוץ לבסיס המע"מ |
| zero | מע"מ בשיעור אפס, למשל יצוא |
סוגי ישות
| ערך | בעברית |
|---|---|
| osek_patur | עוסק פטור |
| osek_murshe | עוסק מורשה |
| company | חברה בע"מ |
| partnership | שותפות |
| amuta | עמותה / מלכ"ר |
מסמכים#
ליבת ה-API. כל הנתיבים יחסיים לכתובת הבסיס ומשויכים לעסק.
/businesses/{business_id}/documentsdocuments:writeיוצר טיוטה, ועם ?issue=true מריץ את מלוא צינור ההפקה: ולידציה → הקצאת מספר רציף → אישור מול רשות המסים → רינדור PDF וחתימה דיגיטלית. מחזיר 201, או 202 כשהרשות מעכבת את החשבונית.
פרמטרים וכותרות
issueboolean= false | להפיק מיד במקום להשאיר טיוטה. |
sandboxboolean= false | יצירת מסמך ניסוי. מתעלמים ממנו במפתחות API — הסביבה של המפתח תמיד גוברת. |
Idempotency-Keyכותרתרשות | מומלץ בחום בכל פעם שמשתמשים ב-issue=true. |
גוף הבקשה
doc_typeintegerחובה | אחד מקודי סוגי המסמכים. |
issue_datedateחובה | קובע את שיעור המע"מ ואת סף ההקצאה שיחולו. |
customer_idstring (uuid)רשות | לקוח קיים; השם, מספר הזיהוי והכתובת מועתקים למסמך בהפקה. |
customer_namestringרשות | לקוח חד-פעמי, או דריסה של השם השמור. |
customer_tax_idstring (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_idstring (uuid)רשות | חובה בחשבונית זיכוי (330): החשבונית המזוכה. |
document_discount_agorotinteger= 0 | הנחה על כלל המסמך, מחולקת יחסית על בסיס המע"מ. |
due_datedateרשות | תאריך לתשלום שיודפס על המסמך. |
languagestring= "he" | he או en — בוחר את שפת רינדור ה-PDF. |
seriesstring= "A" | סדרת מספור חלופית (למשל לפי סניף). כל סדרה רציפה בפני עצמה. |
notes / footer_textstringרשות | טקסט חופשי שיודפס על המסמך. |
{
"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./businesses/{business_id}/documents/{document_id}/issuedocuments:writeמפיק טיוטה קיימת — אותו צינור ואותה סמנטיקה של 201/202 כמו יצירה עם ?issue=true. הפקה של מסמך שאינו טיוטה מחזירה 409 FLOW-DOC-060, וכך גם נראית בקשה כפולה.
/businesses/{business_id}/documents/{document_id}/allocation-decisiondocuments:writechoicestringחובה | אחד מ-cancel, continue, reverse_charge, object. |
reasonstring ≤500רשות | נשמר על המסמך בעת ביטול. |
תקף רק כשהמסמך pending וסטטוס ההקצאה שלו rejected או objection; אחרת 409 FLOW-ALLOC-001. אם גם בקשת היפוך החיוב נדחית תקבלו 409 FLOW-ALLOC-002.
/businesses/{business_id}/documentsdocuments:readפרמטרים וכותרות
doc_typeintegerרשות | סינון לפי קוד סוג. |
statusstringרשות | draft · pending · issued · cancelled. |
from_date / to_datedateרשות | סינון לפי issue_date, כולל. |
limitinteger= 50 | מקסימום 200. |
cursorstringרשות | מתוך next_cursor הקודם. |
sandboxboolean= false | קריאות עם סשן מחליפות סביבה; מפתחות API נעולים לסביבה שלהם. |
מחזיר { items, next_cursor }, מהחדש לישן. פריטי הרשימה אינם כוללים lines, payments ו-open_balance — לשם כך קראו מסמך בודד.
/businesses/{business_id}/documents/{document_id}documents:readהמסמך המלא, כולל lines[], payments[] ו — בחשבוניות ובחשבוניות עסקה שהופקו — open_balance.
/businesses/{business_id}/documents/{document_id}/canceldocuments:writereasonstring ≤500רשות | נרשם על המסמך וביומן הביקורת. |
409 FLOW-DOC-064); יש להפיק חשבונית זיכוי במקום. אם המקור כבר הגיע ללקוח, חשבונית זיכוי היא ממילא הכלי הנכון מבחינה משפטית./businesses/{business_id}/documents/{document_id}documents:writeמוחק טיוטה. כל מסמך שכבר ממוספר מחזיר 409 FLOW-DOC-065 — מסמכים שהופקו הם בלתי ניתנים לשינוי ומבוטלים או מזוכים, לעולם לא נמחקים.
/businesses/{business_id}/documents/{document_id}/pdfdocuments:readמחזיר application/pdf. הקריאה הראשונה מרנדרת וחותמת דיגיטלית את המקור ושומרת אותו; כל קריאה נוספת מחזירה בדיוק את אותם בייטים, מפני שהקובץ החתום הוא המקור המשפטי. הוסיפו ?copy=true לרינדור העתק. לטיוטה אין PDF (409 FLOW-PDF-001).
לקוחות#
/businesses/{business_id}/customerscustomers:readפרמטרים וכותרות
qstringרשות | חיפוש חופשי בשם, במספר הזיהוי ובאימייל. |
limitinteger= 50 | מקסימום 200. |
/businesses/{business_id}/customerscustomers:writenamestring ≤200חובה | שם לתצוגה. |
tax_idstring (9 ספרות)רשות | יידרש בהמשך אם תפיקו ללקוח חשבונית מעל סף ההקצאה. |
email / phonestringרשות | משמשים למשלוח מסמכים. |
address_street / _house / _city / _zipstringרשות | מודפסים על המסמכים. |
country_codestring (2)= "IL" | ISO 3166-1 alpha-2. |
withholding_rate_bpinteger 0–5000= 0 | שיעור ניכוי במקור ברירת מחדל בנקודות בסיס (500 = 5%), למילוי מראש בקבלות. |
notesstring ≤1000רשות | הערה פנימית. |
/businesses/{business_id}/customers/{customer_id}customers:read/businesses/{business_id}/customers/{customer_id}customers:writeעדכון חלקי. עריכת לקוח לעולם אינה משנה מסמכים שכבר הופקו עבורו — הם נושאים תצלום מוקפא.
/businesses/{business_id}/customers/{customer_id}customers:writeמחיקה רכה (השבתה). ההיסטוריה נשמרת לתקופת השמירה הקבועה בחוק.
/businesses/{business_id}/customers/{customer_id}/consentcustomers:read/businesses/{business_id}/customers/{customer_id}/consentcustomers:writegranted_viastringחובה | אחד מ-checkbox, link, import. |
פריטים#
קטלוג אופציונלי למילוי מהיר של שורות מסמך.
/businesses/{business_id}/itemsitems:readפרמטרים וכותרות
qstringרשות | חיפוש לפי שם. |
limitinteger= 100 | מקסימום 500. |
/businesses/{business_id}/itemsitems:writenamestring ≤200חובה | שם הפריט. |
name_enstringרשות | משמש במסמכים באנגלית. |
skustring ≤20רשות | מק"ט פנימי. |
unitstring= "יחידה" | יחידת מידה. |
unit_price_agorotinteger= 0 | מחיר ברירת מחדל. |
vat_treatmentstring= "standard" | standard · exempt · zero. |
descriptionstring ≤500רשות | תיאור מורחב. |
/businesses/{business_id}/items/{item_id}items:write/businesses/{business_id}/items/{item_id}items:writeמספור#
סדרות מספור הן לפי עסק, סוג מסמך וסדרה, והן רציפות לחלוטין — החוק מחייב רצף, איסור שימוש חוזר באותה שנת מס, ושמסמך מבוטל ישמור על מספרו.
/businesses/{business_id}/numberingמציג את הסדרות האמיתיות (סדרות הניסוי פרטיות): doc_type, doc_type_name_he, series, next_number, configured_start, locked.
/businesses/{business_id}/numberingdoc_typeintegerחובה | הסוג שאת סדרתו אתם מגדירים. |
starting_numberinteger ≥ 1חובה | המספר הראשון שיופק. עוברים מפנקס ידני שהקבלה האחרונה בו הייתה 143? הזינו 144. |
seriesstring= "A" | הסדרה שיש להגדיר. |
409 FLOW-NUM-002), מפני ששינוי רטרואקטיבי היה שובר את הרצף שהחוק מחייב.דוחות#
צבירות על מסמכים אמיתיים שהופקו. חשבוניות זיכוי מקוזזות; מסמכי ניסוי לעולם אינם נספרים.
/businesses/{business_id}/reports/incomereports:readפרמטרים וכותרות
from_datedateחובה | כולל. |
to_datedateחובה | כולל. |
מחזיר monthly[] (month, total_agorot, vat_agorot), by_type[] ו-total_agorot.
/businesses/{business_id}/reports/vatreports:readמע"מ עסקאות לפי חודש: periods[] עם taxable_agorot ו-output_vat_agorot, בתוספת total_output_vat_agorot.
/businesses/{business_id}/reports/withholdingreports:readמס שנוכה במקור לפי לקוח — הנתונים שמאחורי התאמת טופס 806 השנתית: customers[] ו-total_withheld_agorot.
מבנה אחיד#
ייצוא הספרים הסטטוטורי שמוגדר בהוראות ניהול ספרים, מפרט גרסה 1.31 — הקבצים שמבקר או רואה החשבון שלכם יבקשו.
/businesses/{business_id}/exports/unified-formatexport:readfrom_datedateחובה | כולל. |
to_datedateחובה | כולל; אסור שיקדם ל-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 — לכל סוג מסמך, הכמות והסכום שרואה החשבון מתאים מולם.
/businesses/{business_id}/exports/unified-format/{export_id}/downloadexport:readמחזיר את קובץ ה-ZIP. חברי צוות בתפקיד רואה חשבון יכולים לייצא גם בלי יכולת להפיק מסמכים — זו בדיוק מטרת התפקיד.
Webhooks#
הירשמו לאירועים במקום לתשאל בלולאה. כל משלוח חתום ב-HMAC וכל ניסיון נרשם.
/businesses/{business_id}/webhooksurlstring (https)חובה | כתובת היעד. |
eventsstring[]חובה | לפחות שם אירוע אחד; שמות לא מוכרים נדחים עם 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 | שמור | — |
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 וסריאליזציה מחדש משנים את הבייטים ושוברים את ההשוואה. השוו בזמן קבוע ודחו חותמות זמן ישנות.
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")
);
}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"])/businesses/{business_id}/webhooks/businesses/{business_id}/webhooks/{webhook_id}/deliveriesחמישים הניסיונות האחרונים עם event_type, status, response_status ו-attempt — המקום הראשון לבדוק כשאינטגרציה משתתקת.
/businesses/{business_id}/webhooks/{webhook_id}2xx ובצעו את העיבוד אסינכרונית; התייחסו לכל אירוע כאילו הוא עלול להישלח פעמיים והשתמשו ב-document_id כמפתח.מפתחות API#
מפתחות מנוהלים בידי משתמשים מחוברים, לא בידי מפתחות אחרים.
/businesses/{business_id}/api-keysnamestring ≤100חובה | תווית שתוצג בממשק. |
scopesstring[]רשות | ברירת מחדל: המקסימום שתפקידכם מתיר. הרשאה לא מוכרת מחזירה 422 FLOW-KEY-001. |
sandboxboolean= false | יצירת מפתח mk_test_ הקשור לנתוני ניסוי. |
מחזיר את key (הסוד המלא, פעם אחת), key_id, ההרשאות שניתנו scopes ו-sandbox.
/businesses/{business_id}/api-keysמטא-דאטה בלבד — key_id, name, scopes, sandbox, last_used_at, revoked. הסודות אינם ניתנים לאחזור לעולם.
/businesses/{business_id}/api-keys/{key_id}מבטל מיידית. נדרש תפקיד בעלים או עובד.
אינדקס קודי שגיאה#
כל שגיאת כלל עסקי שה-API יכול להחזיר. הקודים יציבים בין גרסאות — הסתמכו עליהם.
| קוד | HTTP | משמעות ואיך לתקן |
|---|---|---|
| FLOW-401 | 401 | נדרש אימות — מפתח חסר, לא מוכר או מבוטל. |
| FLOW-403 | 403 | חסרה הרשאה, או תפקיד לקריאה בלבד שמנסה לכתוב. |
| FLOW-404 | 404 | לא נמצא, או שייך לעסק או לסביבה אחרת. |
| FLOW-AUTH-001 | 409 | האימייל כבר רשום. |
| FLOW-AUTH-002 | 401 | אימייל או סיסמה שגויים. |
| FLOW-AUTH-003 | 403 | החשבון מושבת. |
| FLOW-BIZ-001 | 422 | סוג ישות לא מוכר. |
| FLOW-BIZ-002 | 422 | מספר הזיהוי נכשל בבדיקת ספרת ביקורת. |
| FLOW-BIZ-003 | 409 | המשתמש כבר חבר או כבר הוזמן. |
| FLOW-BIZ-004 | 403 | לא ניתן להסיר את חברות הבעלים. |
| FLOW-DOC-000 | 422 | קוד סוג מסמך לא מוכר. |
| FLOW-DOC-001 | 422 | סוג הישות אינו רשאי להפיק סוג מסמך זה — למשל עוסק פטור שמנסה להפיק חשבונית מס. |
| FLOW-DOC-002 | 422 | למסמך אין שורות. |
| FLOW-DOC-010 | 422 | לקבלה אין שורות תשלום. |
| FLOW-DOC-011 | 422 | שורות התשלום אינן מסתכמות בסכום המסמך — זכרו שניכוי במקור נספר כשורת תשלום. |
| FLOW-DOC-012 | 422 | לתשלום בצ'ק חסר cheque_number. |
| FLOW-DOC-020 | 422 | לחשבונית זיכוי חסר parent_id. |
| FLOW-DOC-021 | 422 | ניתן לזכות רק חשבונית מס או חשבונית מס/קבלה. |
| FLOW-DOC-022 | 422 | רק קבלות יכולות לסגור חשבוניות. |
| FLOW-DOC-030 | 422 | סכום חשבונית שלילי — יש להפיק חשבונית זיכוי במקום. |
| FLOW-DOC-040 | 422 | customer_tax_id הוא חובה מעל סף ההקצאה. |
| FLOW-DOC-050 | 404 | ה-customer_id אינו קיים בעסק הזה. |
| FLOW-DOC-060 | 409 | המסמך אינו טיוטה — לרוב בקשת הפקה כפולה. |
| FLOW-DOC-061 | 404 | המסמך לא נמצא. |
| FLOW-DOC-062 | 409 | לא ניתן להשלים הפקה מהסטטוס הנוכחי של המסמך. |
| FLOW-DOC-063 | 409 | טיוטה נמחקת, לא מבוטלת. |
| FLOW-DOC-064 | 409 | למסמך מקושרות קבלות או זיכויים — יש לזכות אותו במקום לבטל. |
| FLOW-DOC-065 | 409 | רק טיוטות ניתנות למחיקה. |
| FLOW-LINK-001 | 422 | החשבונית המקושרת לא נמצאה. |
| FLOW-LINK-002 | 422 | יעד הקישור אינו מסמך שהופק. |
| FLOW-LINK-003 | 422 | קבלות יכולות לסגור רק חשבוניות מס או חשבוניות עסקה. |
| FLOW-LINK-004 | 422 | סכום הקישור חייב להיות חיובי. |
| FLOW-LINK-005 | 422 | סכום הקישור עולה על היתרה הפתוחה של החשבונית — קראו קודם את open_balance. |
| FLOW-ALLOC-001 | 409 | המסמך אינו ממתין להחלטת הקצאה. |
| FLOW-ALLOC-002 | 409 | גם בקשת היפוך החיוב נדחתה. |
| FLOW-NUM-001 | 422 | סוג המסמך אינו זמין לסוג הישות הזה. |
| FLOW-NUM-002 | 409 | המספור נעול — כבר הופקו מסמכים בסדרה זו. |
| FLOW-IDEM-001 | 422 | מפתח אידמפוטנטיות שומש עם גוף בקשה שונה. |
| FLOW-IDEM-002 | 409 | הבקשה המקורית עדיין בעיבוד — נסו שוב בעוד רגע. |
| FLOW-PAGE-001 | 422 | קורסור עימוד פגום. |
| FLOW-PDF-001 | 409 | לטיוטות אין PDF. |
| FLOW-SHARE-001 | 409 | ניתן לשתף רק מסמכים שהופקו. |
| FLOW-EXP-001 | 422 | טווח תאריכים לא חוקי לייצוא. |
| FLOW-KEY-001 | 422 | התבקשה הרשאה לא מוכרת. |
| FLOW-WH-001 | 422 | שם אירוע webhook לא מוכר. |
| FLOW-ITA-001 | 409 | קריאת ה-OAuth של רשות המסים אינה רלוונטית במצב הנוכחי. |
מגבלות וגרסאות#
| ניהול גרסאות /api/v1 | הגרסה נמצאת בנתיב. שינויים מוסיפים (שדות, endpoints וערכים חדשים) יוצאים בלי העלאת גרסה — פרסו בזהירות והתעלמו משדות לא מוכרים. |
| הגבלת קצב אין אכיפה | אין מכסה קשיחה כיום. שמרו על מקביליות סבירה; ההפקה מסודרת במכוון בטור לכל סדרת מספור, כך שהפקה מקבילה של אותו סוג מסמך לא תזרז דבר. |
| גודל בקשה מעשי | אין תקרה קבועה, אך שמרו על מספר שורות סביר במסמך — הוא צריך להתרנדר לקובץ PDF להדפסה. |
| שמירת נתונים 7 שנים | מסמכים שהופקו והמקורות החתומים שלהם נשמרים לתקופה הקבועה בחוק ואינם ניתנים למחיקה דרך ה-API. |