שליחת SMS ראשון ב-5 דקות

המדריך הזה לוקח אתכם ממפתח API להודעה שנמסרה, עם curl או עם ה-SDK ל-Node.

1. צרו מפתח API

בפורטל: API ← מפתחות ← מפתח חדש. יש שני סוגים:

המפתח המלא מוצג פעם אחת בלבד. שמרו אותו במשתנה סביבה (BATLER_API_KEY), לעולם לא בקוד צד-לקוח.

2. ודאו שיש לכם שולח מאומת

כל הודעה יוצאת משם שולח מאושר: שם משותף מהרשימה במערכת, או שם שביקשתם ואושר לחשבון שלכם. שם חדש מבקשים בפורטל (שמות שולח ← בקשה לשם חדש): אותיות גדולות באנגלית עד 10 תווים, עם תעודת עוסק/חברה ותעודה מזהה. התשובה תוך יום עסקים אחד. את הרשימה המלאה מחזיר GET /senders.

3. שלחו הודעה

curl -X POST https://smsprovider-web.vercel.app/api/v1/messages \
  -H "Authorization: Bearer $BATLER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to": "0501234567", "from": "MyBrand", "body": "שלום! ההזמנה שלך יצאה למשלוח"}'

או עם ה-SDK:

import { BatlerSMS } from "@batler/sms";

const sms = new BatlerSMS({ apiKey: process.env.BATLER_API_KEY! });
const res = await sms.messages.send({ to: "0501234567", from: "MyBrand", body: "שלום! ההזמנה שלך יצאה למשלוח" });
console.log(res.messages[0].id);

התשובה מגיעה מיד, לפני השליחה בפועל:

{
  "batch_id": "7d1c3c5e-2b1f-4c55-9a51-1f0b8f1b2a10",
  "accepted": 1,
  "rejected": [],
  "credits_reserved": 1,
  "messages": [{ "id": "0e9b2f0a-6c1d-4f43-8c33-6f3b3f0d9a11", "status": "queued", "to": "+972501234567", "segments": 1, "credits": 1 }]
}

4. עקבו אחרי המסירה

• Webhook (מומלץ): הגדירו כתובת וקבלו message.delivered / message.failed בזמן אמת — ראו Webhooks.
• Polling: GET https://smsprovider-web.vercel.app/api/v1/messages/{id}.

מחזור החיים של הודעה: queued ← sent ← delivered / failed / expired. הודעה מתוזמנת שבוטלה עוברת ל-cancelled והקרדיטים חוזרים.

כללים חשובים

• Idempotency-Key חובה בכל POST של שליחה. אותו מפתח בתוך 24 שעות מחזיר את אותה תשובה בלי חיוב כפול — בטוח לנסות שוב אחרי timeout.
• טלפונים מתקבלים כ-05XXXXXXXX, 5XXXXXXXX, +972… או 972… ומוחזרים תמיד ב-E.164.
• כישלון מסירה (המכשיר כבוי, מספר לא קיים) לא מזכה את הקרדיט; כישלון לפני השליחה משחרר אותו.