תיעוד למפתחים

התחלה מהירה

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

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

אימות

Header	`Authorization`
Value	`Bearer ACCESS_KEY_HERE`
Token type	`server`
Failure	`401 missing_bearer_token` / `401 invalid_token`

מודל תגובה

הצלחה

{
  "ok": true
}

שגיאה

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

Status	Error	משמעות
400	`bad_request`, `missing_sender`	קלט לא תקין או שדה חסר.
401	`missing_bearer_token`, `invalid_token`	המפתח חסר, בוטל או אינו תקין.
402	`insufficient_credits`	אין מספיק קרדיטים לשליחה.
423	`sms_sending_closed_weekend`	שליחה סגורה בחלון סוף השבוע שהוגדר.
429	`too_many_recipients`	יותר מדי נמענים או מגבלת קצב.
502	`provider_send_failed`	ספק השליחה החזיר כישלון.
503	`sms_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

מחזיר עד limit הודעות נכנסות בסדר מזהה עולה. השתמשו ב־after_id כדי לקבל רק הודעות עם מזהה גבוה יותר.

שאילתה	Required	הערות
`limit`	No	מספר שלם בין 1 ל־250. ברירת מחדל: 100.
`after_id`	No	מחזיר רק הודעות שהמזהה שלהן גדול ממספר שלם חיובי זה.
`virtual_number_id`	No	מסנן הודעות לפי מזהה מספר וירטואלי משויך.

שדה	Type	תיאור
`id`	number	מזהה הודעה.
`virtual_number_id`	number	מזהה המספר שקיבל את ההודעה.
`from_raw`	string	השולח המקורי.
`to_raw`	string	מספר היעד.
`body`	string	תוכן ההודעה.
`provider_received_at`	datetime	זמן קבלה אצל הספק.
`first_seen_at`	datetime	זמן הייבוא הראשון ל־ACloud.

ערכי תאריך ושעה נשלחים בפורמט YYYY-MM-DD HH:mm:ss ללא היסט מספרי, ומייצגים את אזור הזמן Asia/Jerusalem.

{
  "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"
    }
  ],
  "pagination": {
    "limit": 100,
    "count": 1,
    "after_id": null,
    "next_after_id": 991,
    "has_more": false
  }
}

GET

/messages/{id}

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

Path	`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

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

Body	Required	הערות
`sender` / `from`	Yes	מזהה השולח.
`state`	No	`spam` / `blocked`. כאשר השדה חסר, ברירת המחדל היא spam.
`virtual_number_id`	No	שיוך אופציונלי למספר.

{
  "sender": "0520000000",
  "state": "spam",
  "virtual_number_id": 12
}

{
  "ok": true,
  "state": "spam",
  "result": {
    "state": "spam"
  }
}

POST

/senders/block

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

{
  "sender": "0520000000",
  "virtual_number_id": 12
}

{
  "ok": true,
  "blocked": true,
  "result": {
    "state": "blocked"
  }
}

POST

/sms/send

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

Body	Required	הערות
`from`	Yes	מספר שולח משויך.
`message`	Yes	טקסט הודעה.
`phones` / `to`	Yes	נמענים מופרדים בנקודתיים, פסיק או שורה חדשה.
`flash`	No	בוליאני: 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

Webhook להודעות נכנסות נרשם ידנית לכל מספר. ACloud אינו חושף נקודות API לרישום או למחיקה של Webhook.

צרו Custom webhook ב־Make והעתיקו את כתובת ה־HTTPS הציבורית שלו.
ב־ACloud פתחו מספרים, בחרו את המספר המקבל ופתחו Webhook.
הדביקו את כתובת Make בשדה כתובת Webhook ושמרו.

אין בורר אירועים. ACloud שולח את האירוע sms.received עבור כל הודעת SMS נכנסת.

{
  "event": "sms.received",
  "message_id": "msg_991",
  "number_id": "num_12",
  "to": "0500000000",
  "from": "Google",
  "from_type": "text",
  "body": "Your code is 123456",
  "received_at": "2026-07-05 13:45:00"
}

השדה received_at נשלח בפורמט YYYY-MM-DD HH:mm:ss ללא היסט מספרי ומייצג את אזור הזמן Asia/Jerusalem.

X-SMS-Timestamp: 1782395100
X-SMS-Signature: sha256=...
HMAC_SHA256(webhook_secret, timestamp + "." + rawBody)

דוגמאות

curl

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

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())