API (/api/v1)
מפתח לכל ממשק, חתימה על כל בקשה, הרשאה לפי מסך, פעולה ושדה, ומסנן שורות. הממשק נבנה במחולל ה-API במערכת, וכל ממשק מקבל מסמך OpenAPI משלו.
ממשק שנבנה מתוך המערכת, עם הרשאות לפי מסך ושדה. שרת MCP למודול חיצוני. ספריית JavaScript אחת שמכסה את שניהם, כולל העלאה והורדה של קבצים.
מפתח לכל ממשק, חתימה על כל בקשה, הרשאה לפי מסך, פעולה ושדה, ומסנן שורות. הממשק נבנה במחולל ה-API במערכת, וכל ממשק מקבל מסמך OpenAPI משלו.
714 כלים, אותם כלים של הסוכן הפנימי, בהרשאות של בעל האסימון. כל כתיבה הופכת לבקשת אישור לאדם.
קובץ JavaScript אחד, בלי תלויות, עם הגדרות טיפוסים. עובד בדפדפן, ב-Node.js 18 ומעלה, ב-Deno וב-Bun. רישיון MIT.
העלאה, רשימה, הורדה והסרה של קבצים ברשומה, עם אותן בדיקות של הלשונית "קבצים" במערכת: סוג לפי התוכן, סיומות מורשות, גודל וסריקת אנטי-וירוס.
eolk_…) וסוד החתימה (eols_…) מוצגים פעם אחת. שומרים אותם במשתני סביבה.GET /api/v1/me. המסמך המלא של הממשק: GET /api/v1/openapi.json.בסביבת הניסיון הציבורית אין גישה פתוחה ל-API, ל-MCP ול-A2A. הגישה ניתנת לכל לקוח בשרת שלו, עם מפתח או אסימון שמנהל המערכת יוצר.
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
פונקציית חתימה קטנה (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.malware). כשהסורק לא זמין, ההעלאה נדחית ולא עוברת בלי סריקה.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])
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) |
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 עוד לא נראתה.not_tracked), ולא רשימה ריקה. מסמך OpenAPI של הממשק מציג את הנתיב רק במסכים שיש בהם.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;
: > 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):
EOLIPA1-HMAC-SHA256METHODpath?querytimestampnoncekey_prefixsha256_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 (הוא מוסיף אחד לבד).
ממשק עם מנוי שולח 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 (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)
גרסה 1.1.0. מודול ES אחד, בלי תלויות, שלא פונה לשום כתובת חוץ מהשרת שנותנים לו. רישיון MIT (בראש הקובץ eolipa-sdk.d.ts).
EolipaApi, EolipaMcp, verifyWebhook ועזרי base64 ו-sha256.טיפוסים לרשומות: מייצרים אותם מה-OpenAPI של הממשק שלכם (api.openapi()) בעזרת openapi-typescript, ומעבירים כפרמטר: api.get<Customer>('sales.customer', id).
כל מדריך כולל תרגול בסביבת ההדגמה, על נתוני דוגמה.
נתוני דוגמה · 7 ימים · ללא עלות · הרשמה ללא כרטיס אשראי