פרטי החיבור

Base URL
https://app.aharon.cloud/api/v1
Auth
Bearer token
Format
JSON

משתמשים במפתח גישה מסוג server מתוך הגדרות החשבון. אין לחשוף את המפתח בקוד צד לקוח.

פתיחת התיעוד המלא כניסה ללקוחות

התחלה מהירה

הבקשה הבאה מחזירה את ההודעות הנכנסות האחרונות. מחליפים את הערך ACCESS_KEY_HERE במפתח server מתוך הגדרות החשבון.

curl \
  --request GET \
  --url "https://app.aharon.cloud/api/v1/messages" \
  --header "Authorization: Bearer ACCESS_KEY_HERE" \
  --header "Accept: application/json"

אימות

שדהערך
HeaderAuthorization
ValueBearer ACCESS_KEY_HERE
Token typeserver
Failure401 missing_bearer_token או 401 invalid_token

מודל תגובה

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

{ "ok": true }

תגובה עם שגיאה:

{ "ok": false, "error": "invalid_token", "message": "Bad request" }

הצלחה ושגיאות

StatusErrorמשמעות
400bad_request, missing_senderקלט לא תקין או שדה חסר.
401missing_bearer_token, invalid_tokenהמפתח חסר, בוטל או אינו תקין.
402insufficient_creditsאין מספיק קרדיטים לשליחה.
423sms_sending_closed_weekendבמהלך הבטא, השליחה סגורה מיום שישי בשעה 15:00 עד מוצאי שבת בשעה 21:00 לפי שעון ישראל. לוח הזמנים עשוי להשתנות בכל עת.
429too_many_recipientsיותר מדי נמענים או מגבלת קצב.
502provider_send_failedספק השליחה החזיר כישלון.
503sms_sending_not_enabledשליחה לא פעילה.

GET /me

מחזיר את החשבון המאומת ואת יתרת הקרדיטים הנוכחית.

{
  "ok": true,
  "user": {
    "id": 123,
    "email": "customer@example.com",
    "token_id": 77,
    "token_type": "server",
    "sms_credits": 1000
  }
}

GET /numbers

מציג מספרים וירטואליים שמשויכים לחשבון המאומת.

{
  "ok": true,
  "numbers": [
    {
      "id": 12,
      "number_raw": "0500000000",
      "label": "Main",
      "status": "assigned"
    }
  ]
}

GET /messages

מחזיר את 100 ההודעות הנכנסות האחרונות, מהחדש לישן. זהו החיבור המרכזי עבור API לקבלת SMS.

שדהTypeתיאור
idnumberמזהה הודעה.
virtual_number_idnumberמזהה המספר שקיבל את ההודעה.
from_rawstringהשולח המקורי.
to_rawstringמספר היעד.
bodystringתוכן ההודעה.
provider_received_atdatetimeזמן קבלה אצל הספק.
 
{
  "ok": true,
  "messages": [
    {
      "id": 991,
      "virtual_number_id": 12,
      "from_raw": "Google",
      "from_normalized": "Google",
      "from_type": "text",
      "to_raw": "0500000000",
      "body": "Your code is 123456",
      "provider_received_at": "2026-07-05 13:45:00",
      "first_seen_at": "2026-07-05 13:45:02"
    }
  ]
}

GET /messages/{id}

מחזיר הודעה אחת לפי מזהה, רק אם היא שייכת לחשבון המאומת.

PathRequiredתיאור
idכןמזהה הודעה.
 
{ "ok": true, "message": { "id": 991, "virtual_number_id": 12, "from_raw": "Google", "body": "Your code is 123456" } }
{ "ok": false, "error": "not_found" }

GET /sms/credits

מחזיר את יתרת הקרדיטים הנוכחית לשליחת SMS.

{ "ok": true, "sms_credits": 1000 }

POST /senders/state

מסמן שולח כספאם או כחסום.

BodyRequiredהערות
sender או fromכןמזהה השולח.
stateלאspam או blocked
virtual_number_idלאשיוך אופציונלי למספר.
 
{ "sender": "0520000000", "state": "spam", "virtual_number_id": 12 }
{ "ok": true, "result": { "state": "spam" } }

POST /senders/block

נקודת קיצור לחסימת שולח.

{ "sender": "0520000000", "virtual_number_id": 12 }
{ "ok": true, "blocked": true, "result": { "state": "blocked" } }

POST /sms/send

שולח SMS ממספר וירטואלי משויך. החיוב מחושב לפי נמענים ומקטעי הודעה.

במהלך הבטא, השליחה זמינה בימי חול, נסגרת ביום שישי בשעה 15:00 וחוזרת במוצאי שבת בשעה 21:00 לפי שעון ישראל. השעות עשויות להשתנות בכל עת.

BodyRequiredהערות
fromכןמספר שולח משויך.
messageכןטקסט הודעה.
phones או toכןנמענים מופרדים בנקודתיים, פסיק או שורה חדשה.
flashלאערך בוליאני: flash, sendFlashMessage או send_flash.
 
curl \
  --request POST \
  --url "https://app.aharon.cloud/api/v1/sms/send" \
  --header "Authorization: Bearer ACCESS_KEY_HERE" \
  --header "Content-Type: application/json" \
  --data '{ "from": "0500000000", "to": "0520000000", "message": "Your code is 123456" }'
{
  "ok": true,
  "sms": {
    "outbound_message_id": 456,
    "provider_status": "OK",
    "recipients_count": 1,
    "segments": 1,
    "credits_used": 1,
    "balance_after": 999,
    "flash": false
  }
}

Webhook לקבלת SMS

ניתן להגדיר כתובת HTTPS ציבורית לכל מספר כדי לקבל אירועי SMS נכנסים.

{
  "event": "sms.received",
  "to": "0500000000",
  "from": "Google",
  "body": "Your code is 123456",
  "received_at": "2026-07-05 13:45:00"
}
X-SMS-Timestamp: 1782395100
X-SMS-Signature: sha256=...
HMAC_SHA256(webhook_secret, timestamp + "." + rawBody)

דוגמאות חיבור

Node.js

const response = await fetch(
  'https://app.aharon.cloud/api/v1/messages',
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer ACCESS_KEY_HERE',
      Accept: 'application/json'
    }
  }
);

const data = await response.json();
console.log(data);

Python

import requests

response = requests.get(
    'https://app.aharon.cloud/api/v1/messages',
    headers={
        'Authorization': 'Bearer ACCESS_KEY_HERE',
        'Accept': 'application/json'
    },
    timeout=20
)

print(response.json())