البدء السريع
في هذا الدليل تقرن هاتفًا بحسابك، وتنشئ مفتاح API، وترسل رسالة من شيفرتك، ثم تتابعها في البوابة حتى تُسلَّم.
قبل أن تبدأ
Section titled “قبل أن تبدأ”- حساب في SMSFabric. أنشئه من
https://app.smsfabric.com/register(دليل الحساب). - هاتف Android فيه شريحة SIM وتطبيق SMSFabric مثبت (تثبيت التطبيق).
- طرفية فيها
curl، أو Node.js بالإصدار 20 أو أحدث.
1. أقرن هاتفًا
Section titled “1. أقرن هاتفًا”-
في البوابة، افتح الأجهزة ثم انقر إقران هاتف.
-
يظهر رمز QR صالح لمرة واحدة ولمدة 10 دقائق.
-
على الهاتف، افتح SMSFabric واضغط مسح رمز QR، ثم وجّه الكاميرا نحو الرمز. لا توجد كاميرا؟ اضغط إدخال الرمز يدويًا واكتب الرمز الظاهر تحت رمز QR.
اضغط مسح رمز QR. اضغط متابعة واسمح باستخدام الكاميرا. -
تؤكد البوابة أن الهاتف اقترن وتعرض شرائحه، ويعرض الهاتف أن البوابة متصلة.
البوابة متصلة.
اسمح للتطبيق بتجاهل تحسين البطارية عندما يطلب ذلك، حتى لا يوقفه Android ليلًا (السبب).
2. أنشئ مفتاح API
Section titled “2. أنشئ مفتاح API”-
افتح مفاتيح API تحت المطوّرون في الشريط الجانبي، ثم انقر إنشاء مفتاح API.
-
سمِّ المفتاح باسم ما يستخدمه، واختر تجريبي · بيئة اختبار أو إنتاج · رسائل حقيقية.
-
حدّد
messages:sendوmessages:read، ثم انقر إنشاء المفتاح. -
انسخ السر واحفظه في مدير الأسرار أو في ملف
.env، فهو لا يظهر إلا مرة واحدة. ثم انقر حفظته.
احفظه في متغير بيئة للخطوة التالية:
export SMSFABRIC_API_KEY="sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"3. أرسل أول رسالة
Section titled “3. أرسل أول رسالة”أرسل إلى رقم هاتفك بالصيغة الدولية (E.164)، مثل +201001234567.
curl -X POST https://api.smsfabric.com/v1/messages \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: quickstart-001" \ -d '{"to": "+201001234567", "body": "Hello from SMSFabric"}'npm install @smsfabric/sdkimport { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const [message] = await sf.messages.send( { to: '+201001234567', body: 'Hello from SMSFabric' }, { idempotencyKey: 'quickstart-001' },);console.log(message?.id, message?.status);import osimport requests
response = requests.post( "https://api.smsfabric.com/v1/messages", headers={ "X-Api-Key": os.environ["SMSFABRIC_API_KEY"], "Idempotency-Key": "quickstart-001", }, json={"to": "+201001234567", "body": "Hello from SMSFabric"}, timeout=30,)response.raise_for_status()message = response.json()["data"][0]print(message["id"], message["status"])<?php$ch = curl_init('https://api.smsfabric.com/v1/messages');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json', 'Idempotency-Key: quickstart-001', ], CURLOPT_POSTFIELDS => json_encode(['to' => '+201001234567', 'body' => 'Hello from SMSFabric']),]);$message = json_decode(curl_exec($ch), true)['data'][0];echo $message['id'] . ' ' . $message['status'] . PHP_EOL;package main
import ( "bytes" "crypto/rand" "encoding/json" "fmt" "io" "log" "net/http" "os")
func main() { payload, _ := json.Marshal(map[string]string{"to": "+201001234567", "body": "Hello from SMSFabric"}) req, err := http.NewRequest("POST", "https://api.smsfabric.com/v1/messages", bytes.NewReader(payload)) if err != nil { log.Fatal(err) } req.Header.Set("X-Api-Key", os.Getenv("SMSFABRIC_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", newUUID())
res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() raw, _ := io.ReadAll(res.Body) if res.StatusCode/100 != 2 { log.Fatalf("send failed: %s %s", res.Status, raw) } var out struct{ Data []struct{ ID, Status string } } if err := json.Unmarshal(raw, &out); err != nil || len(out.Data) == 0 { log.Fatalf("unexpected response: %s", raw) } fmt.Println(out.Data[0].ID, out.Data[0].Status)}
func newUUID() string { b := make([]byte, 16) rand.Read(b) b[6], b[8] = b[6]&0x0f|0x40, b[8]&0x3f|0x80 return fmt.Sprintf("%x-%x-%x-%x-%x", b[:4], b[4:6], b[6:8], b[8:10], b[10:])}import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.util.UUID;import java.util.regex.Matcher;import java.util.regex.Pattern;
public class Send { public static void main(String[] args) throws Exception { String json = """ {"to":"+201001234567","body":"Hello from SMSFabric"}"""; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.smsfabric.com/v1/messages")) .header("X-Api-Key", System.getenv("SMSFABRIC_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", UUID.randomUUID().toString()) .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() / 100 != 2) { throw new IllegalStateException("Send failed: " + response.statusCode() + " " + response.body()); } Matcher message = Pattern.compile("\"id\":\"([^\"]+)\".*?\"status\":\"([^\"]+)\"").matcher(response.body()); if (!message.find()) { throw new IllegalStateException("Unexpected response: " + response.body()); } System.out.println(message.group(1) + " " + message.group(2)); }}using System;using System.Net.Http;using System.Text;using System.Text.Json;
using var client = new HttpClient();using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.smsfabric.com/v1/messages");request.Headers.Add("X-Api-Key", Environment.GetEnvironmentVariable("SMSFABRIC_API_KEY"));request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());request.Content = new StringContent( JsonSerializer.Serialize(new { to = "+201001234567", body = "Hello from SMSFabric" }), Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);var text = await response.Content.ReadAsStringAsync();if (!response.IsSuccessStatusCode){ throw new HttpRequestException($"Send failed: {(int)response.StatusCode} {text}");}
using var json = JsonDocument.Parse(text);var message = json.RootElement.GetProperty("data")[0];var id = message.GetProperty("id").GetString();var status = message.GetProperty("status").GetString();Console.WriteLine($"{id} {status}");require "json"require "net/http"require "securerandom"
uri = URI("https://api.smsfabric.com/v1/messages")request = Net::HTTP::Post.new(uri, { "X-Api-Key" => ENV.fetch("SMSFABRIC_API_KEY"), "Content-Type" => "application/json", "Idempotency-Key" => SecureRandom.uuid,})request.body = JSON.generate({ to: "+201001234567", body: "Hello from SMSFabric" })
response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }abort "Send failed: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
message = JSON.parse(response.body)["data"][0]puts "#{message["id"]} #{message["status"]}"يرد SMSFabric بـ 201 Created ورسالة لكل مستلم بالحالة queued:
{ "data": [ { "id": "msg_8k2m9xdp4lw1", "direction": "outbound", "to": "+201001234567", "body": "Hello from SMSFabric", "status": "queued", "segments": 1, "encoding": "GSM7", "createdAt": "2026-11-19T09:41:00.000Z" } ]}تجعل ترويسة Idempotency-Key إعادة المحاولة آمنة: إرسال الطلب نفسه مرة أخرى خلال 24 ساعة يعيد النتيجة الأولى بدل رسالة ثانية (منع التكرار).
تفضّل Postman أو Insomnia؟
Section titled “تفضّل Postman أو Insomnia؟”استورد مجموعة جاهزة، واضبط المتغير apiKey، وشغّل Messages › Send a message. الخطوات في صفحة Postman وInsomnia.
- تنزيل مجموعة Postman (
smsfabric.postman_collection.json, Collection v2.1) - تنزيل مجموعة Insomnia (
smsfabric.insomnia.json, v4 export)
22 طلبًا جاهزًا بالترتيب الذي تجربها به، من أول إرسال إلى الحملات وخطافات الويب وباقتك.
4. تابعها في البوابة
Section titled “4. تابعها في البوابة”-
افتح الرسائل. تظهر رسالتك في الأعلى، وتتحدث حالتها مباشرة.
-
انقر الرسالة لفتحها.
-
يعرض السجل الزمني كل خطوة: في الطابور، ثم التوجيه، ثم الإرسال، ثم التسليم، مع الهاتف والشريحة اللذين أرسلاها.
تستطيع شيفرتك قراءة السجل الزمني نفسه عبر GET /v1/messages/:id، أو تلقي كل تغيير فور حدوثه عبر webhook. راجع تتبع التسليم.
5. تلقَّ تحديثات التسليم عبر webhook
Section titled “5. تلقَّ تحديثات التسليم عبر webhook”أضف عنوان HTTPS في Webhooks، واشترك في message.delivered وmessage.failed، وتحقق من ترويسة SMSFabric-Signature في كل استدعاء. يشرح دليل webhooks الإعداد كاملًا مع شيفرة التحقق.
ليس لديك عنوان عام بعد؟ شغّل smsfabric listen لتصلك الأحداث نفسها على جهازك وتُرسل إلى خادم محلي:
smsfabric listen --forward-to http://localhost:3000/hooks/sms --events message.delivered,message.failed