הצטרפות

כרטסת לקוח ב-API — הפקה, שליחה במייל והורדה (PDF/Excel)

כרטסת לקוח ב-API — הפקה, שליחה במייל והורדה

נקודת הקצה customerCard מפיקה את כרטסת הלקוח (דוח תנועות המסמכים של לקוח) דרך ה-API — בדיוק כמו הכפתור "כרטסת לקוח" במסך הלקוח. אפשר לקבל את הכרטסת כ-PDF או Excel, לבחור בין שליחה במייל לבין הורדת הקובץ, או פשוט לקבל את היתרה בלבד כ-JSON.

המדריך מיועד למפתחים. אם עדיין לא הכרתם — כדאי לקרוא קודם על ה-API של המערכת.

נקודת הקצה

  • URL: POST /api/customers/customerCard
  • אימות: api_key (בכותרת או בגוף ה-JSON), כמו בשאר ה-API.

שדות הבקשה

  • api_key — מפתח העסק (חובה).
  • test — 0 = הפקה אמיתית, 1 = בדיקה בלבד (מחזיר את הפרמטרים שזוהו, בלי להפיק/לשלוח).
  • customer_id — מזהה הלקוח (GUID), או לחלופין:
  • identification — ת.ז / ח.פ של הלקוח.
  • balance_only — 1 להחזרת היתרה בלבד כ-JSON, ללא הפקת PDF/Excel וללא שליחת מייל. ברירת מחדל: 0. כשמפעילים אותו, השדות format ו-emails אינם רלוונטיים.
  • card_type — balance (כרטסת יתרה, עם עמודת יתרה מצטברת) או income (כרטסת הכנסה, סכומי מסמכים + סה"כ, ללא עמודת יתרה). ברירת מחדל: balance.
  • format — pdf או excel. ברירת מחדל: pdf.
  • from_date / to_date — טווח תאריכים אופציונלי, בפורמט dd/MM/yyyy. השאירו ריק לכל התקופה.
  • emails — מערך כתובות מייל. אם מועבר — הכרטסת תישלח לכתובות אלו. אם לא מועבר — הקובץ יוחזר להורדה.

מצבי פעולה

  • יתרה בלבד (JSON) — כאשר מעבירים balance_only: 1. התגובה היא JSON עם היתרה בלבד: {"status_code":"0","balance":1234.5,"customer_id":"..."} — בלי קובץ ובלי מייל. שימושי כשרוצים רק להציג או לסנכרן את יתרת הלקוח במערכת שלכם.
  • שליחה במייל — כאשר מעבירים emails (וללא balance_only). התגובה היא JSON: {"status_code":"0","sent":true,"emails_count":N}.
  • הורדה — כאשר לא מעבירים emails (וללא balance_only). התגובה היא הקובץ עצמו (PDF/Excel) עם כותרת Content-Disposition: attachment, ולא JSON.

דוגמה — קבלת היתרה בלבד (JSON)

curl -X POST "https://app.invoice-maven.co.il/api/customers/customerCard" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "test": 0,
    "customer_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "balance_only": 1
  }'

# תגובה:
# {"status_code":"0","balance":346.41,"customer_id":"a1b2c3d4-e5f6-7890-1234-567890abcdef"}

דוגמה — שליחת כרטסת PDF במייל

curl -X POST "https://app.invoice-maven.co.il/api/customers/customerCard" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "test": 0,
    "customer_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "card_type": "balance",
    "format": "pdf",
    "emails": ["client@example.com"]
  }'

דוגמה — הורדת כרטסת Excel

curl -X POST "https://app.invoice-maven.co.il/api/customers/customerCard" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -o card.xlsx \
  -d '{
    "api_key": "YOUR_API_KEY",
    "test": 0,
    "identification": "123456789",
    "card_type": "income",
    "format": "excel"
  }'

סיום בהצלחה

זהו — אפשר להפיק כרטסת לכל לקוח ישירות מהמערכת שלכם, לשלוח אותה אוטומטית במייל, לשמור את הקובץ, או לקבל רק את היתרה.

טיפים נוספים:
• רוצים רק את היתרה, בלי קובץ? העבירו balance_only: 1 וקבלו מספר בתגובת JSON.
• השתמשו ב-test: 1 כדי לוודא שהלקוח והפרמטרים זוהו נכון לפני הפקה אמיתית.
• balance מציג יתרה מצטברת; income מתאים לסיכום הכנסות בלבד.
• לתיעוד ה-API המלא והאינטראקטיבי, לחצו כאן.

x

הצטרפות