שירותים וצוות
רשימת השירותים של העסק עם משך, מחיר וקיבולת, ורשימת אנשי הצוות עם השירותים שכל אחד נותן.
קריאהלמפתחים
חברו אתר, מערכת CRM, תוכנת הנהלה או מוצר שאתם בונים ליומן של עסק בחווה-לינק: שעות פנויות בזמן אמת, קביעה, הזזה וביטול של תורים, וניהול לקוחות. כל פעולה עוברת דרך אותם כללים שהעסק הגדיר בממשק הניהול.
מה אפשר לעשות
גרסה 1 של ה-API, בכתובת https://havalink.co.il/api/v1. בקשות ותשובות ב-JSON.
רשימת השירותים של העסק עם משך, מחיר וקיבולת, ורשימת אנשי הצוות עם השירותים שכל אחד נותן.
קריאההשעות הפנויות לשירות ביום מסוים, לפי שעות הפעילות, ההתראה מראש, החסימות והאירועים ביומן Google של הצוות.
קריאהקביעת תור בשם לקוח. התור נכנס ליומן, והלקוח מקבל אישור ותזכורות בערוצים שהעסק הגדיר, בדיוק כמו בתור שנקבע מהממשק.
תוריםהזזת תור לתאריך, שעה או איש צוות אחרים, וביטול עם סיבה. הלקוח מקבל עדכון.
תוריםשליפת התורים לטווח של עד 62 ימים, עם סינון לפי סטטוס או לקוח. מתאים לסנכרון, לדוחות ולמערכות הנהלת חשבונות.
קריאהחיפוש לקוח לפי שם או טלפון, יצירת לקוח חדש ועדכון פרטים, הערות, תגיות וחסימה.
לקוחותהכללים של העסק נשמרים. ה-API לא עוקף את הגדרות העסק. זמינות, חסימות, קיבולת, הודעות ללקוח ויומן הגישה עובדים בדיוק כמו בממשק הניהול.
למי זה מתאים
אתר שמציג שעות פנויות וקובע תורים בעיצוב שלו, CRM שמסנכרן לקוחות, או גיליון שמושך את היומן לדוחות.
מי שבונה אתרים ומערכות לעסקים יכול לחבר אותם לחווה-לינק בשם הלקוח, עם מפתח שהעסק יוצר ומנהל.
מוצר שעובד מעל יומן התורים של כמה עסקים. כל עסק מחבר את עצמו במפתח משלו, ויכול לבטל אותו בכל רגע.
איך מתחילים
Authorization.# the business and the key's permissions
curl https://havalink.co.il/api/v1/me \
-H "Authorization: Bearer tk_xxxxxxxx_your_secret"
הרשאות
הרשאת כתיבה כוללת תמיד גם קריאה. משתמש בעסק יכול לתת למפתח רק הרשאות שיש לו בעצמו בממשק הניהול.
| הרשאה | מה היא מאפשרת |
|---|---|
| read | שירותים, צוות, שעות פנויות, רשימת תורים ולקוחות. |
| appointments:write | קביעת תור, הזזה וביטול. הלקוח מקבל את אותן הודעות כמו בתור שנקבע מהממשק. |
| customers:write | יצירת לקוח ועדכון שם, דוא״ל, הערות, תגיות וחסימה. |
נקודות הקצה
תאריכים ושעות בבקשות הם בשעון המקומי של העסק: YYYY-MM-DD ו-HH:MM. בתשובות מופיעים גם startAt ו-endAt ב-UTC. רשימות חוזרות בעמודים של 100, עם hasMore.
| קריאה | הרשאה | מה היא עושה |
|---|---|---|
| העסק | ||
| GET /api/v1/me | כל מפתח | שם העסק, אזור הזמן, כתובת דף ההזמנה וההרשאות של המפתח. |
| GET /api/v1/services | read | השירותים: משך, מחיר, קיבולת, כמות מרבית, פעיל והזמנה אונליין. |
| GET /api/v1/staff | read | אנשי הצוות והשירותים שכל אחד נותן. |
| GET /api/v1/availability | read | שעות פנויות. serviceId ו-date חובה. אפשר גם staffId, quantity ו-branchId. |
| תורים | ||
| GET /api/v1/appointments | read | תורים בטווח from עד to, עד 62 ימים. סינון אופציונלי לפי status ו-customerId, ועמוד עם page. |
| GET /api/v1/appointments/:id | read | תור אחד. |
| POST /api/v1/appointments | appointments:write | קביעת תור. לקוח שעוד לא קיים נוצר לפי מספר הטלפון. מומלץ לשלוח Idempotency-Key. |
| POST /api/v1/appointments/:id/move | appointments:write | הזזה ל-date ו-time חדשים, ואפשר גם לאיש צוות אחר. |
| POST /api/v1/appointments/:id/cancel | appointments:write | ביטול, עם reason אופציונלי. |
| לקוחות | ||
| GET /api/v1/customers | read | חיפוש לפי שם או טלפון עם q, או התאמה מדויקת עם phone. |
| GET /api/v1/customers/:id | read | לקוח אחד, כולל תגיות, חסימה והסכמה לדיוור. |
| POST /api/v1/customers | customers:write | יצירת לקוח, או החזרת הלקוח הקיים לפי טלפון. לא דורס שם שהלקוח מילא בעצמו. |
| PATCH /api/v1/customers/:id | customers:write | עדכון שם פרטי ושם משפחה, דוא״ל, הערות, תגיות (עד 10) וחסימה. |
סטטוסים של תור: pending ממתין לאישור, confirmed מאושר, completed הושלם, no_show לא הגיע, cancelled בוטל.
תור שנקבע דרך ה-API נחשב תור שהלקוח קבע בעצמו: האישור עליו יוצא מיד, גם בשבת ובחג. רק ב-WhatsApp, וב-SMS שנשלח במקומו, הוא מחכה כמו שאר ההודעות.
ביטול או הזזה של תור דרך ה-API נחשבים פעולה של העסק. כשההגדרה "לא לשלוח הודעות שירות בשבת ובחג" דלוקה, ההודעה ללקוח מחכה כמו שאר הודעות השירות. היא יוצאת מיד, גם בשבת ובחג, כשמבטלים תור שמתקיים לפני שהודעות שמחכות יוצאות, או מזיזים תור שהמועד הקודם או החדש שלו מגיע לפני כן. התשובה של ה-API לא מציינת מתי ההודעה יוצאת. ב-WhatsApp, וב-SMS שנשלח במקומו, היא יוצאת גם מחוץ לשעות השליחה.
דוגמה
curl "https://havalink.co.il/api/v1/availability?serviceId=SERVICE_ID&date=2026-11-01" \
-H "Authorization: Bearer tk_xxxxxxxx_your_secret"
# 200
{ "date": "2026-11-01",
"slots": [ { "time": "10:30", "staffIds": ["STAFF_ID"] } ],
"reason": null }
curl -X POST https://havalink.co.il/api/v1/appointments \
-H "Authorization: Bearer tk_xxxxxxxx_your_secret" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f8e2a1c-7b4d-4e9a-9c11-2d5f6a7b8c90" \
-d '{"customer":{"phone":"0501234567","name":"Dana Levi"},
"serviceId":"SERVICE_ID","date":"2026-11-01",
"time":"10:30","notes":"Booked on our website"}'
// Node.js: this week's appointments
const res = await fetch('https://havalink.co.il/api/v1/appointments?from=2026-11-01&to=2026-11-07', {
headers: { Authorization: 'Bearer ' + process.env.HAVALINK_API_KEY },
});
const { appointments, hasMore } = await res.json();
בלי תורים כפולים. שלחו בכל קביעת תור כותרת Idempotency-Key עם מזהה UUID חדש, או requestId בגוף הבקשה. אם החיבור נפל ואתם שולחים שוב עם אותו מזהה ואותו תוכן, מתקבל אותו תור, בלי תור נוסף ובלי אישור נוסף ללקוח. אותו מזהה עם תוכן אחר מחזיר 409 עם idempotency_mismatch.
תור בשעה תפוסה מחזיר 409 עם "code": "slot_taken". השדה "force": true קובע גם מחוץ לשעות הפעילות, כמו קביעה ידנית בממשק.
אבטחה
שומרים רק גיבוב של המפתח. המפתח המלא מוצג פעם אחת ביצירה, ומפתח שאבד מבטלים ויוצרים חדש.
קריאה שמגיעה מדפדפן נדחית, כדי שמפתח לא יוטמע באתר ויודלף. קוראים ל-API רק מהשרת שלכם.
לכל מפתח אפשר לקבוע תוקף, ולהגביל אותו לעד 20 כתובות IP של השרתים שלכם.
עד 300 קריאות בדקה לכל מפתח. אחרי 20 ניסיונות אימות כושלים, הכתובת נחסמת לשעה.
כל קריאה שקוראת או משנה מידע של לקוחות נרשמת ביומן הגישה של העסק, עם המפתח שביצע אותה.
העסק רואה מתי כל מפתח היה בשימוש לאחרונה, ויכול לבטל אותו בלחיצה. עד 20 מפתחות פעילים לעסק.
שגיאות
שגיאה חוזרת כ-JSON עם error, הסבר בעברית, ולעיתים גם code קבוע שאפשר לבדוק בקוד.
| קוד | מתי |
|---|---|
| 400 | פרמטר חסר או לא תקין, למשל תאריך שלא בפורמט YYYY-MM-DD. |
| 401 | מפתח חסר, לא תקין, בוטל או שפג תוקפו. api_key_required, api_key_invalid, api_key_expired. |
| 403 | למפתח אין את ההרשאה (scope_required), הקריאה הגיעה מכתובת IP לא מורשית או מדפדפן, התוספת לא פעילה לעסק, או שהעסק לא פעיל. ביצירת מפתח בממשק הניהול: ניסיון לתת למפתח הרשאה שאין למשתמש (scope_not_grantable). |
| 404 | התור, הלקוח או השירות לא נמצאו בעסק. |
| 409 | התנגשות, למשל שעה שכבר נתפסה (slot_taken), או מזהה בקשה שכבר שימש לתוכן אחר (idempotency_mismatch). |
| 429 | יותר מדי קריאות (rate_limited). השדה retryAfterSec אומר כמה שניות לחכות לפני שמנסים שוב. |
מה בדרך
היכולות האלה עדיין לא זמינות. נשמח לשמוע מה הכי חשוב לכם.
הודעה מחווה-לינק לשרת שלכם ברגע שתור נקבע, זז או בוטל, חתומה כדי שתוכלו לוודא שהיא מאיתנו. עד אז אפשר למשוך את התורים של הימים הקרובים.
בפיתוח לקראת ההשקהסביבת ניסוי עם נתונים לדוגמה, לפיתוח ולבדיקות בלי לגעת ביומן אמיתי.
בפיתוח לקראת ההשקהחיבור באישור של בעל העסק (OAuth) למוצרים שעובדים עם עסקים רבים, בלי להעתיק מפתחות.
בפיתוח לקראת ההשקהה-API מצטרף לכל חבילה, בהצעת מחיר נפרדת. ספרו לנו מה אתם בונים, ונחזור אליכם עם הפרטים.