وثائق API

كل ما تحتاجه لدمج خدمة OTP في تطبيقك. واجهة RESTful بسيطة وأمثلة جاهزة.

البداية السريعة

ابدأ بإرسال رموز OTP خلال دقائق. اتبع الخطوات التالية:

1

إنشاء حساب

سجل حساباً جديداً في صفحة التسجيل

2

الحصول على API Key

من لوحة التحكم، أنشئ مفتاح API جديد

3

إرسال أول OTP

استخدم المثال أدناه لإرسال رمز التحقق

المصادقة

جميع طلبات API تتطلب مفتاح API صالح. أضف المفتاح في ترويسة الطلب:

Authorization: Bearer YOUR_API_KEY

تنبيه أمني

لا تشارك مفتاح API أو تضعه في الكود المصدري العام. استخدم متغيرات البيئة.

إرسال OTP

أرسل رمز تحقق إلى رقم هاتف أردني.

POST/api/v1/otp/{ brandSlug }/send

المتطلبات

الحقلالنوعالوصف
phonestringرقم الهاتف بصيغة 962XXXXXXXXX

مثال cURL

curl -X POST https://otp.nashmi.org/api/v1/otp/myapp/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "962790000000"}'

مثال Node.js

const response = await fetch('https://otp.nashmi.org/api/v1/otp/myapp/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ phone: '962790000000' }),
});

const data = await response.json();
console.log(data);

مثال Python

import requests

response = requests.post(
    'https://otp.nashmi.org/api/v1/otp/myapp/send',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'phone': '962790000000'}
)

print(response.json())

التحقق من OTP

تحقق من صحة رمز OTP المُدخل من المستخدم.

POST/api/v1/otp/{ brandSlug }/verify

المتطلبات

الحقلالنوعالوصف
phonestringرقم الهاتف بصيغة 962XXXXXXXXX
codestringرمز OTP المكون من 6 أرقام

مثال

curl -X POST https://otp.nashmi.org/api/v1/otp/myapp/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "962790000000", "code": "123456"}'

الاستجابة

{
  "success": true,
  "message": "تم التحقق بنجاح"
}

الأخطاء

جميع الأخطاء تُرجع بتنسيق JSON موحد:

الكودالوصف
400طلب غير صالح - تحقق من البيانات المرسلة
401غير مصرح - مفتاح API غير صالح أو مفقود
404غير موجود - تحقق من عنوان الـ API
429تجاوز الحد - انتظر قبل إعادة المحاولة
500خطأ في الخادم - حاول لاحقاً أو تواصل معنا

حدود الاستخدام

لحماية الخدمة، هناك حدود على عدد الطلبات:

الباقةطلبات/دقيقةOTP/رقم/ساعة
مجاني103
المبتدئ305
الأعمال10010
المؤسساتمخصصمخصص

Webhooks

استقبل إشعارات فورية عند تغير حالة الرسائل. قم بإعداد Webhook URL من لوحة التحكم.

صيغة الإشعار

{
  "event": "message.delivered",
  "data": {
    "messageId": "msg_abc123",
    "phone": "962790000000",
    "status": "delivered",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "signature": "sha256=..."
}

التحقق من التوقيع

تحقق دائماً من توقيع Webhook باستخدام المفتاح السري لضمان صحة الإشعار.