توثيق API

المصادقة

كل طلب يحتاج مفتاح API في الترويسة. ولّد مفتاحك من صفحة المطوّرين داخل حسابك (يُعرض مرة واحدة فقط — احفظه بأمان).

Authorization: Bearer YOUR_API_KEY

أو عبر الترويسة البديلة x-api-key: YOUR_API_KEY.

إرسال رسالة

POST /messages — يرسل رسالة قالب معتمد (للرموز والتنبيهات) أو رسالة نصّية حرة (داخل نافذة الـ 24 ساعة فقط).

حقول الطلب (JSON)

أمثلة

curl -X POST https://nomutech.sa/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+9665XXXXXXXX",
    "type": "template",
    "template": "your_template",
    "language": "ar"
  }'

الاستجابة عند النجاح

{ "success": true, "wamid": "wamid.HBgM..." }

مثال: رمز تحقق (OTP)

للرموز والتنبيهات الفورية، الأفضل قالب نوعه «مصادقة» معتمد. المثال التالي يستخدم رسالة نصّية للتوضيح (تعمل داخل نافذة 24 ساعة):

curl -X POST https://nomutech.sa/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+9665XXXXXXXX",
    "type": "text",
    "text": "رمز الدخول الخاص بك: 482913"
  }'

منع التكرار (Idempotency)

لتفادي إرسال نفس الرمز/التنبيه مرتين عند انقطاع الشبكة أو إعادة المحاولة، أرسل ترويسة Idempotency-Key بقيمة فريدة لكل عملية (مثل معرّف الطلب عندك). إذا وصلنا نفس المفتاح مرة ثانية، نرجّع نفس النتيجة المحفوظة بدون إرسال جديد(مع ترويسة Idempotency-Replayed: true).

Idempotency-Key: order-9f2c1a-otp

الإرسال الناجح فقط يُحفَظ؛ لو فشل الإرسال يُحرَّر المفتاح لتقدر تعيد المحاولة. أثناء معالجة طلب بنفس المفتاح يرجع 409.

رموز الأخطاء

كل خطأ يرجع رمز HTTP مناسب + كائن { "error": "..." } برسالة عربية.

الحدود

• •60 طلب/دقيقة لكل مفتاح API. عند التجاوز يرجع 429 مع ترويسة Retry-After بعدد الثواني.
• •كل استجابة تتضمّن ترويسات الحدود X-RateLimit-Limit و X-RateLimit-Remaining لتتابع استهلاكك.
• •حد شهري حسب باقتك (عدد الرسائل). عند بلوغه يرجع 429 برسالة توضّح الحد.
• •الرسائل النصّية الحرة تعمل فقط داخل نافذة 24 ساعة من آخر رد للعميل. للإرسال في أي وقت استخدم قالباً معتمداً.