חיבור מבחוץ: API, ‏MCP ו-SDK.

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

מה יש כאן

API ‏(/api/v1)

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

MCP למודול חיצוני

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

Web SDK

קובץ JavaScript אחד, בלי תלויות, עם הגדרות טיפוסים. עובד בדפדפן, ב-Node.js 18 ומעלה, ב-Deno וב-Bun. רישיון MIT.

קבצים מצורפים

העלאה, רשימה, הורדה והסרה של קבצים ברשומה, עם אותן בדיקות של הלשונית "קבצים" במערכת: סוג לפי התוכן, סיומות מורשות, גודל וסריקת אנטי-וירוס.

התחלה מהירה

  1. במערכת, במחולל ה-API: מתארים במשפט מה המערכת החיצונית צריכה. המחולל מציע מסכים, פעולות ושדות, ואחרי אישור נוצרים ממשק ומפתח.
  2. המפתח (eolk_…) וסוד החתימה (eols_…) מוצגים פעם אחת. שומרים אותם במשתני סביבה.
  3. בודקים מה המפתח מורשה: GET /api/v1/me. המסמך המלא של הממשק: GET /api/v1/openapi.json.

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

עם ה-SDK

import { EolipaApi } from './eolipa-sdk.js';

const api = new EolipaApi({
  baseUrl: 'https://eolipa.example.co.il',
  key: process.env.EOLIPA_API_KEY,
  signingSecret: process.env.EOLIPA_SIGNING_SECRET,
});

const me = await api.me();                       // what this key may do
const page = await api.list('sales.customer', { q: 'כהן', limit: 50 });
for await (const c of api.listAll('sales.customer')) console.log(c.id, c.name);
const order = await api.create('sales.order', { customer: page.items[0].id });   // Idempotency-Key is automatic

עם curl

פונקציית חתימה קטנה (bash, openssl), ואחריה בקשה:

# הסוד והמפתח - ממשתני סביבה, לא בקוד
KEY="$EOLIPA_API_KEY"; SECRET="$EOLIPA_SIGNING_SECRET"
BASE="https://eolipa.example.co.il"
PREFIX=$(printf '%s' "$KEY" | cut -d_ -f1-2)          # eolk_xxxxxxxx

# sign METHOD PATH BODY_FILE  ->  prints the three signature headers
sign() {
  local METHOD="1" PATHQ="2" BODYF="3"
  TS=$(date +%s); NONCE=$(openssl rand -hex 16)
  BH=$(sha256sum "$BODYF" | cut -d' ' -f1)
  SIG=$(printf 'EOLIPA1-HMAC-SHA256\n%s\n%s\n%s\n%s\n%s\n%s' "$METHOD" "$PATHQ" "$TS" "$NONCE" "$PREFIX" "$BH" \
        | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')
  printf -- '-H\nX-Eolipa-Timestamp: %s\n-H\nX-Eolipa-Nonce: %s\n-H\nX-Eolipa-Signature: v1=%s\n' "$TS" "$NONCE" "$SIG"
}
: > empty.txt
P='/api/v1/me'
mapfile -t H < <(sign GET "$P" empty.txt)
curl -sS "$BASE$P" -H "Authorization: Bearer $KEY" "${H[@]}"

קבצים מצורפים: העלאה, רשימה, הורדה והסרה

כל רשומה שהמפתח רואה מקבלת את הנתיבים האלה. קריאה ורשימה דורשות הרשאת קריאה למסך; העלאה והסרה דורשות הרשאת עדכון. רשומה מחוץ למסנן של הממשק או של חברה אחרת מחזירה 404.

בקשהמה היא עושה
GET /api/v1/{entity}/{id}/attachmentsרשימת הקבצים ברשומה (בלי התוכן), והמגבלה של החברה ב-MB
POST /api/v1/{entity}/{id}/attachmentsהעלאה: { "filename", "content_base64", "content_type"? }. מחזירה 201 עם המזהה, הסוג שזוהה, הגודל ו-sha256
GET /api/v1/{entity}/{id}/attachments/{attachment_id}הורדה: הפרטים ו-content_base64, עם sha256 לבדיקה
DELETE /api/v1/{entity}/{id}/attachments/{attachment_id}הסרת הקובץ מהרשומה (רק קבצים, לא רשומות)

מה נבדק בכל העלאה

  • סוג לפי התוכן: קובץ הרצה נדחה גם כשהסיומת שלו תמימה, וקובץ שהתוכן שלו לא מתאים לסיומת נדחה. סיומות שנחסמות תמיד: .apk .app .application .appx .asp .aspx .bash .bat .chm .cjs .cmd .com .cpl .csh ועוד 54.
  • סיומות מורשות: רשימה של החברה. ברירת המחדל: pdf, jpg, jpeg, png, webp, gif, tif, tiff, heic, bmp, doc, docx, xls, xlsx, csv, txt, rtf, odt, ods, ppt, pptx, xml, json, zip, eml, msg.
  • גודל: לפי ההגדרה של החברה (ברירת מחדל 10MB). גוף בקשה עד 20MB (התוכן ב-base64 גדול בכשליש מהקובץ).
  • אנטי-וירוס: כשמוגדרת סריקה בשרת, כל קובץ נסרק לפני שהוא נשמר. קובץ נגוע נדחה ב-422 (malware). כשהסורק לא זמין, ההעלאה נדחית ולא עוברת בלי סריקה.
  • שם הקובץ: שמות בעברית נשמרים כמו שהם. נתיב, תווי בקרה ותווים אסורים מוסרים.

עם ה-SDK

import { readFile, writeFile } from 'node:fs/promises';
import { EolipaApi, EolipaError } from './eolipa-sdk.js';

const api = new EolipaApi({ baseUrl: 'https://eolipa.example.co.il', key: process.env.EOLIPA_API_KEY, signingSecret: process.env.EOLIPA_SIGNING_SECRET });

try {
  const up = await api.attachments.upload('fin.invoice', id, { filename: 'חשבונית 1001.pdf', data: await readFile('invoice.pdf') });
  const files = await api.attachments.list('fin.invoice', id);
  const f = await api.attachments.download('fin.invoice', id, up.id);
  await writeFile('copy.pdf', f.bytes);             // f.sha256 === up.sha256
  await api.attachments.remove('fin.invoice', id, up.id);
} catch (e) {
  if (e instanceof EolipaError) console.error(e.status, e.code, e.message);   // 413 too_large, 415 executable, 422 malware ...
}

// in a browser: <input type="file"> -> api.attachments.upload(entity, id, input.files[0])

עם curl

ID='<record-id>'
P="/api/v1/fin.invoice/$ID/attachments"

# upload: JSON with base64 content (multipart is rejected with 415, the signature covers the JSON bytes)
base64 -w0 invoice.pdf > b64.txt
jq -cn --arg f 'חשבונית 1001.pdf' --rawfile c b64.txt '{filename: $f, content_base64: $c}' > body.json
mapfile -t H < <(sign POST "$P" body.json)
curl -sS -X POST "$BASE$P" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
     -H "Idempotency-Key: $(uuidgen)" "${H[@]}" --data-binary @body.json
# -> 201 { "id": "...", "name": "חשבונית 1001.pdf", "content_type": "application/pdf", "size": 48213, "sha256": "...", "scanned_by": "clamav" }

# list
: > empty.txt
mapfile -t H < <(sign GET "$P" empty.txt)
curl -sS "$BASE$P" -H "Authorization: Bearer $KEY" "${H[@]}"

# download one file
A_ID='<attachment-id>'
mapfile -t H < <(sign GET "$P/$A_ID" empty.txt)
curl -sS "$BASE$P/$A_ID" -H "Authorization: Bearer $KEY" "${H[@]}" | jq -r .content_base64 | base64 -d > copy.pdf

דרך MCP: הכלי attach_file מקבל את התוכן ב-base64 ויוצר בקשת אישור, וההורדה היא משאב eolipa://attachments/…. הפירוט במדריך ה-MCP.

סנכרון הדרגתי: מה השתנה ומה נמחק

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

בקשהמה היא עושה
GET /api/v1/{entity}?updated_at[gte]=…סינון לפי created_at או updated_at, עם [gt], [gte], [lt], [lte]. אפשר גם בצורה updated_at=gt.…
GET /api/v1/{entity}/deleted?since=…רשומות שנמחקו (deleted) או עברו לארכיון (archived) מאז since: מזהה, deleted_at, ו-restored_at אם שוחזרו. עמוד של עד 1000 (ברירת מחדל 200)
  • הזמן: ISO 8601 עם אזור זמן, למשל 2026-11-11T09:30:00Z או 2026-11-11T11:30:00+02:00 (ב-URL הסימן + נשלח כ-%2B). תאריך בלי שעה הוא חצות UTC. ערך לא תקין, או אופרטור אחר, מחזיר 422 עם הסבר בעברית (detail.code: bad_timestamp או bad_operator).
  • מה המפתח רואה: רק רשומות שהממשק רשאי לקרוא, לפי אותו מסנן שורות והפרדה בין חברות של הרשימה. מזהה של רשומה שנמחקה ולא הייתה גלויה לממשק לא מופיע.
  • הסנכרון הבא: בתשובה של רשימת הנמחקים יש as_of, זמן השרת. שומרים אותו ושולחים אותו כ-since בפעם הבאה. since כולל (גדול או שווה), ולכן רשומה יכולה לחזור פעמיים: מעדכנים לפי המזהה. מומלץ חלון חפיפה של כמה דקות, כי שמירה ארוכה שהתחילה לפני as_of עוד לא נראתה.
  • איפה זה קיים: רשימת הנמחקים קיימת בנתוני אב ובמסמכים, כי שם כל מחיקה נרשמת. במסך אחר הנתיב מחזיר 409 (not_tracked), ולא רשימה ריקה. מסמך OpenAPI של הממשק מציג את הנתיב רק במסכים שיש בהם.

עם ה-SDK

import { EolipaApi } from './eolipa-sdk.js';

const api = new EolipaApi({ baseUrl: 'https://eolipa.example.co.il', key: process.env.EOLIPA_API_KEY, signingSecret: process.env.EOLIPA_SIGNING_SECRET });

// since: the as_of you saved last time (see the note on overlap below)
const since = state.lastSync;
let next = null, offset = 0, page; const restored = new Set();
do {                                                       // deletions first: the first page's as_of is the next lastSync
  page = await api.deleted('sales.customer', since, { offset });
  next ??= page.as_of;
  for (const d of page.items) {
    if (d.kind === 'archived' && !d.restored_at) await markArchived(d.id);  // still there, read-only
    else if (d.restored_at) restored.add(d.id);            // restored: read it again below
    else { restored.delete(d.id); await remove(d.id); }    // deleted (a later event wins)
  }
  offset = page.next_offset;
} while (page.has_more);
for await (const c of api.changedSince('sales.customer', since)) await upsert(c);
for (const id of restored) {                               // restored and then deleted again: 404, it is gone
  const r = await api.get('sales.customer', id).catch((e) => (e.status === 404 ? null : Promise.reject(e)));
  if (r) await upsert(r); else await remove(id);
}
state.lastSync = next;

עם curl

: > empty.txt
SINCE='2026-11-11T09:30:00Z'
# changed since: updated_at[gte] - the brackets go encoded (%5B %5D), curl reads [ ] as a pattern
P="/api/v1/sales.customer?updated_at%5Bgte%5D=$SINCE&sort=created_at&limit=200"
mapfile -t H < <(sign GET "$P" empty.txt)
curl -sS "$BASE$P" -H "Authorization: Bearer $KEY" "${H[@]}"

# deleted or archived since the same time
P="/api/v1/sales.customer/deleted?since=$SINCE"
mapfile -t H < <(sign GET "$P" empty.txt)
curl -sS "$BASE$P" -H "Authorization: Bearer $KEY" "${H[@]}"
# -> { "items": [{ "id": "...", "kind": "deleted", "deleted_at": "2026-11-11T09:31:12.402113+00:00", "restored_at": null }],
#      "has_more": false, "next_offset": null, "since": "...", "as_of": "2026-11-11T09:45:00.118204+00:00" }

חתימה על כל בקשה

כל בקשה נושאת את המפתח בכותרת Authorization: Bearer eolk_…, ובנוסף חתימת HMAC-SHA256 בסוד החתימה. שלוש כותרות: X-Eolipa-Timestamp, X-Eolipa-Nonce, X-Eolipa-Signature (הערך v1=<hex>).

מחרוזת החתימה: השורות האלה, מחוברות בירידת שורה (\n):

  1. EOLIPA1-HMAC-SHA256
  2. METHOD
  3. path?query
  4. timestamp
  5. nonce
  6. key_prefix
  7. sha256_hex(body)

חותמת הזמן בשניות, בחלון של ±5 דקות. ה-nonce חדש בכל בקשה (16-64 תווים מ-A-Z a-z 0-9 _ -); nonce שכבר שימש נדחה במשך 15 דקות. הנתיב נחתם בדיוק כמו שהוא נשלח, כולל ה-query.

קודי שגיאה

כל שגיאה חוזרת כ-JSON עם הודעה בעברית ב-error, ופרט קריא למכונה ב-detail (למשל detail.code או detail.reason). ב-SDK: EolipaError עם status, code ו-retryAfter.

קודמתי
401מפתח חסר, שגוי, מבוטל או שפג תוקפו; או חתימה חסרה, שגויה, מחוץ לחלון הזמן או חוזרת (detail.reason)
403אין הרשאה: מסך, פעולה או שדה שלא הוענקו, IP לא מורשה, או נחסם במסד
404לא נמצא (או מחוץ לתחום של המפתח)
409התנגשות: גרסה שהשתנתה, שדה שמשתנה רק בתהליך, ערך ייחודי שכבר קיים (למשל מספר לקוח), או Idempotency-Key (detail.reason: idempotency_mismatch - אותו מפתח עם בקשה אחרת; idempotency_in_progress - בקשה עם אותו מפתח עדיין בעיבוד, ממתינים לפי Retry-After)
413הקובץ גדול מהמגבלה של החברה (detail.limit_mb), או שהבקשה גדולה מתקרת השרת
415סוג הקובץ לא מתקבל: קובץ הרצה, סיומת מסוכנת, או תוכן שלא תואם לסיומת / ל-MIME (detail.code)
422נתונים לא תקינים: שדה לא קיים, שדה מחושב, חובה חסר, קישור לרשומה שלא קיימת או לא מורשית, כלל עסקי, ערך בסוג לא נכון, או Idempotency-Key לא תקין (הפירוט ב-detail)
428הממשק דורש Idempotency-Key בכל כתיבה, והכותרת לא נשלחה
429חריגה ממגבלת הקצב - ממתינים לפי Retry-After
500שגיאה פנימית בשרת - הפרטים נרשמו ביומן. אפשר לנסות שוב; בכתיבה - עם אותו Idempotency-Key
503המערכת עסוקה או שהאבטחה במסד של הממשק עוד לא הותקנה - ממתינים לפי Retry-After ושולחים שוב

מגבלות

מהכמה
עלותללא עלות לבקשה, ב-API וב-MCP, קריאה או כתיבה. כל חבילה כוללת היקף חודשי של קריאות ושל כתיבות (במחירון). כשהוא נגמר, בקשות מאותו סוג מקבלות 429 עד תחילת החודש הבא, בלי חיוב
מגבלת קצב של ממשקנקבעת לכל ממשק במחולל (בדקה). GET /me מחזיר אותה
תקרה בשרת600 בקשות בדקה למפתח, ו-600 לכתובת IP
גוף בקשהעד 1MB, ובנתיבי הקבצים עד 20MB
קובץלפי ההגדרה של החברה (ברירת מחדל 10MB)
גודל עמוד ברשימהlimit בין 1 ל-200 (ברירת מחדל 50)

חריגה מחזירה 429 עם Retry-After. ה-SDK ממתין ושולח שוב בקריאה, ובכתיבה רק עם Idempotency-Key (הוא מוסיף אחד לבד).

Webhooks

ממשק עם מנוי שולח POST ליעד שהוגדר בכל פעם שרשומה בתחום שלו נוצרת או מתעדכנת, רק עם השדות שהממשק קורא. הכותרת Eolipa-Signature: t=<unix>,v1=<hex> היא HMAC-SHA256 על t.body בסוד של היעד. תשובה 2xx מסמנת מסירה; אחרת יש ניסיונות חוזרים במשך יממה.

import { verifyWebhook } from './eolipa-sdk.js';

// raw body as received (string), before JSON.parse
const ok = await verifyWebhook(process.env.EOLIPA_WEBHOOK_SECRET, req.headers['eolipa-signature'], rawBody);
if (!ok) return res.status(401).end();
const event = JSON.parse(rawBody);   // { event_id, event: 'sales.order.created', occurred_at, client, id, data }
res.status(204).end();               // any 2xx = delivered

A2A: כרטיס סוכן

מודול חיצוני שמדבר A2A ‏(1.0, 0.3) מוצא את הכתובות והכישורים בכרטיס: /.well-known/agent-card.json. הנקודה: /a2a, עם אותו אסימון של MCP.

מזההכישור
eolipa.dataנתונים ורשומות
eolipa.financeכספים
eolipa.reportsדוחות ומדדים
eolipa.commsמיילים והודעות
eolipa.buildבנייה
eolipa.skillsכישורים ואוטומציות
curl -sS "https://eolipa.example.co.il/.well-known/agent-card.json"            # the agent card (skills, versions, endpoints)

הורדת ה-Web SDK

גרסה 1.1.0. מודול ES אחד, בלי תלויות, שלא פונה לשום כתובת חוץ מהשרת שנותנים לו. רישיון MIT (בראש הקובץ eolipa-sdk.d.ts).

  • eolipa-sdk.js: ‏EolipaApi, EolipaMcp, verifyWebhook ועזרי base64 ו-sha256.
  • eolipa-sdk.d.ts: הגדרות טיפוסים ל-TypeScript.

טיפוסים לרשומות: מייצרים אותם מה-OpenAPI של הממשק שלכם (api.openapi()) בעזרת openapi-typescript, ומעבירים כפרמטר: api.get<Customer>('sales.customer', id).

הכי טוב ללמוד על המערכת עצמה

כל מדריך כולל תרגול בסביבת ההדגמה, על נתוני דוגמה.

נתוני דוגמה · 7 ימים · ללא עלות · הרשמה ללא כרטיס אשראי