SPLITZ API - Node.js SDK

ספריית JavaScript רשמית לעבודה עם SPLITZ API - ניהול תשלומים ומנויים

תכונות

• ✅ תמיכה מלאה ב-TypeScript
• ✅ API ברור ואינטואיטיבי עם namespaces
• ✅ טיפול חכם בשגיאות עם error classes ייעודיים
• ✅ Validation אוטומטי של פרמטרים
• ✅ Authentication אוטומטי
• ✅ תיעוד מפורט עם דוגמאות

📚 תיעוד מלא

לתיעוד מפורט כולל מודלים, API reference ודוגמאות מתקדמות:

📖 API Documentation →

התקנה

npm install splitz-payments

או עם yarn:

yarn add splitz-payments

שימוש בסיסי

אתחול

const SplitzClient = require('splitz-payments');

const splitz = new SplitzClient({
  apiKey: 'your-api-key-here'
});

עם TypeScript

import SplitzClient from 'splitz-payments';

const splitz = new SplitzClient({
  apiKey: 'your-api-key-here',
  baseURL: 'https://api.splitz.co.il', // אופציונלי
  timeout: 30000 // אופציונלי - timeout בms
});

מבנה Subscription Object

כאשר אתה מקבל מנוי, האובייקט המוחזר מכיל את השדות הבאים:

{
  uid: string;                    // מזהה ייחודי
  status: string;                 // ACTIVE | CANCELLED | PAST_DUE | PAUSED
  subscriber_email: string;       // אימייל המנוי
  subscriber_name: string;        // שם המנוי
  order_uid: string;             // מזהה ההזמנה
  product_uid: string;           // מזהה התוכנית הנוכחית
  pending_plan_change?: {        // שינוי תוכנית מתוכנן (אופציונלי)
    current_product_uid: string;
    future_product_uid: string;
    future_product_name: string;
    effective_date: string;
    status: string;
  };
}

ראה תיעוד מלא של המודל →

API Reference

Subscriptions (מנויים)

שליפת מנוי

// שליפה לפי מזהה מנוי
const result = await splitz.subscriptions.get({
  subscription_uid: 'sub_xxx'
});

const sub = result.subscription;
console.log(sub.status);        // 'ACTIVE'
console.log(sub.product_uid);   // 'prod_xxx'

// בדיקה אם יש שינוי תוכנית מתוכנן
if (sub.pending_plan_change) {
  console.log('מעבר ל:', sub.pending_plan_change.future_product_name);
}

// או לפי אימייל לקוח ומזהה חנות
const result = await splitz.subscriptions.get({
  customer_email: '[email protected]',
  shop_uid: 'shop_xxx'
});

בקשה לשינוי תוכנית

const changeRequest = await splitz.subscriptions.requestProductChange({
  subscription_uid: 'sub_xxx',
  target_product_uid: 'prod_yyy',
  return_url: 'https://myapp.com/success'
});

// הפנה את הלקוח לעמוד האישור
console.log(changeRequest.data.approval_url);
console.log(changeRequest.data.prorated_amount); // סכום prorated
console.log(changeRequest.data.requires_payment); // true/false

פרמטרים שחוזרים ב-return_url:

// לאחר אישור, הלקוח מופנה ל:
// https://myapp.com/success?status=success&subscription_uid=sub_xxx&new_plan=Premium%20Plan&prorated_charge=50

// טיפול בפרמטרים:
const urlParams = new URLSearchParams(window.location.search);
if (urlParams.get('status') === 'success') {
  console.log('✅ שינוי הצליח!');
  console.log('מנוי:', urlParams.get('subscription_uid'));
  console.log('תוכנית:', decodeURIComponent(urlParams.get('new_plan')));
  console.log('סכום:', urlParams.get('prorated_charge'), '₪');
}

יצירת קישור לפורטל ניהול

const portal = await splitz.subscriptions.createManagementLink('sub_xxx');

// שלח ללקוח
console.log(portal.data.management_url); 
console.log(portal.data.expires_in_hours); // 24

Payment Links (קישורי תשלום)

יצירת קישור תשלום מותאם אישית

const paymentLink = await splitz.paymentLinks.generate({
  payment_link_uid: 'pl_xxx',
  customer_email: '[email protected]'
});

// שלח ללקוח את הקישור
console.log(paymentLink.url);
// https://app.splitz.co.il/pay-link/pl_xxx/token...

Success URL Callbacks

למנוי:

// הלקוח חוזר עם: ?subscription_uid=sub_xxx
const subscriptionUid = new URLSearchParams(window.location.search).get('subscription_uid');

לתשלום חד פעמי:

// מידע מפורט (כרטיס): ?uid=order_xxx&email=...&price=...&card_last_four=...&card_type=...
// או מידע בסיסי (PayPal): ?order_uid=order_xxx

const params = new URLSearchParams(window.location.search);
const orderUid = params.get('uid') || params.get('order_uid');

// אמת תשלום
const status = await splitz.orders.isPaid(orderUid);

Orders (הזמנות)

בדיקה האם הזמנה שולמה

const status = await splitz.orders.isPaid('order_xxx');

if (status.paid) {
  console.log('✅ ההזמנה שולמה');
} else {
  console.log('⏳ ההזמנה ממתינה לתשלום');
}

שליפת פרטי הזמנה

const response = await splitz.orders.get('order_xxx');
const order = response.order;

console.log('מזהה:', order.uid);
console.log('אימייל לקוח:', order.email);
console.log('מחיר:', order.price, order.currency);
console.log('סטטוס:', order.status);
console.log('שולם:', order.is_paid);
console.log('תאריך תשלום:', order.paid_at);
console.log('תאריך יצירה:', order.createdAt);

טיפול בשגיאות

הספרייה מספקת error classes ייעודיים:

const { errors } = require('splitz-payments');

try {
  const subscription = await splitz.subscriptions.get({
    subscription_uid: 'invalid_id'
  });
} catch (error) {
  if (error instanceof errors.NotFoundError) {
    console.error('מנוי לא נמצא');
  } else if (error instanceof errors.ValidationError) {
    console.error('שגיאת ולידציה:', error.field);
  } else if (error instanceof errors.AuthenticationError) {
    console.error('API key לא תקין');
  } else if (error instanceof errors.ForbiddenError) {
    console.error('אין הרשאה לגשת למשאב זה');
  } else if (error instanceof errors.SplitzAPIError) {
    console.error('שגיאת API:', error.message);
    console.error('סטטוס:', error.statusCode);
  }
}

סוגי שגיאות

• SplitzAPIError - שגיאה כללית מה-API
• ValidationError - פרמטרים לא תקינים
• AuthenticationError - API key לא תקין או חסר
• NotFoundError - משאב לא נמצא (404)
• ForbiddenError - אין הרשאה (403)

דוגמאות שימוש

תרחיש מלא - שינוי תוכנית

const SplitzClient = require('splitz-payments');

async function upgradePlan(subscriptionId, newPlanId) {
  const splitz = new SplitzClient({
    apiKey: process.env.SPLITZ_API_KEY
  });

  try {
    // 1. שלוף את המנוי הנוכחי
    const subscription = await splitz.subscriptions.get({
      subscription_uid: subscriptionId
    });

    console.log('מנוי נוכחי:', subscription.subscription.product_uid);

    // 2. צור בקשה לשינוי תוכנית
    const changeRequest = await splitz.subscriptions.requestProductChange({
      subscription_uid: subscriptionId,
      target_product_uid: newPlanId,
      return_url: 'https://myapp.com/plan-changed'
    });

    // 3. הפנה את הלקוח לעמוד האישור
    return {
      approvalUrl: changeRequest.data.approval_url,
      amount: changeRequest.data.prorated_amount,
      requiresPayment: changeRequest.data.requires_payment
    };

  } catch (error) {
    console.error('שגיאה בשינוי תוכנית:', error.message);
    throw error;
  }
}

// שימוש
upgradePlan('sub_xxx', 'prod_premium')
  .then(result => {
    console.log('הפנה את הלקוח ל:', result.approvalUrl);
  })
  .catch(console.error);

שליחת קישור תשלום ללקוח

async function sendPaymentLink(paymentLinkId, customerEmail) {
  const splitz = new SplitzClient({
    apiKey: process.env.SPLITZ_API_KEY
  });

  const link = await splitz.paymentLinks.generate({
    payment_link_uid: paymentLinkId,
    customer_email: customerEmail
  });

  // שלח את הקישור במייל / SMS
  await sendEmail(customerEmail, link.url);

  return link.url;
}

יצירת פורטל ניהול ללקוח

async function getCustomerPortal(subscriptionId) {
  const splitz = new SplitzClient({
    apiKey: process.env.SPLITZ_API_KEY
  });

  const portal = await splitz.subscriptions.createManagementLink(subscriptionId);

  return {
    url: portal.data.management_url,
    expiresAt: portal.data.expires_at
  };
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | Required | Your SPLITZ API key | | baseURL | string | https://api.splitz.co.il | API base URL | | timeout | number | 30000 | Request timeout (ms) |

TypeScript Support

הספרייה כוללת TypeScript definitions מלאות:

import SplitzClient, { 
  GetSubscriptionOptions,
  GetSubscriptionResponse,
  RequestProductChangeOptions
} from 'splitz-payments';

const splitz = new SplitzClient({ apiKey: 'key' });

const options: GetSubscriptionOptions = {
  subscription_uid: 'sub_xxx'
};

const result: GetSubscriptionResponse = await splitz.subscriptions.get(options);

תמיכה

• 📧 Email: [email protected]
• 📚 Documentation: https://docs.splitz.co.il
• 📖 API Documentation - תיעוד מלא עם מודלים
• 🐛 Issues: https://github.com/splitz/splitz-api/issues

License

MIT © SPLITZ

Made with ❤️ by SPLITZ