תיעוד API | RealPayment

🚀 התחלה מהירה

כדי להתחיל להשתמש ב-API, תצטרך:

ליצור API Key בדף ההגדרות (הגדרות → API)
לשמור את ה-API Key במקום מאובטח (מוצג פעם אחת בלבד!)
להוסיף את ה-API Key לכל בקשה ב-header: X-API-Key

Base URL

https://us-central1-yakirvakninpayment.cloudfunctions.net/api

אלטרנטיבה (Hosting): https://realpayment.co.il/api

🔗 מדריך התממשקות למערכות חיצוניות

מדריך מלא לחיבור CRM, אתרי E-commerce, מערכות ניהול ומערכות חיצוניות אחרות.

שלב 1 — קבלת API Key

היכנס ל-RealPayment → הגדרות → API
לחץ "צור API Key חדש"
העתק את המפתח (מוצג פעם אחת!) ושמור אותו בצורה מאובטחת

שלב 2 — Headers חובה

X-API-Key: rp_live_YOUR_API_KEY
Content-Type: application/json
            

שלב 3 — Endpoints מרכזיים לפי שימוש

שימוש	Endpoint	Method
יצירת קישור תשלום	`/external/create-payment`	POST
יצירת חשבונית	`/external/create-invoice`	POST
יצירת הצעת מחיר	`/external/create-quote`	POST
יצירת קבלה	`/external/create-receipt`	POST
ניהול לקוחות	`/external/customers`	GET/POST/PUT
תהליך מכירה אוטומטי	`/external/sales-process/activate`	POST
סטטוס תשלום	`/external/payment-status/:paymentId`	GET
אנליטיקס	`/external/analytics`	GET

שלב 4 — Webhooks (אופציונלי)

הגדר webhookUrl ב-create-payment כדי לקבל עדכוני סטטוס אוטומטית (completed/failed).

📥 Swagger / OpenAPI

הורד את מפרט ה-API בפורמט OpenAPI 3.0 לשימוש ב-Swagger UI, Postman, או כלי פיתוח אחר.

⬇️ הורד realpayment-api-swagger.json

גרסה: 0.1 | עודכן: 2026-03-03

🔐 אימות (Authentication)

כל בקשה ל-API חייבת לכלול את ה-API Key ב-header:

Headers:
  X-API-Key: rp_live_YOUR_API_KEY_HERE
  Content-Type: application/json

⚠️ חשוב: שמור את ה-API Key במקום מאובטח ואל תחשוף אותו בקוד Frontend!

💳 Payments API

POST /external/create-payment

תיאור: יצירת קישור תשלום חדש

פרמטרים (Body):

שם	סוג	חובה	תיאור
`amount`	number	כן	סכום התשלום (₪), 1 - 10,000,000
`description`	string	כן	תיאור התשלום
`customerName`	string	לא	שם הלקוח
`customerPhone`	string	לא	טלפון הלקוח (פורמט: 05XXXXXXXX)
`customerEmail`	string	לא	אימייל הלקוח
`numOfPayments`	number	לא	מספר תשלומים (1-36, ברירת מחדל: 1)
`currency`	string	לא	מטבע (ברירת מחדל: ILS)
`webhookUrl`	string	לא	URL לקבלת עדכוני סטטוס
`metadata`	object	לא	מידע נוסף (יוחזר ב-webhook)
`recurringData`	object	לא	הגדרות תשלום חוזר אוטומטי (ראה פירוט למטה) חדש

🔄 תשלום חוזר אוטומטי (recurringData):

כדי ליצור תשלום חוזר, העבר אובייקט recurringData עם השדות הבאים:

שם	סוג	חובה	תיאור
`isAutoRecurringPayment`	boolean	כן	חייב להיות `true` להפעלת תשלום חוזר
`frequency`	string	כן	תדירות: "daily", "weekly", "monthly", "yearly"
`interval`	number	כן	כל כמה (לדוגמה: 1 = כל חודש, 2 = כל חודשיים)
`totalBills`	number	כן	מספר חיובים כולל (0 = ללא הגבלה)
`startDate`	string	כן	תאריך חיוב ראשון (פורמט: YYYY-MM-DD)

תגובה מוצלחת (200):

קישור הוראת קבע: כאשר recurringData נשלח, ה-paymentUrl יכלול &recurring=1 — כך הלקוח יראה בדף התשלום סימן "הוראת קבע" ויבין שהכרטיס יחויב אוטומטית.

{
  "success": true,
  "paymentUrl": "https://yakirvakninpayment.web.app/payment.html?url=...&returnValue=...&recurring=1",
  "directUrl": "https://secure.cardcom.solutions/...",
  "returnValue": "EXT_abc12345_1704123456789_x7y8z9",
  "paymentId": "PAYMENT_DOC_ID",
  "lowProfileId": "CARDCOM_PROFILE_ID",
  "amounts": {
    "base": 100,
    "commission": 2.5,
    "final": 102.5,
    "currency": "ILS"
  },
  "commission": {
    "percent": 2.5,
    "amount": 2.5
  },
  // אם זה תשלום חוזר:
  "recurringPaymentId": "RECURRING_DOC_ID",
  "recurringId": "CARDCOM_RECURRING_ID",
  "recurring": {
    "frequency": "monthly",
    "interval": 1,
    "totalBills": 12,
    "startDate": "2025-02-01"
  }
}

דוגמה - תשלום חוזר חודשי:

{
  "amount": 100,
  "description": "מנוי חודשי",
  "customerName": "יוסי כהן",
  "customerPhone": "0501234567",
  "customerEmail": "yossi@example.com",
  "recurringData": {
    "isAutoRecurringPayment": true,
    "frequency": "monthly",
    "interval": 1,
    "totalBills": 12,
    "startDate": "2025-02-01"
  }
}

GET /external/payment-status/:paymentId חדש

תיאור: בדיקת סטטוס תשלום לפי מזהה

תגובה מוצלחת (200):

{
  "success": true,
  "payment": {
    "id": "PAYMENT_ID",
    "status": "completed",
    "amount": 102.5,
    "baseAmount": 100,
    "commission": { "percent": 2.5, "amount": 2.5 },
    "description": "תשלום עבור שירות",
    "customerName": "דני כהן",
    "customerEmail": "danny@example.com",
    "returnValue": "EXT_abc12345_...",
    "transactionId": "CARDCOM_TXN_ID",
    "createdAt": "2025-12-28T10:00:00Z",
    "completedAt": "2025-12-28T10:05:00Z",
    "source": "external_api"
  }
}

GET /external/analytics חדש

תיאור: קבלת סטטיסטיקות שימוש ב-API

Query Parameters:

שם	סוג	ברירת מחדל	תיאור
`days`	number	30	מספר ימים להציג (מקסימום 90)

תגובה מוצלחת (200):

{
  "success": true,
  "analytics": {
    "period": {
      "days": 30,
      "from": "2025-11-28T00:00:00Z",
      "to": "2025-12-28T23:59:59Z"
    },
    "calls": {
      "total": 150,
      "successful": 142,
      "failed": 8,
      "successRate": 94.7
    },
    "revenue": {
      "periodCommission": 425.50,
      "lifetimeCommission": 1250.00,
      "currency": "ILS"
    },
    "wallet": {
      "balance": -425.50,
      "status": "active",
      "paymentThreshold": 100,
      "creditLimit": 500
    },
    "daily": {
      "2025-12-28": { "calls": 5, "success": 5, "failed": 0, "revenue": 12.50 }
    },
    "recentCalls": [...]
  }
}

POST /external/webhook/test חדש

תיאור: שליחת webhook לבדיקה

פרמטרים (Body):

שם	סוג	תיאור
`testUrl`	string	URL לבדיקה (אופציונלי, אחרת משתמש ב-webhook המוגדר)

📄 Documents API (External)

יצירה, שליפה, עדכון ושליחת מסמכים דרך External API

POST /external/create-invoice

תיאור: יצירת חשבונית מס חדשה

פרמטרים (Body):

שם	סוג	חובה	תיאור
`customerName`	string	כן	שם הלקוח
`customerPhone`	string	לא	טלפון
`customerEmail`	string	לא	אימייל
`items`	array	כן	פריטים [{description, quantity, price}]
`notes`	string	לא	הערות
`dueDate`	string	לא	תאריך לתשלום (YYYY-MM-DD)

תגובה:

{
  "success": true,
  "invoiceId": "inv_123456789_abc",
  "invoiceNumber": "INV-2025-000001",
  "pdfUrl": "https://storage.../invoice.pdf",
  "totalAmount": 1180
}

POST /external/create-quote

תיאור: יצירת הצעת מחיר חדשה

פרמטרים (Body):

שם	סוג	חובה	תיאור
`customerName`	string	כן	שם הלקוח
`customerPhone`	string	לא	טלפון
`customerEmail`	string	לא	אימייל
`items`	array	כן	פריטים [{description, quantity, price}]
`notes`	string	לא	הערות
`validUntil`	string	לא	תוקף ההצעה (YYYY-MM-DD)

תגובה:

{
  "success": true,
  "quoteId": "quote_123456789_abc",
  "quoteNumber": "Q-2025-000001",
  "pdfUrl": "https://storage.../quote.pdf",
  "totalAmount": 1180
}

POST /external/create-receipt

תיאור: יצירת קבלה חדשה

פרמטרים (Body):

שם	סוג	חובה	תיאור
`customerName`	string	כן	שם הלקוח
`amount`	number	כן	סכום
`description`	string	לא	תיאור
`paymentMethod`	string	לא	אמצעי תשלום

GET /external/documents

תיאור: קבלת רשימת כל המסמכים

Query Parameters:

שם	סוג	ברירת מחדל	תיאור
`type`	string	-	סינון לפי סוג (invoice/quote/receipt)
`limit`	number	50	מספר תוצאות (מקסימום 100)

GET /external/document/:id

תיאור: קבלת מסמך בודד

PUT /external/document/:id חדש

תיאור: עדכון פרטי מסמך (לא ניתן לשנות סכומים)

פרמטרים (Body):

שם	סוג	תיאור
`customerName`	string	שם לקוח חדש
`customerPhone`	string	טלפון חדש
`customerEmail`	string	אימייל חדש
`notes`	string	הערות
`status`	string	סטטוס (draft/sent/viewed/cancelled)

DELETE /external/document/:id

תיאור: מחיקת מסמך

POST /external/document/:id/send חדש

תיאור: שליחת מסמך ללקוח ב-WhatsApp או Email

פרמטרים (Body):

שם	סוג	חובה	תיאור
`channel`	string	כן	"whatsapp" או "email"
`phone`	string	*	טלפון (חובה אם channel=whatsapp)
`email`	string	*	אימייל (חובה אם channel=email)
`message`	string	לא	הודעה מותאמת אישית

תגובה:

{
  "success": true,
  "message": "Document sent successfully via WhatsApp",
  "sentVia": "whatsapp",
  "sentTo": "972501234567",
  "documentNumber": "INV-2025-000001"
}

👥 Customers API חדש

ניהול לקוחות - יצירה, עדכון, וחיפוש

POST /external/customers

תיאור: יצירת לקוח חדש

פרמטרים (Body):

שם	סוג	חובה	תיאור
`name`	string	כן	שם הלקוח
`phone`	string	*	טלפון (חובה אם אין email)
`email`	string	*	אימייל (חובה אם אין phone)
`address`	string	לא	כתובת
`company`	string	לא	שם חברה
`taxId`	string	לא	ח.פ/ע.מ
`notes`	string	לא	הערות

תגובה:

{
  "success": true,
  "customerId": "cust_1706123456789_abc123",
  "customer": {
    "id": "cust_1706123456789_abc123",
    "name": "ישראל ישראלי",
    "phone": "0501234567",
    "email": "israel@example.com",
    "company": "חברה בע\"מ",
    "createdAt": "2025-01-28T10:00:00.000Z"
  }
}

GET /external/customers

תיאור: קבלת רשימת לקוחות

Query Parameters:

שם	סוג	ברירת מחדל	תיאור
`limit`	number	50	מספר תוצאות (מקסימום 100)
`search`	string	-	חיפוש לפי שם/טלפון/אימייל

GET /external/customers/:id

תיאור: קבלת פרטי לקוח בודד

PUT /external/customers/:id

תיאור: עדכון פרטי לקוח

ניתן לעדכן כל שדה בנפרד (name, phone, email, address, company, taxId, notes)

✍️ Signatures API

יצירת קישורי חתימה דיגיטלית להצעות מחיר

POST /external/create-signature-link

תיאור: יצירת קישור לחתימה דיגיטלית על הצעת מחיר

פרמטרים (Body):

שם	סוג	חובה	תיאור
`documentId`	string	כן	מזהה הצעת המחיר
`signerName`	string	לא	שם החותם
`signerPhone`	string	לא	טלפון החותם

תגובה:

{
  "success": true,
  "signatureLink": "https://realpayment.co.il/sign?doc=xxx&token=yyy",
  "expiresAt": "2025-02-04T10:00:00.000Z"
}

GET /external/document/:id/signature-status

תיאור: בדיקת סטטוס חתימה

תגובה:

{
  "success": true,
  "documentId": "quote_123456789",
  "documentNumber": "Q-2025-000001",
  "signatureStatus": "signed",
  "signedAt": "2025-01-28T14:30:00.000Z",
  "signerName": "ישראל ישראלי",
  "signatureUrl": "https://storage.../signature.png"
}

📄 Documents API (Internal)

API ליצירת מסמכים עם Firebase Authentication (לשימוש פנימי)

POST /api/documents-v2/create חדש

תיאור: יצירת מסמך PDF מקצועי (קבלה/חשבונית/הצעת מחיר/חשבונית-קבלה)

⚠️ אימות: endpoint זה דורש Firebase Authentication Token בנוסף ל-API Key

Headers:

Authorization: Bearer FIREBASE_ID_TOKEN
X-API-Key: rp_live_YOUR_API_KEY_HERE
Content-Type: application/json

פרמטרים (Body):

שם	סוג	חובה	תיאור
`type`	string	כן	סוג מסמך: "receipt", "invoice", "quote", "invoice_receipt"
`customerName`	string	כן	שם הלקוח (2-200 תווים)
`customerPhone`	string	לא	טלפון הלקוח
`customerEmail`	string	לא	אימייל הלקוח
`amount`	number	תלוי בסוג	סכום (חובה עבור receipt, אופציונלי עבור invoice/quote)
`description`	string	לא	תיאור התשלום/שירות
`items`	array	תלוי בסוג	רשימת פריטים (חובה עבור invoice, אופציונלי עבור quote)
`notes`	string	לא	הערות נוספות
`validUntil`	string	לא	תוקף (עבור quote, פורמט: YYYY-MM-DD)
`discount`	number	לא	הנחה בשקלים (עבור invoice/quote)
`vatRate`	number	לא	אחוז מע"מ (ברירת מחדל: 18)
`paymentId`	string	לא	מזהה תשלום קיים (לקישור מסמך לתשלום)

מבנה items[] (עבור invoice/quote):

[
  {
    "description": "תיאור הפריט",
    "quantity": 1,
    "price": 100.00,
    "total": 100.00
  }
]

תגובה מוצלחת (200):

{
  "success": true,
  "documentId": "doc_1704123456789_x7y8z9",
  "documentNumber": "RS-2025-001",
  "documentType": "receipt",
  "pdfUrl": "https://storage.googleapis.com/.../document.pdf",
  "createdAt": "2025-01-12T10:30:00Z",
  "status": "ready"
}

דוגמה 1 - קבלה פשוטה:

{
  "type": "receipt",
  "customerName": "דני כהן",
  "customerPhone": "0501234567",
  "customerEmail": "danny@example.com",
  "amount": 150.00,
  "description": "תשלום עבור שירות ייעוץ",
  "notes": "תשלום התקבל במזומן"
}

דוגמה 2 - חשבונית עם פריטים:

{
  "type": "invoice",
  "customerName": "חברת ABC בע\"מ",
  "customerPhone": "0501234567",
  "customerEmail": "info@abc.co.il",
  "items": [
    {
      "description": "שירות פיתוח אתר",
      "quantity": 1,
      "price": 5000.00,
      "total": 5000.00
    },
    {
      "description": "אחסון שנתי",
      "quantity": 1,
      "price": 500.00,
      "total": 500.00
    }
  ],
  "discount": 200,
  "vatRate": 18,
  "notes": "תשלום עד 30 ימים"
}

דוגמה 3 - הצעת מחיר:

{
  "type": "quote",
  "customerName": "יוסי לוי",
  "customerPhone": "0507654321",
  "customerEmail": "yossi@example.com",
  "items": [
    {
      "description": "מערכת ניהול לקוחות",
      "quantity": 1,
      "price": 10000.00,
      "total": 10000.00
    }
  ],
  "validUntil": "2025-02-28",
  "notes": "ההצעה כוללת הטמעה ואימון"
}

שגיאות נפוצות:

קוד	תיאור
400	חסרים שדות חובה (type, customerName, amount/items)
401	חסר Firebase Auth Token
503	יצירת PDF ארכה יותר מדי (timeout)
500	שגיאה ביצירת PDF או שמירה

🔄 Sales Process API חדש

ניהול תהליכי מכירה אוטומטיים - מהצעת מחיר ועד קבלה

🔄 זרימה אוטומטית: הצעת מחיר → חתימה דיגיטלית → קישור תשלום → תשלום → קבלה
כל שלב כולל שליחת הודעת WhatsApp אוטומטית ללקוח

⚠️ אימות: כל ה-endpoints דורשים Firebase Authentication Token

GET /api/sales-process/templates

תיאור: קבלת רשימת תבניות תהליכי מכירה

תגובה מוצלחת:

{
  "success": true,
  "templates": [
    {
      "id": "template_123",
      "name": "תהליך מכירה סטנדרטי",
      "description": "הצעת מחיר → חתימה → תשלום → קבלה",
      "steps": ["quote", "signature", "payment", "receipt"],
      "isActive": true,
      "createdAt": "2025-01-28T10:00:00Z"
    }
  ]
}

POST /api/sales-process/templates

תיאור: יצירת תבנית תהליך מכירה חדשה

פרמטרים:

שם	סוג	חובה	תיאור
name	string	כן	שם התבנית
description	string	לא	תיאור התבנית
steps	array	כן	שלבים: ["quote", "signature", "payment", "receipt"]
whatsappMessages	object	לא	הודעות מותאמות לכל שלב

GET /api/sales-process/list

תיאור: רשימת כל תהליכי המכירה הפעילים

Query Parameters:

שם	סוג	ברירת מחדל	תיאור
status	string	-	סינון לפי סטטוס
limit	number	50	מספר תוצאות

סטטוסים אפשריים:

STARTED - התחיל, ממתין לחתימה
QUOTE_SIGNED - נחתם, ממתין לתשלום
PAYMENT_COMPLETED - שולם, ממתין לקבלה
COMPLETED - הושלם
FAILED - נכשל
CANCELLED - בוטל

POST /api/sales-process/activate

תיאור: הפעלת תהליך מכירה חדש עבור לקוח

פרמטרים:

שם	סוג	חובה	תיאור
templateId	string	כן	מזהה התבנית
customerName	string	כן	שם הלקוח
customerPhone	string	כן	טלפון (05XXXXXXXX)
price	number	כן	מחיר (מספר חיובי)
productName	string	לא	שם המוצר/שירות

תגובה מוצלחת:

{
  "success": true,
  "processId": "sp_1706446800000_abc123",
  "status": "STARTED",
  "currentStep": 1,
  "quoteId": "QT-2025-000001",
  "message": "תהליך מכירה הופעל בהצלחה"
}

דוגמה:

{
  "templateId": "template_123",
  "customerName": "ישראל ישראלי",
  "customerPhone": "0501234567",
  "price": 1000,
  "productName": "חבילת שירות פרימיום"
}

POST /api/sales-process/cancel

תיאור: ביטול תהליך מכירה פעיל

פרמטרים:

שם	סוג	חובה	תיאור
processId	string	כן	מזהה התהליך לביטול
reason	string	לא	סיבת הביטול

תגובה מוצלחת:

{
  "success": true,
  "message": "תהליך בוטל בהצלחה"
}

🔄 זרימת אירועים אוטומטית

activate → נוצרת הצעת מחיר + נשלחת הודעת WhatsApp עם קישור חתימה
חתימה → מזוהה אוטומטית → נוצר קישור תשלום + נשלחת הודעת WhatsApp
תשלום → מזוהה אוטומטית (Webhook) → נוצרת קבלה + נשלחת הודעת WhatsApp עם PDF
סטטוס → מתעדכן אוטומטית: COMPLETED

🌐 External API (X-API-Key)

🔑 אימות: כל ה-endpoints הבאים דורשים X-API-Key header (לאינטגרציות חיצוניות)

POST /external/sales-process/activate חדש

תיאור: הפעלת תהליך מכירה ממערכת חיצונית (CRM, E-commerce וכו')

פרמטרים:

שם	סוג	חובה	תיאור
customerName	string	כן	שם הלקוח
customerPhone	string	כן	טלפון (05XXXXXXXX)
price	number	כן	מחיר (מספר חיובי)
productName	string	לא	שם המוצר/שירות
customerEmail	string	לא	אימייל הלקוח
templateId	string	לא	מזהה תבנית (ברירת מחדל: תבנית ראשית)
metadata	object	לא	מידע נוסף (יוחזר ב-status)

תגובה מוצלחת:

{
  "success": true,
  "processId": "sp_1706446800000_abc123",
  "status": "STARTED",
  "currentStep": 1,
  "quoteId": "QT-2025-000001",
  "message": "Sales process activated successfully. Quote sent to customer via WhatsApp.",
  "nextStep": "Waiting for customer signature"
}

GET /external/sales-process/status/:processId חדש

תיאור: קבלת סטטוס מלא של תהליך מכירה

תגובה מוצלחת:

{
  "success": true,
  "process": {
    "id": "sp_1706446800000_abc123",
    "status": "COMPLETED",
    "currentStep": 4,
    "customerName": "ישראל ישראלי",
    "productName": "חבילת שירות",
    "price": 1000,
    "quoteNumber": "QT-2025-000001",
    "receiptNumber": "RC-2025-000001",
    "receiptPdfUrl": "https://storage.../receipt.pdf",
    "activityLog": [...]
  }
}

GET /external/sales-process/list חדש

תיאור: רשימת כל תהליכי המכירה

Query Parameters:

שם	סוג	ברירת מחדל	תיאור
status	string	-	סינון לפי סטטוס
limit	number	50	מספר תוצאות (מקסימום 100)

💻 דוגמאות קוד

Node.js

Python

PHP

JavaScript (fetch)

cURL

const axios = require('axios');

const API_KEY = 'rp_live_YOUR_API_KEY_HERE';
const BASE_URL = 'https://us-central1-yakirvakninpayment.cloudfunctions.net/api';

async function createPayment(amount, description, customerName) {
  try {
    const response = await axios.post(
      `${BASE_URL}/external/create-payment`,
      {
        amount,
        description,
        customerName,
        customerEmail: 'customer@example.com'
      },
      {
        headers: {
          'X-API-Key': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Payment URL:', response.data.paymentUrl);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}

// Usage - תשלום רגיל
createPayment(100, 'תשלום עבור שירות', 'דני כהן');

// Usage - תשלום חוזר חודשי (12 חודשים)
async function createRecurringPayment() {
  const response = await axios.post(
    `${BASE_URL}/external/create-payment`,
    {
      amount: 99,
      description: 'מנוי חודשי',
      customerName: 'יוסי כהן',
      customerPhone: '0501234567',
      customerEmail: 'yossi@example.com',
      recurringData: {
        isAutoRecurringPayment: true,
        frequency: 'monthly',
        interval: 1,
        totalBills: 12,
        startDate: '2025-02-01'
      }
    },
    {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );
  
  console.log('Recurring Payment ID:', response.data.recurringPaymentId);
  console.log('Payment URL:', response.data.paymentUrl);
}

import requests

API_KEY = 'rp_live_YOUR_API_KEY_HERE'
BASE_URL = 'https://us-central1-yakirvakninpayment.cloudfunctions.net/api'

def create_payment(amount, description, customer_name):
    headers = {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
    }
    
    payload = {
        'amount': amount,
        'description': description,
        'customerName': customer_name,
        'customerEmail': 'customer@example.com'
    }
    
    response = requests.post(
        f'{BASE_URL}/external/create-payment',
        json=payload,
        headers=headers
    )
    
    if response.status_code == 200:
        data = response.json()
        print(f"Payment URL: {data['paymentUrl']}")
        return data
    else:
        print(f"Error: {response.json()}")
        return None

# Usage
create_payment(100, 'תשלום עבור שירות', 'דני כהן')

<?php

$API_KEY = 'rp_live_YOUR_API_KEY_HERE';
$BASE_URL = 'https://us-central1-yakirvakninpayment.cloudfunctions.net/api';

function createPayment($amount, $description, $customerName) {
    global $API_KEY, $BASE_URL;
    
    $payload = json_encode([
        'amount' => $amount,
        'description' => $description,
        'customerName' => $customerName,
        'customerEmail' => 'customer@example.com'
    ]);
    
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $BASE_URL . '/external/create-payment',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $payload,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $API_KEY,
            'Content-Type: application/json'
        ]
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    $data = json_decode($response, true);
    
    if ($httpCode === 200 && $data['success']) {
        echo "Payment URL: " . $data['paymentUrl'];
        return $data;
    } else {
        echo "Error: " . ($data['error'] ?? 'Unknown error');
        return null;
    }
}

// Usage
createPayment(100, 'תשלום עבור שירות', 'דני כהן');
?>

const API_KEY = 'rp_live_YOUR_API_KEY_HERE';
const BASE_URL = 'https://us-central1-yakirvakninpayment.cloudfunctions.net/api';

async function createPayment(amount, description, customerName) {
  const response = await fetch(`${BASE_URL}/external/create-payment`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount,
      description,
      customerName,
      customerEmail: 'customer@example.com'
    })
  });
  
  const data = await response.json();
  
  if (data.success) {
    console.log('Payment URL:', data.paymentUrl);
    return data;
  } else {
    console.error('Error:', data.error);
    throw new Error(data.error);
  }
}

// Usage
createPayment(100, 'תשלום עבור שירות', 'דני כהן');

# תשלום רגיל
curl -X POST \
  'https://us-central1-yakirvakninpayment.cloudfunctions.net/api/external/create-payment' \
  -H 'X-API-Key: rp_live_YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 100,
    "description": "תשלום עבור שירות",
    "customerName": "דני כהן",
    "customerEmail": "customer@example.com"
  }'

# תשלום חוזר חודשי
curl -X POST \
  'https://us-central1-yakirvakninpayment.cloudfunctions.net/api/external/create-payment' \
  -H 'X-API-Key: rp_live_YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 99,
    "description": "מנוי חודשי",
    "customerName": "יוסי כהן",
    "customerPhone": "0501234567",
    "customerEmail": "yossi@example.com",
    "recurringData": {
      "isAutoRecurringPayment": true,
      "frequency": "monthly",
      "interval": 1,
      "totalBills": 12,
      "startDate": "2025-02-01"
    }
  }'

📋 קודי תגובה

קוד	משמעות	תיאור
200	Success	הבקשה הצליחה
400	Bad Request	פרמטרים חסרים או לא תקינים
401	Unauthorized	API Key חסר או לא תקין
403	Forbidden	אין הרשאה (מסגרת אשראי נחרגה / חשבון מושעה)
429	Too Many Requests	חריגה ממגבלת Rate Limit
500	Server Error	שגיאת שרת - נסה שוב מאוחר יותר

🔔 Webhooks

אם הגדרת Webhook URL, תקבל עדכונים אוטומטיים על סטטוס התשלומים:

אירועים:

payment.completed - תשלום הושלם בהצלחה
payment.failed - תשלום נכשל
payment.expired - קישור פג תוקף
payment.test - Webhook לבדיקה

מבנה Webhook:

{
  "event": "payment.completed",
  "paymentId": "PAYMENT_DOC_ID",
  "returnValue": "EXT_abc12345_1704123456789_x7y8z9",
  "amount": 102.5,
  "baseAmount": 100,
  "commission": { "percent": 2.5, "amount": 2.5 },
  "customerName": "דני כהן",
  "customerEmail": "danny@example.com",
  "transactionId": "CARDCOM_TXN_ID",
  "timestamp": "2025-12-28T10:30:00Z",
  "metadata": { ... }
}

Headers:

X-RealPayment-Event: payment.completed
X-RealPayment-Signature: sha256=...
Content-Type: application/json

אימות Signature (Node.js):

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSig = 'sha256=' + 
    crypto.createHmac('sha256', secret)
          .update(JSON.stringify(payload))
          .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSig)
  );
}

⚡ Rate Limits

Endpoint	מגבלה	חלון זמן
כל ה-External API	100 בקשות	דקה (per API Key)
Portal API	100 בקשות	דקה (per API Key)
Public Payment Status	30 בקשות	דקה (per IP)

Headers בתגובה:

X-RateLimit-Limit: 100          // מגבלה מקסימלית
X-RateLimit-Remaining: 95       // בקשות שנותרו
X-RateLimit-Reset: 1706446860   // Unix timestamp לאיפוס

כאשר חורגים מהמגבלה, תקבלו תגובת 429 Too Many Requests עם header Retry-After.

💰 עמלות

על כל תשלום מוצלח, העמלה שהוגדרה ב-API Key שלך מתווספת לסכום שהלקוח משלם.

דוגמה:

סכום מקורי: ₪100
עמלה: 2.5%
סכום עמלה: ₪2.50
סכום סופי (שהלקוח משלם): ₪102.50

העמלה מתווספת ליתרת הארנק שלך. ניתן לעקוב אחרי היתרה בפורטל הלקוחות או דרך ה-/external/analytics endpoint.

💡 טיפ: ניתן להגדיר עמלה 0% או להשאיר ריק אם לא רוצים לגבות עמלה.

💬 תמיכה

שאלות? בעיות? צור קשר:

📧 אימייל: support@realpayment.co.il
💬 WhatsApp: 050-123-4567

📖 RealPayment API Documentation

📚 תוכן עניינים

🚀 התחלה מהירה

Base URL

🔗 מדריך התממשקות למערכות חיצוניות

שלב 1 — קבלת API Key

שלב 2 — Headers חובה

שלב 3 — Endpoints מרכזיים לפי שימוש

שלב 4 — Webhooks (אופציונלי)

📥 Swagger / OpenAPI

🔐 אימות (Authentication)

💳 Payments API

פרמטרים (Body):

🔄 תשלום חוזר אוטומטי (recurringData):

תגובה מוצלחת (200):

דוגמה - תשלום חוזר חודשי:

תגובה מוצלחת (200):

Query Parameters:

תגובה מוצלחת (200):

פרמטרים (Body):

📄 Documents API (External)

פרמטרים (Body):

תגובה:

פרמטרים (Body):

תגובה:

פרמטרים (Body):

Query Parameters:

פרמטרים (Body):

פרמטרים (Body):

תגובה:

👥 Customers API חדש

פרמטרים (Body):

תגובה:

Query Parameters:

✍️ Signatures API

פרמטרים (Body):

תגובה:

תגובה:

📄 Documents API (Internal)

Headers:

פרמטרים (Body):

מבנה items[] (עבור invoice/quote):

תגובה מוצלחת (200):

דוגמה 1 - קבלה פשוטה:

דוגמה 2 - חשבונית עם פריטים:

דוגמה 3 - הצעת מחיר:

שגיאות נפוצות:

🔄 Sales Process API חדש

תגובה מוצלחת:

פרמטרים:

Query Parameters:

סטטוסים אפשריים:

פרמטרים:

תגובה מוצלחת:

דוגמה:

פרמטרים:

תגובה מוצלחת:

🔄 זרימת אירועים אוטומטית

🌐 External API (X-API-Key)

פרמטרים:

תגובה מוצלחת:

תגובה מוצלחת:

Query Parameters:

💻 דוגמאות קוד

📋 קודי תגובה

🔔 Webhooks

אירועים:

מבנה Webhook:

Headers:

אימות Signature (Node.js):

⚡ Rate Limits

Headers בתגובה:

💰 עמלות

דוגמה:

💬 תמיכה