התחלה מהירה

משתמשים במפתח גישה מסוג 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

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

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

{
  "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}

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

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`
`virtual_number_id`	No	שיוך אופציונלי למספר.

{
  "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 ממספר וירטואלי משויך. החיוב מחושב לפי נמענים ומקטעי הודעה.

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

ניתן להגדיר כתובת 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)

דוגמאות

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