אינטגרציית קופה

סקירה

האינטגרציה דו-כיוונית. eato שולחת Webhook חתום לכתובת שלכם בכל אירוע הזמנה, והמערכת שלכם מחזירה סטטוסים, יוצרת הזמנות טלפוניות ומעדכנת זמינות דרך ה-API. מתאים לקופות כמו Restigo, Tabit ו-ResApp, ולכל קופה שיודעת לקבל הזמנות ולהחזיר סטטוס.

כל הנתיבים יושבים תחת כתובת בסיס אחת:

https://eato.co.il/api/v1/merchant

• Restigo
• Tabit
• ResApp
• Make
• Zapier
• n8n
• Pipedream
• Slack
• Telegram

אין סביבת Sandbox ציבורית. אפשר לבקש חשבון בדיקה עם תפריט לדוגמה.

אימות

כל קריאה ל-/api/v1/merchant/* נושאת מפתח Bearer בכותרת Authorization. המפתח בנוי כך: eak_live_<12 hex>_<32 base62>. הוא מוצג פעם אחת בלבד בזמן היצירה, ונשמר אצלנו כגיבוב בלבד, כך שגם אנחנו לא יכולים לשחזר אותו.

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

GET /api/v1/merchant/orders?status=preparing HTTP/1.1
Host: eato.co.il
Authorization: Bearer eak_live_a1b2c3d4e5f6_<32-char-secret>
Accept: application/json

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

שגיאות

כל שגיאה חוזרת במבנה אחיד. השדה field מופיע רק בשגיאות אימות של הגוף.

{
  "error": {
    "code": "validation_error",
    "message": "quantity must be at least 1",
    "field": "lines[0].quantity"
  }
}

Webhooks

אנחנו שולחים POST עם גוף JSON לכתובת שרשמתם, ומצפים לתשובת 2xx תוך 8 שניות. כל תוצאה אחרת מפעילה ניסיון חוזר. רושמים כתובת בלוח הבקרה או דרך ה-API, ולכל כתובת יש כפתור בדיקה ששולח אירוע order.created חתום לדוגמה.

כותרות

מעטפת

{
  "id": "7b1c2f6e-3d4a-4c1b-9f20-5a6b7c8d9e0f",
  "event": "order.created",
  "created_at": "2026-11-10T19:30:45.123Z",
  "tenant_id": "napoli",
  "data": {
    "order_id": "9d2e4b1a-6c3f-4e8d-a1b2-c3d4e5f60718",
    "number": 1247,
    "status": "confirmed",
    "total": 12700,
    "method": "delivery",
    "channel": "web",
    "payment_method": "card",
    "customer": { "name": "Dana", "phone": "+972541234567" },
    "items": [
      {
        "item_id": "marg",
        "name": "Margherita",
        "quantity": 1,
        "total": 5800,
        "size": "family",
        "modifiers": ["Right half: mushrooms"],
        "note": null
      }
    ],
    "created_at": "2026-11-10T19:30:41.002Z"
  }
}

אירועים

ניסיונות חוזרים

שישה ניסיונות לאורך כ-7.4 שעות. אחרי הכישלון השישי המשלוח מסומן abandoned. הוא נשאר בלוח הבקרה עם היסטוריה מלאה וכפתור Retry ידני.

אימות חתימה

הכותרת X-Eato-Signature בנויה כך: t=<unix>,v1=<hex>. הערך v1 הוא HMAC-SHA256 על t.raw_body עם הסוד של הכתובת. מאמתים מול הגוף הגולמי לפני פענוח ה-JSON, עם חלון של 5 דקות נגד שידור חוזר, ובהשוואה בזמן קבוע. חתימה לא תקינה מקבלת 401 ולא מעובדת.

const crypto = require("node:crypto");

function verifyEato(rawBody, header, secret) {
  if (!header) return false;
  const parts = Object.fromEntries(
    header.split(",").map((p) => {
      const i = p.indexOf("=");
      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
    })
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > 300) return false; // 5 minute window

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`, "utf8")
    .digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(parts.v1, "utf8");
  if (a.length !== b.length) return false; // timingSafeEqual throws on different lengths
  return crypto.timingSafeEqual(a, b);
}

// Express: keep the raw body, verify before JSON.parse
app.post("/eato/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyEato(raw, req.get("X-Eato-Signature"), process.env.EATO_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const delivery = req.get("X-Eato-Delivery"); // dedupe on this id
  queue.push({ delivery, event: JSON.parse(raw) }); // process async
  res.status(200).end(); // answer within 8 seconds
});

Orders API

הזמנה ידנית (טלפון או דלפק)

טלפון בפורמט ישראלי מומר ל-E.164. בלי payment_method ההזמנה נרשמת כמזומן.

curl -X POST https://eato.co.il/api/v1/merchant/orders/manual \
  -H "Authorization: Bearer $EATO_API_KEY" \
  -H "Idempotency-Key: 2f1e7c1a-8b9d-4e2f-a3c4-d5e6f7a8b9c0" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone": "054-1234567",
    "customer_name": "Dana",
    "method": "pickup",
    "payment_method": "cash",
    "notes": "no onion",
    "lines": [
      { "item_id": "marg", "quantity": 1, "size_id": "family", "option_ids": [] }
    ]
  }'

HTTP/1.1 201 Created
Content-Type: application/json

{
  "order": {
    "id": "5c7d9e1f-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
    "number": 1248,
    "status": "pending",
    "total": 5800,
    "eta_at": "2026-11-10T19:52:00.000Z"
  }
}

החזר

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

{
  "refund": {
    "amount": 5800,
    "reason": "customer cancelled",
    "money_action_required": true,
    "message": "Refund the card in the payment provider panel"
  },
  "money_action_required": true
}

Menu API

available_from ו-available_to הם דקות מחצות (660 = 11:00). available_days הוא מסכת ימים של 7 ביטים, ביט 0 הוא יום ראשון (127 = כל הימים). stock_remaining ריק (null) פירושו שאין מעקב מלאי.

מעברי סטטוס

מעבר לא חוקי מחזיר 409 invalid_transition. החזר עובר רק דרך POST /orders/{id}/refund. כל PATCH שולח גם Webhook לכל המנויים, כולל למי ששלח אותו, ולכן צריך מנגנון נגד לולאות.

Idempotency

שולחים כותרת Idempotency-Key עם UUID לכל פעולה לוגית. אותו מפתח עם אותו גוף מחזיר את התשובה המקורית עם X-Eato-Idempotent-Replay: true. אותו מפתח עם גוף אחר מחזיר 409 conflict. מפתחות פגים אחרי 24 שעות.

נתמך כרגע ב-POST /orders/manual. תמיכה בעדכון סטטוס ובהחזר מתוכננת.

מגבלת קריאות

600 קריאות בדקה לכל מפתח, בערך 10 בשנייה. חריגה מחזירה 429 עם Retry-After. מי שמתקרב למגבלה בדרך כלל נמצא בלולאה לא מסונכרנת, ועדיף לעבור ל-Webhooks במקום לשאול שוב ושוב.

CORS, IP ותעבורה

HTTPS בלבד. כתובת Webhook בלי HTTPS, או כתובת פנימית, נדחית ברישום. ל-Webhooks היוצאים אין כתובת IP קבועה. מי שצריך רשימת IP מורשים פונה לתמיכה לקבלת פרוקסי ייעודי. עיבוד כבד כדאי להעביר לתור, כי המתנה לתשובה מוגבלת ל-8 שניות.

מוסכמות

רשימת בדיקה לפני עלייה לאוויר

סומנו 0 מתוך 8.

שאלות ותמיכה

נתקעתם? כתבו ל-[למילוי: מייל מפתחים] עם מזהה המשלוח מהכותרת X-Eato-Delivery, או דרך צור קשר.