חיבור ראשון של פלטפורמה

חברו את תהליך ההצטרפות שכבר קיים אצלכם

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

לפני תחילת החיבור, פתחו חשבון Platform, הפעילו מנוי והפיקו מפתח ראשי. העניקו לו platform:manage וגם את ההרשאות שתאצילו לעסקים. לדוגמה: business:read, customers:read, customers:write, documents:read, documents:write, payments:read, payments:write, integrations:write.

שמרו בשרת DAILY_API_BASE_URL ו־DAILY_PLATFORM_KEY. מפתח בדיקה אינו מדמה אוטומטית חברת סליקה; גם חיבור הספק צריך להתאים לסביבה. עמוד Playground באתר התיעוד פונה לסביבה החיה. פרסום התיעוד אינו אישור שהופעלו אצלכם או בסביבה מסוימת כל החיבורים המופיעים בו.

1. שמרו פעולת הקמה ושלחו את פרטי העסק

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

{
  "businessNameHe": "סטודיו הדגמה",
  "businessIdentifier": "515990281",
  "businessType": "COMPANY_LTD",
  "address": "הארבעה 28",
  "city": "תל אביב",
  "contact": {
    "firstName": "נועה",
    "lastName": "לוי",
    "email": "finance@merchant.daily.test",
    "phone": "0525550128",
    "idNumber": "123456782"
  },
  "externalId": "merchant-1042"
}

businessType הוא OSEK_PATUR, OSEK_MURSHE, COMPANY_LTD או NON_PROFIT. מספר העוסק ותעודת הזהות חייבים לעבור בדיקת תקינות; מספר עוסק קיים אינו ניתן לרישום נוסף גם אם העסק הופסק. אימייל איש הקשר אינו משתמש כניסה.

פונקציה זו רצה בשרת, עם timeout ובלי להדפיס מפתחות או פרטי קשר:

const apiBase = process.env.DAILY_API_BASE_URL;
const platformKey = process.env.DAILY_PLATFORM_KEY;
if (!apiBase || !platformKey) throw new Error('חסרות הגדרות החיבור לדיילי');

async function daily<T>(path: string, key: string, method = 'GET', body?: unknown, idempotencyKey?: string): Promise<T> {
  const response = await fetch(`${apiBase}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${key}`,
      Accept: 'application/json',
      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(30000),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(`Daily ${response.status}: ${result.error?.code}; ${result.request_id}`);
  return result.data as T;
}

// Load these two values from your persisted onboarding operation.
declare const savedOperationId: string;
declare const savedMerchantRegistration: Record<string, unknown>;
const business = await daily<{ id: string; subscriptionActive: boolean }>(
  '/platform/businesses', platformKey, 'POST', savedMerchantRegistration, savedOperationId,
);

שמרו business.id לצד מזהה העסק שלכם לפני המשך החיבור. בתשובת ההקמה מתקבלים id, businessNameHe, businessIdentifier, createdAt ו־subscriptionActive. 409 business_identifier_exists דורש בירור של העסק הקיים; 409 resource_conflict על מזהה חוזר עם גוף שונה דורש תיקון הפעולה המקומית.

2. הפיקו מפתח לעסק ושמרו אותו בכספת

עם המפתח הראשי שלחו POST /platform/businesses/{id}/api-keys:

{
  "name": "חיבור ההזמנות",
  "expirationDays": 365,
  "permissions": [
    "business:read", "customers:read", "customers:write",
    "documents:read", "documents:write", "payments:read",
    "payments:write", "integrations:write"
  ]
}

תוקף מותר: 90, 180 או 365 ימים. platform:manage אסורה במפתח עסק. data.key הוא הסוד החד־פעמי; data.id הוא מזהה המפתח לניהול, ולא סוד אימות. שמרו את הסוד בכספת ואת מזהה המפתח ברשומת העסק. אם התשובה אבדה, השתמשו ברשימת המפתחות, בטלו את המפתח שלא נשמר והפיקו חדש. פעולה זו אינה idempotent.

בדקו את החיבור דרך GET /business עם מפתח העסק וודאו שהזהות תואמת לעסק שלכם. אפשר גם לפעול עם המפתח הראשי וכותרת X-Daily-Business-ID; במקרה זה נדרשות platform:manage והרשאת הפעולה. עם מפתח עסק אין לשלוח את הכותרת.

3. חברו סליקה לפי מצב העסק

לסליקת אשראי התחילו ב־GET /integrations/payme. השלימו את missingApprovalFields ואת פרטי הבנק דרך PATCH /business/settings. שלחו בקשת אישור או הקמת מוכר בהתאם למצב; פתחו השלמה בדפדפן רק כשה־API מציין שהיא נדרשת. אם העסק כבר paymentReady: true, אין להפעיל מחדש onboarding.

לחיבור PayPal שלחו POST /integrations/paypal/onboarding, העבירו data.redirectUrl לדפדפן, ואחרי הסכמת העסק בדקו GET /integrations/paypal. המשיכו לתשלום רק כאשר paymentReady: true. כל פעולות החיבור דורשות integrations:write; קריאת מצב דורשת business:read.

השלבים, פרטי הבנק ומצבי ההשלמה מופיעים ב־חיבור סליקה ותשלום להזמנה.

4. חברו את כפתור התשלום שלכם

בשרת שלכם צרו לקוח, מסמך וקישור תשלום מתוך ההזמנה השמורה. שמרו מיפוי של businessId, orderId, customerId, documentId ו־paymentRequestId. הסכום מגיע משורות ההזמנה בשרת; סכום שהגיע מהדפדפן אינו מקור אמת.

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

5. ודאו שהחיבור שלכם מוכן

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

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

הפעולות שהחוזה הציבורי אינו מספק

אין המרת חשבון רגיל ל־Platform, העברת עסק בין פלטפורמות, התחלת ייבוא Morning או Maven, החזר תשלום לקוח או API ציבורי מלא לקריאת בקשת תשלום לפי מזהה. GET /platform/businesses/{id} מספק רק את עשר בקשות התשלום האחרונות. אין לתרגם נתיבים פנימיים של ממשק Daily לנתיבי v1 עם מפתח API. השתמשו רק בפעולות ובמגבלות המתוארות ב־המפרט המלא.