Daily Platform

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

חברו את העסקים שלכם לדיילי

בחרו Platform בהרשמה למערכת Daily, השלימו את פרטי הפלטפורמה והפעילו את המנוי עם אמצעי תשלום. במסך מפתחות API הפיקו מפתח ראשי עם platform:manage ועם הרשאות הפעולות שהפלטפורמה צריכה לבצע עבור העסקים. המפתח נשמר בשרת שלכם בלבד.

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

הקימו עסק מהשרת שלכם

שלחו POST /platform/businesses לבסיס ה־API, עם המפתח הראשי. שדות ניהול הפלטפורמה וחיבורי הסליקה נכתבים ב־camelCase; פעולות הנתונים הקיימות ממשיכות להשתמש ב־snake_case לפי התיעוד שלהן.

const managementKey = process.env.DAILY_PLATFORM_KEY!;
const apiBase = process.env.DAILY_API_BASE_URL!;
const operationId = crypto.randomUUID();
const response = await fetch(`${apiBase}/platform/businesses`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${managementKey}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': operationId,
  },
  body: JSON.stringify(merchantRegistration),
});
const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? 'לא הצלחנו להקים את העסק');
await saveDailyBusinessId(result.data.id);

merchantRegistration מגיע מטופס ההצטרפות שכבר קיים בפלטפורמה שלכם וכולל businessNameHe, מספר עוסק תקין בן תשע ספרות ב־businessIdentifier, businessType, address, city, ו־contact עם firstName, lastName, email, phone, idNumber. אימייל איש הקשר משמש למסמכים ולחיבור הסליקה; הוא אינו חשבון כניסה לדיילי. אפשר לצרף externalId לזיהוי אצלכם.

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

GET /platform/businesses מחזיר עד 50 עסקים ב־data.items. העבירו את data.nextCursor ב־cursor לעמוד הבא. GET /platform/businesses/{id} מחזיר גם חיבורים, מפתחות ללא סודות, מסמכים ובקשות תשלום אחרונים. PATCH לאותו נתיב מעדכן שם, כתובת ופרטי קשר.

הפיקו מפתח לכל עסק

שלחו POST /platform/businesses/{id}/api-keys עם name, expirationDays ו־permissions, כפי שמוגדר ב־OpenAPI. העניקו רק את הרשאות הנתונים הנדרשות; platform:manage אסורה למפתח עסק. אי אפשר להעניק הרשאה שאינה קיימת במפתח הראשי.

הסוד המלא מוחזר פעם אחת ב־data.key; שמרו אותו בכספת הסודות בשרת שלכם. רשימת המפתחות אינה חושפת אותו. אם התשובה אבדה, בדקו את הרשימה, בטלו את המפתח שלא נשמר והפיקו חדש. אל תנסו POST חוזר באופן עיוור. ניתן להחזיק עד עשרה מפתחות פעילים לעסק. הסביבה ותוקף המפתח ממשיכים לפעול כמו במפתחות Daily הרגילים.

לעדכון הרשאות שלחו PATCH /platform/businesses/{id}/api-keys/{keyId}/permissions עם permissions. גם כאן אין להעניק הרשאות שאין למפתח הראשי.

רשימת המפתחות זמינה ב־GET /platform/businesses/{id}/api-keys תחת data.items, יחד עם apiAccessActive ו־maximumActiveKeys.

לסיבוב מפתח שלחו POST /platform/businesses/{id}/api-keys/{keyId}/rotate עם confirmed: true; לביטול מיידי שלחו POST לאותו נתיב עם הסיומת /revoke וגוף confirmed: true. בסיבוב, המפתח הישן מקבל תקופת מעבר של עד 24 שעות בכפוף לתוקף המקורי. ביטול אינו מבטל תשלומים שכבר אומתו.

לחלופין, אפשר לפעול עם המפתח הראשי וכותרת X-Daily-Business-ID ובה מזהה העסק שקיבלתם. ההרשאות נשארות הרשאות המפתח הראשי והשרת מאמת שהעסק שייך לפלטפורמה הזו. אי אפשר לבחור עסק דרך גוף בקשה או דרך מפתח של עסק אחר.

חברו סליקה וצרו תשלום מתוך ההזמנה הקיימת

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

עם מפתח העסק:

1. עדכנו כתובת ופרטי בנק דרך PATCH /business/settings כשנדרש. פרטי הבנק מוגדרים בחוזה UpdateBusinessDto.
2. בררו אפשרויות ומצב חיבורים דרך GET /integrations/providers ו־GET /integrations.
3. לסליקת אשראי התחילו בקריאת GET /integrations/payme. שלחו בקשת אישור ב־POST /integrations/payme/approval-request או הקמת מוכר ב־POST /integrations/payme/sellers לפי מצב העסק והפרטים החסרים. פרטי זיהוי הספק חייבים להתאים לעסק ובעליו הרשומים. POST /integrations/payme/onboarding הוא מסלול השלמה חלופי כאשר fallbackAvailable=true; אין להפעילו אחרי הקמת מוכר מוצלחת. המשיכו לתשלום רק כאשר paymentReady=true. השלבים והמצבים.
4. לחיבור PayPal השתמשו ב־POST /integrations/paypal/onboarding. החיבור חוזר לעמוד אישור ציבורי, ללא צורך בהתחברות של בעל העסק לדיילי. אישור בדפדפן אינו הוכחה שהספק אישר סליקה; בררו את המצב ב־API.
5. צרו לקוח ומסמך באמצעות ה־API הקיים. client_request_id של המסמך צריך להישמר אצלכם לכל פעולה. אותו מזהה הזמנה יכול להתקיים בעסקים שונים בלי לערבב את המסמכים שלהם.
6. שלחו POST /payments/payme/payment-links או /payments/paypal/payment-links עם documentId של המסמך. הרשאות payments:write נדרשות. השימוש בסכום ובמסמך והבדיקה מול הספק נעשים במנגנון התשלומים הקיים של Daily.
7. החזירו לדפדפן רק את קישור התשלום שחזר. לאחר תשלום, עדכנו את ההזמנה שלכם רק לאחר בירור מצב הבקשה ב־API או עדכון חתום. בצעו עדכון הזמנה פעם אחת לפי מזהה תשלום שמור.

שתי חשבוניות פתוחות לאותו לקוח נשארות שתי בקשות תשלום עצמאיות. תשלום לאחת אינו משלם את האחרת. הפסקת מנוי עסק חוסמת פעולות חדשות דרך ה־API; קישורים קיימים וכסף שכבר התקבל ממשיכים לעבור אימות והשלמת מסמכים.

לרשות המסים השתמשו ב־GET /integrations/tax-authority לבירור מצב וב־POST /integrations/tax-authority/connect לקבלת קישור הזדהות. אפשר לנתק בנתיב /disconnect. למסמך שדורש החלטה או מספר הקצאה יש נתיבי POST /documents/{documentId}/tax-authority/decision ו־/allocation-number, עם הרשאת documents:write. ההרשאות הממשלתיות נשארות לכל עסק בנפרד.

חיבורי Morning ו־Maven זמינים בנתיבי /integrations/morning/connect ו־/integrations/maven/connect, עם DTO ההתחברות של כל חיבור. ניתן לנתק חיבור ב־POST /integrations/{providerKey}/disconnect, ולעדכן הגדרות סליקה וברירת מחדל לפי ה־OpenAPI.

קראו אומדן שימוש וחיובים

GET /platform במפתח הראשי מחזיר pricing, estimate, history, webhookUrl ו־subscriptionStatus. estimate עשוי להיות null; אחרת הוא כולל periodStart, periodEnd, items לכל עסק, usageAgorot, baseAgorot, totalAgorot ו־isEstimate. סכומי Agorot באגורות. history כולל עד 12 מחזורי חיוב עם totalAmount בשקלים ופירוט platformBreakdownJson שנשמר. אומדן אינו חיוב סופי; פעילות ושימוש עתידיים יכולים לשנות אותו.

קבלו עדכונים חתומים

הגדירו כתובת HTTPS ציבורית באמצעות POST /platform/webhook עם url. התשובה מחזירה סוד חתימה פעם אחת. הגדרה מחדש מסובבת את הסוד. אין תמיכה בכתובות פנימיות, הפניות HTTP, או שרתים שיש להם רק IPv6.

העדכונים כוללים payment.updated, integration.updated ו־document.created. גוף האירוע מכיל id, type, businessId ו־data מצומצם. הם נשלחים לאחר שהמצב נשמר בדיילי; המצב העדכני זמין ב־API גם אם עדכון התעכב. העדכונים מתארים מצב שמור, ולא יומן מלא של כל מצב ביניים.

אמתו חתימת HMAC SHA-256 על המחרוזת timestamp + '.' + rawBody באמצעות הסוד, מול X-Daily-Signature; זמן השליחה נמצא ב־X-Daily-Timestamp. השתמשו בהשוואה בזמן קבוע, דחו זמן ישן, ושמרו את X-Daily-Delivery-ID כדי למנוע עיבוד כפול. שמרו קודם את האירוע בתור שלכם והחזירו 2xx מהר. אין להסתמך על דף החזרה מהתשלום כראיה לתשלום.

Daily מנסה מסירה עד 12 פעמים, עם השהיה עולה והמתנה מרבית של יום בין ניסיונות. אין מעקב אחר redirects. GET /platform/webhook/deliveries מציג את המסירות האחרונות; אם הגעתם למגבלת הניסיונות, השלימו את המידע באמצעות קריאת מצב ב־API.

חיוב, מכסות והפסקת מנוי

דמי הפלטפורמה הם 299 ש״ח בחודש, החל מהפעלת המנוי. כל עסק פעיל עולה 19 ש״ח למחזור מלא, באופן יחסי לימי פעילות המנוי במחזור החיוב של הפלטפורמה. יום שבו המנוי היה פעיל בחלק מהיום נספר כיום; הפסקה וחידוש באותו יום אינם סופרים אותו פעמיים. העיגול מתבצע לאגורות פעם אחת לכל עסק.

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

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

הפסקת מנוי עסק: POST /platform/businesses/{id}/subscription עם active: false. חידוש: אותו נתיב עם active: true. פרטי העסק ומספר העוסק נשמרים. כישלון חיוב הפלטפורמה פועל לפי תקופת החסד הקיימת בדיילי; לאחריה פעולות חדשות נחסמות, אך מידע קיים נשאר זמין לקריאה דרך המפתחות התקפים.

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

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

מפתחות בדיקה עובדים בסביבת Daily לבדיקות, ומפתחות חיים בסביבה החיה. הכינו את חיבור הסליקה בסביבת הספק המתאימה; מפתח בדיקה אינו מחליף חיבור כזה.