הצגת המקור של הדף "שליחת סמס ב-API"

= ממשק API לשליחת SMS =

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

----

== נקודת קצה ==

<syntaxhighlight lang="text">
GET /api/send_sms.php
</syntaxhighlight>

----

== אימות ==

יש להעביר את מזהה העובד באמצעות הפרמטר <code>user_id</code>. הממשק משתמש בו לאיתור רשומת הלקוח ולרישום ההודעה היוצאת תחת חשבונך.

----

== מצב 1 — הודעה ישירה ==

שליחת הודעה שאתה מנסח ישירות בבקשה.

=== פרמטרים חובה ===

{| class="wikitable"
! פרמטר !! סוג !! תיאור
|-
| <code>source_number</code> || מחרוזת || שם השולח או המספר שמוצג אצל הנמען. תווים אלפאנומריים בלבד, עד 12 תווים.
|-
| <code>message</code> || מחרוזת || תוכן ההודעה לשליחה. עד 500 תווים.
|-
| <code>phone</code> || מחרוזת || מספר הנייד הישראלי של הנמען בפורמט <code>05X-XXXXXXX</code> או <code>05XXXXXXXX</code>.
|}

=== פרמטרים אופציונליים ===

{| class="wikitable"
! פרמטר !! סוג !! תיאור
|-
| <code>user_id</code> || מספר שלם || מזהה העובד שלך. משמש לאיתור הלקוח ולרישום.
|-
| <code>from_phone</code> || מחרוזת || חלופה ל־<code>phone</code>. יוחל אם <code>phone</code> לא סופק.
|-
| <code>date</code> || מחרוזת || תאריך שליחה מתוזמנת בפורמט <code>YYYY-MM-DD</code>. ברירת מחדל: היום.
|-
| <code>time</code> || מחרוזת || שעת שליחה מתוזמנת בפורמט <code>HH:MM:SS</code>. ברירת מחדל: עכשיו.
|-
| <code>repository_assign_id</code> || מספר שלם || אם מזהה השיוך של הלקוח כבר ידוע, יש להעבירו כאן כדי לדלג על שלב האיתור.
|}

=== דוגמת בקשה ===

<syntaxhighlight lang="text">
GET /api/send_sms.php
  ?source_number=MindCRM
  &message=שלום, התור שלך אושר.
  &phone=0501234567
  &user_id=42
</syntaxhighlight>

=== דוגמת שליחה מתוזמנת ===

<syntaxhighlight lang="text">
GET /api/send_sms.php
  ?source_number=MindCRM
  &message=תזכורת: הפגישה שלך מחר בשעה 10:00.
  &phone=0501234567
  &user_id=42
  &date=2025-07-01
  &time=09:00:00
</syntaxhighlight>

----

== מצב 2 — תבנית SMS ==

שימוש בתבנית מוכנה מראש השמורה במערכת. תוכן ההודעה נשלף אוטומטית, וכל '''משתני ה־placeholder''' (כגון שם הלקוח או מספר הטלפון) מוחלפים בנתונים אמיתיים לפני השליחה.

כל פרמטר שמועבר במפורש '''דורס''' את ערך התבנית המתאים.

=== פרמטרים חובה ===

{| class="wikitable"
! פרמטר !! סוג !! תיאור
|-
| <code>sms_template_id</code> || מספר שלם || מזהה תבנית ה־SMS לשימוש.
|-
| <code>phone</code> || מחרוזת || מספר הנייד הישראלי של הנמען בפורמט <code>05X-XXXXXXX</code> או <code>05XXXXXXXX</code>.
|}

=== פרמטרים אופציונליים ===

{| class="wikitable"
! פרמטר !! סוג !! תיאור
|-
| <code>user_id</code> || מספר שלם || מזהה העובד שלך. משמש לאיתור נתוני הלקוח ולהחלפת המשתנים.
|-
| <code>from_phone</code> || מחרוזת || חלופה ל־<code>phone</code>. יוחל אם <code>phone</code> לא סופק.
|-
| <code>source_number</code> || מחרוזת || דורס את שם השולח המוגדר בתבנית.
|-
| <code>message</code> || מחרוזת || דורס את תוכן ההודעה המוגדר בתבנית לחלוטין.
|-
| <code>date</code> || מחרוזת || תאריך שליחה מתוזמנת בפורמט <code>YYYY-MM-DD</code>. ברירת מחדל: עכשיו.
|-
| <code>time</code> || מחרוזת || שעת שליחה מתוזמנת בפורמט <code>HH:MM:SS</code>. ברירת מחדל: עכשיו.
|-
| <code>repository_assign_id</code> || מספר שלם || אם מזהה השיוך של הלקוח כבר ידוע, יש להעבירו כאן כדי לדלג על שלב האיתור.
|}

=== דוגמת בקשה ===

<syntaxhighlight lang="text">
GET /api/send_sms.php
  ?sms_template_id=7
  &phone=0501234567
  &user_id=42
</syntaxhighlight>

=== דוגמה לדריסת שם השולח מהתבנית ===

<syntaxhighlight lang="text">
GET /api/send_sms.php
  ?sms_template_id=7
  &phone=0501234567
  &user_id=42
  &source_number=MyBrand
</syntaxhighlight>

----

== פורמט מספר טלפון ==

מספר הטלפון של הנמען חייב להיות מספר נייד ישראלי התואם לאחד מהפורמטים הבאים:

* <code>0501234567</code> — 10 ספרות, ללא מפריד
* <code>050-1234567</code> — עם מקף כמפריד

קידומות תקינות: <code>050</code>, <code>051</code>, <code>052</code>, <code>053</code>, <code>054</code>, <code>055</code>, <code>058</code>, <code>059</code>

----

== פורמט תגובה ==

כל התגובות מוחזרות בפורמט JSON.

<syntaxhighlight lang="json">
{
  "stat_code": 0,
  "description": "SMS sent successfully",
  "data": "SMS sent successfully"
}
</syntaxhighlight>

{| class="wikitable"
! שדה !! סוג !! תיאור
|-
| <code>stat_code</code> || מספר שלם || <code>0</code> = הצלחה. כל ערך אחר = שגיאה (ראה טבלה להלן).
|-
| <code>description</code> || מחרוזת || הודעת תוצאה קריאה לאדם.
|-
| <code>data</code> || מחרוזת || זהה ל־<code>description</code>.
|}

----

== קודי שגיאה ==

{| class="wikitable"
! קוד !! משמעות !! כיצד לתקן
|-
| <code>0</code> || הצלחה || —
|-
| <code>1</code> || פרמטר חובה חסר || יש לוודא שכל הפרמטרים הנדרשים נכללים בבקשה.
|-
| <code>2</code> || פורמט מספר טלפון שגוי || יש לוודא שמספר הטלפון מתחיל ב־<code>05</code> ומכיל בדיוק 10 ספרות.
|-
| <code>3</code> || הודעה ארוכה מדי || יש לשמור על הודעה עד 500 תווים.
|-
| <code>4</code> || <code>source_number</code> לא תקין || יש להשתמש באותיות ומספרים בלבד, עד 12 תווים. ללא תווים מיוחדים.
|-
| <code>5</code> || תבנית SMS לא נמצאה || יש לוודא שה־<code>sms_template_id</code> קיים ופעיל במערכת.
|}

----

== כללי עדיפות (מצב 2) ==

כאשר מועברים גם תבנית וגם פרמטרים מפורשים, '''הפרמטרים המפורשים תמיד גוברים''':

{| class="wikitable"
! ערך !! מקור
|-
| <code>message</code> || פרמטר מפורש ← טקסט התבנית (עם החלפת משתנים)
|-
| <code>source_number</code> || פרמטר מפורש ← שם השולח מהתבנית
|}

----

== הערות ==

* הודעות נרשמות אוטומטית בהיסטוריית ה־SMS של הלקוח.
* הודעות מתוזמנות (באמצעות <code>date</code>/<code>time</code>) שזמנן עבר — נשלחות מיידית.
* משתני התבנית מוחלפים בנתוני הלקוח החיים בזמן הבקשה.