📘 Simchapp Business API

🔑 הזדהות

כל בקשה חייבת לכלול כותרת:

Authorization: Bearer <API_KEY>

מפתחות מופקים בהגדרות העסק. המפתח מוצג פעם אחת בלבד. מוגבל ל-60 בקשות לדקה לכל מפתח. CORS פתוח.

🎉 פתיחת הזמנה חדשה

POST /api/v1/events · פעולה אידמפוטנטית לפי external_id.

curl -X POST "https://simchapp.co.il/api/v1/events" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "external_id": "glow-12345",
    "event_type": "wedding",
    "celebrant_name": "נועה & איתי",
    "event_date": "2027-05-20",
    "event_time": "19:00",
    "client_name": "משפחת לוי",
    "client_phone": "0501234567",
    "venue_name": "גלואו אירועים",
    "address": "הראשונים 7, הרצליה",
    "notes": "קונספט לבן-זהב"
  }'

תגובה: event_id, manage_url (לקוח), invitation_url (קישור כללי לאורחים), status (created / existing), client_name.

client_name – שם הלקוח (אופציונלי, ניתן לעדכון ב-PATCH, מוחזר בכל תשובה). client_phone – כל מספר ישראלי תקין (נייד, קווי או 07X); SMS/וואטסאפ נשלחים רק למספרים ניידים.

📋 רשימת אירועים ומעקב

GET /api/v1/events?from=YYYY-MM-DD&to=YYYY-MM-DD&updated_since=ISO&include_deleted=1

include_deleted=1 מחזיר גם אירועים שנמחקו ב-30 הימים האחרונים. כל אירוע כולל תמיד cancelled_at ו-deleted_at (null אם לא בוטל/נמחק).

curl -H "Authorization: Bearer $KEY" "https://simchapp.co.il/api/v1/events?from=2026-10-01"

סטטיסטיקה לכל אירוע: stats.invited_count, guests_total, attending_people, not_attending, pending, viewed, sent, last_rsvp_at.

🔎 פרטי אירוע מלאים

GET /api/v1/events/{id_or_external_id}

מחזיר stats, breakdowns (מנות, הסעות לפי עיר, פריטים להבאה, קבוצות) ואת רשימת האורחים. אירוע שנמחק מחזיר 410 deleted.

✏️ עדכון / ביטול / קישור חדש

PATCH /api/v1/events/{id_or_external_id}
DELETE /api/v1/events/{id_or_external_id}         # soft-cancel
POST   /api/v1/events/{id_or_external_id}/regenerate-link

שחזור אירוע שבוטל / ביטול דרך PATCH:

curl -X PATCH "https://simchapp.co.il/api/v1/events/glow-12345" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "cancelled": false, "client_name": "משפחת לוי" }'

"cancelled": false משחזר את האירוע (cancelled_at מתאפס) ושולח webhook event.updated. "cancelled": true זהה ל-DELETE. event_type לא מוכר נשמר כ-other.

אירוע מבוטל: ההזמנה לאורחים מציגה „האירוע בוטל” ואינה מקבלת אישורי הגעה, קישור הניהול של הלקוח נחסם והודעות מתוזמנות אינן נשלחות. מחיקה מהדשבורד (ביטול ומחיקה) שולחת event.cancelled; ניתן לשחזר מהדשבורד במשך 30 יום (נשלח event.updated), ולאחר מכן האירוע נמחק לצמיתות. מחיקה אוטומטית אחרי האירוע (לפי הגדרת העסק: 7/14/30/60 ימים אחרי מועד האירוע) שולחת event.cancelled עם "reason": "retention" ו-"deleted": true.

📡 Webhooks

בהגדרות העסק ניתן להגדיר כתובת HTTPS וסוד HMAC. הכתובת חייבת להיות שם דומיין ציבורי (לא כתובת IP, לא localhost או רשת פרטית). אנו לא עוקבים אחרי הפניות (redirect), וכל שליחה מוגבלת ל-10 שניות. אנו שולחים POST לכתובת עם:

X-Simchapp-Topic: event.created | rsvp.updated | event.updated | event.cancelled
X-Simchapp-Timestamp: <unix-seconds>
X-Simchapp-Signature-V2: sha256=<hex-hmac-of "timestamp.rawBody">
X-Simchapp-Signature: sha256=<hex-hmac-of-raw-body>   (ישן – נשמר לתאימות)

מומלץ לאמת את החתימה החדשה ולדחות בקשות שהחותמת שלהן ישנה מ-5 דקות:

const ts = req.headers["x-simchapp-timestamp"];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) throw ...;
const expected = "sha256=" + createHmac("sha256", SECRET).update(`${ts}.${rawBody}`).digest("hex");
if (!timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-simchapp-signature-v2"]))) throw ...

⚠️ שגיאות

{ "error": { "code": "invalid_phone", "message": "טלפון לקוח אינו תקין (ישראלי)" } }

קודים: unauthorized, invalid_key, rate_limited, bad_json, invalid_body, invalid_phone, not_found, deleted, db_error.