منع التكرار
قد تنقطع الشبكة بعد أن تقبل الواجهة طلبك وقبل أن تصلك الاستجابة. إذا أعدت المحاولة دون احتياط، يصل العميل الرسالة مرتين. أرسل الترويسة Idempotency-Key لتنفذ SMSFabric الطلب مرة واحدة، ثم تعيد الاستجابة المحفوظة لكل محاولة تحمل المفتاح نفسه.
كيف يعمل
Section titled “كيف يعمل”- ترسل طلب إنشاء مع
Idempotency-Key: <your key>. - تحجز SMSFabric المفتاح لمؤسستك وتنفذ الطلب.
- عند النجاح تُحفظ الاستجابة (الحالة والمحتوى) مشفرة لمدة 24 ساعة.
- أي إعادة بالمفتاح نفسه والطلب نفسه تعيد تلك الاستجابة مع الترويسة
Idempotent-Replayed: true، ولا يُنفذ شيء من جديد.
الطلب الفاشل (أي 4xx أو 5xx) لا يستهلك المفتاح، فيمكنك تصحيح الطلب وإرساله بالمفتاح نفسه.
المفاتيح خاصة بمؤسستك: يمكن لمؤسستين استخدام المفتاح نفسه دون تعارض.
نقاط النهاية التي تقبله
Section titled “نقاط النهاية التي تقبله”كل طلب POST ينشئ شيئا:
| نقطة النهاية | تنشئ |
|---|---|
POST /v1/messages |
رسائل |
POST /v1/verifications |
عملية تحقق (رمز لمرة واحدة) |
POST /v1/contacts |
جهة اتصال |
POST /v1/contact-groups |
مجموعة جهات اتصال |
POST /v1/templates |
قالبا |
POST /v1/campaigns |
مسودة حملة |
POST /v1/blacklist |
مدخلا في القائمة السوداء |
POST /v1/webhooks |
نقطة نهاية webhook |
POST /v1/devices/pairing-tokens |
رمز إقران |
POST /v1/pools |
مجموعة أجهزة |
POST /v1/api-keys |
مفتاح API (للمستخدمين المسجلين فقط) |
POST /v1/org/invitations |
دعوة إلى الفريق (للمستخدمين المسجلين فقط) |
تتجاهل باقي نقاط النهاية الترويسة. أما طلبات PATCH وPUT وDELETE فتكرارها آمن بطبيعتها.
اختيار المفتاح
Section titled “اختيار المفتاح”- من 1 إلى 255 حرفا من
A–Z a–z 0–9 _ - : .. أي شيء آخر يعيد400 invalid_idempotency_key. - اشتقه من بياناتك متى أمكن:
order-1042-shippedأوsignup:usr_8812:otp. هكذا تستخدم أي إعادة من عامل آخر أو بعد إعادة التشغيل المفتاح نفسه. - وإلا فولّد UUID مرة واحدة لكل عملية منطقية واحفظه مع المهمة، لا مع كل محاولة HTTP.
إعادة المحاولة بأمان
Section titled “إعادة المحاولة بأمان”# Run this twice: the second call returns the same message ids# and the header "Idempotent-Replayed: true".curl -i https://api.smsfabric.com/v1/messages \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: invoice-7781-reminder" \ -d '{"to": "+201001234567", "body": "Invoice 7781 is due on 1 December."}'import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
// The SDK retries network errors, 429 and 5xx on its own (2 retries by default)// and reuses this key for every attempt. Without a key it generates a UUID per call.const messages = await sf.messages.send( { to: '+201001234567', body: 'Invoice 7781 is due on 1 December.' }, { idempotencyKey: 'invoice-7781-reminder' },);console.log(messages[0].id);import osimport timeimport requests
def send_once(payload: dict, key: str) -> dict: headers = {"X-Api-Key": os.environ["SMSFABRIC_API_KEY"], "Idempotency-Key": key} for attempt in range(4): try: res = requests.post("https://api.smsfabric.com/v1/messages", json=payload, headers=headers, timeout=30) except requests.RequestException: time.sleep(2 ** attempt) continue if res.status_code == 409 or res.status_code == 429 or res.status_code >= 500: time.sleep(int(res.headers.get("Retry-After", 2 ** attempt))) continue res.raise_for_status() return res.json() raise RuntimeError("gave up after 4 attempts")
send_once({"to": "+201001234567", "body": "Invoice 7781 is due on 1 December."}, "invoice-7781-reminder")<?phpfunction sendOnce(array $payload, string $key): array { for ($attempt = 0; $attempt < 4; $attempt++) { $ch = curl_init('https://api.smsfabric.com/v1/messages'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json', 'Idempotency-Key: ' . $key, ], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); if ($body !== false && $status < 300) { return json_decode($body, true); } if ($body !== false && $status < 500 && $status !== 409 && $status !== 429) { throw new RuntimeException("SMSFabric error $status: $body"); } sleep(2 ** $attempt); } throw new RuntimeException('Gave up after 4 attempts');}
sendOnce(['to' => '+201001234567', 'body' => 'Invoice 7781 is due on 1 December.'], 'invoice-7781-reminder');الأخطاء
Section titled “الأخطاء”| الحالة | code |
المعنى | ما العمل |
|---|---|---|---|
| 400 | invalid_idempotency_key |
المفتاح فارغ أو طويل جدا أو فيه أحرف غير مسموحة. | استخدم من 1 إلى 255 حرفا من A–Z a–z 0–9 _ - : .. |
| 409 | idempotency_in_progress |
الطلب الأول بهذا المفتاح ما زال قيد التنفيذ. | انتظر ثانية وأعد المحاولة بالمفتاح نفسه. |
| 422 | idempotency_key_reused |
استُخدم المفتاح خلال آخر 24 ساعة مع طريقة أو مسار أو محتوى مختلف. | استخدم مفتاحا جديدا لكل عملية جديدة، ولا تكرر مفتاحا لمحتوى مختلف. |