التحقق والرسائل
إنشاء عملية تحقق
نولّد رمزاً ونرسله عبر سلسلة القنوات، مع تبديل تلقائي واسترداد عند الفشل.
https://watsy.me/v1/verifyالرمز يتولّد في الخادم ولا يظهر في أي رد، ولا نخزّنه: نحفظ بصمة HMAC فقط. نجرب القنوات بالترتيب، وإذا رفضت قناة أو لم ترد خلال 6 ثوانٍ نعيد مبلغها وننتقل للتالية.
curl -X POST https://watsy.me/v1/verify \
-H "Authorization: Bearer $WATSY_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: signup-8841" \
-d '{
"phone": "07701234567",
"locale": "ar",
"client_ip": "198.51.100.23",
"metadata": {
"user_id": 8841
}
}'{
"id": "5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11",
"object": "verification",
"mode": "live",
"phone": "+9647701234567",
"status": "sent",
"channel": "telegram",
"channels": [
"whatsapp",
"telegram",
"sms"
],
"attempts": 0,
"max_attempts": 5,
"attempts_remaining": 5,
"locale": "ar",
"metadata": {
"user_id": 8841
},
"expires_at": "2026-10-28T10:05:00.000Z",
"verified_at": null,
"created_at": "2026-10-28T10:00:00.000Z",
"price_milli": 18000,
"messages": [
{
"id": "0b6f6a3e-1c2d-4e5f-8a9b-1c2d3e4f5a6b",
"object": "message",
"verification_id": "5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11",
"channel": "whatsapp",
"provider": "meta_cloud",
"status": "failed",
"error_code": "whatsapp_131026",
"price_milli": 0,
"created_at": "2026-10-28T10:00:00.000Z",
"updated_at": "2026-10-28T10:00:01.000Z"
},
{
"id": "7e1d2c3b-4a59-4687-9a0b-c1d2e3f4a5b6",
"object": "message",
"verification_id": "5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11",
"channel": "telegram",
"provider": "telegram_gateway",
"status": "sent",
"error_code": null,
"price_milli": 18000,
"created_at": "2026-10-28T10:00:01.000Z",
"updated_at": "2026-10-28T10:00:02.000Z"
}
]
}المصادقة
Authorizationstring (header)إلزاميBearerثم مفتاح المشروع:wsy_live_…أوwsy_test_….
الترويسات
Idempotency-Keystring1 إلى 255 حرفاً. يمنع التكرار عند إعادة المحاولة خلال 24 ساعة. انظر Idempotency.
X-Request-Idstringاختياري، 8 إلى 64 حرفاً. نعيده في الرد، وإلا نولّد واحداً.
جسم الطلب
application/jsonphonestringإلزاميرقم المستلم بأي صيغة مدعومة.
channelsstring[]ترتيب القنوات، من 1 إلى 3 بدون تكرار. الافتراضي من إعدادات المشروع (
whatsappثمtelegramثمsms).القيم:
whatsapptelegramsmscode_lengthintegerالافتراضي: 6طول الرمز من 4 إلى 8. الافتراضي من إعدادات المشروع.
ttl_secondsintegerالافتراضي: 300صلاحية الرمز من 60 إلى 1800 ثانية.
localestringالافتراضي: arلغة الرسالة.
القيم:
arenmetadataobjectبياناتك الخاصة (حتى 2KB، والمفاتيح حتى 64 حرفاً). تعود في الردود والـ webhooks.
client_ipstringعنوان IP للمستخدم النهائي (من طلب تطبيقك، IPv4 أو IPv6). حد الطلبات لكل IP يُحسب عليه فقط؛ بدونه لا يُطبّق حد الـ IP. أرسله دائماً حتى نحميك من شخص واحد يطلب رموزاً لأرقام كثيرة.
الرد (201)
application/jsonidstringإلزاميمعرّف عملية التحقق (UUID).
objectstringإلزاميدائماً
verification.modestringإلزامينوع المفتاح الذي أنشأ العملية.
القيم:
livetestphonestringإلزاميالرقم بصيغة E.164 بعد التوحيد.
statusstringإلزاميحالة العملية. انظر جدول الحالات.
القيم:
pendingsentverifiedfailedexpiredcanceledchannelstring | nullإلزاميآخر قناة جُرّبت، أو التي وصل منها الرمز.
channelsstring[]إلزاميسلسلة القنوات المطلوبة بالترتيب.
attemptsintegerإلزاميعدد الفحوصات حتى الآن.
max_attemptsintegerإلزاميحد الفحوصات من إعدادات المشروع (الافتراضي 5).
attempts_remainingintegerإلزاميالفحوصات المتبقية.
localestringإلزاميلغة الرسالة.
القيم:
arenmetadataobjectإلزاميبياناتك كما أرسلتها، أو
{}.expires_atstringإلزامينهاية صلاحية الرمز.
verified_atstring | nullإلزاميوقت التحقق الناجح.
created_atstringإلزاميوقت الإنشاء.
price_milliintegerإلزاميصافي ما خُصم لكل المحاولات بالـ milli-IQD (1 دينار = 1000).
messagesmessage[]إلزاميمحاولة لكل قناة جُرّبت، بالترتيب.
عرض الحقول الفرعيةإخفاء الحقول الفرعية
idstringمعرّف محاولة الإرسال.
objectstringدائماً
message.verification_idstringعملية التحقق التي تتبعها المحاولة.
channelstringالقناة.
القيم:
whatsapptelegramsmsproviderstringالمزوّد الذي نفّذ المحاولة:
meta_cloud(رقم Watsy على واتساب)،whatsapp_own(رقمك الخاص)،telegram_gateway، أوtestفي وضع الاختبار.statusstringdeliveredيظهر عندما يرسل المزوّد تقرير تسليم (واتساب حالياً).القيم:
pendingsentdeliveredfailederror_codestring | nullسبب الفشل من المزوّد، مثل
whatsapp_131026أوtelegram_PHONE_NUMBER_INVALIDأوtimeout.price_milliintegerصافي ما خُصم لهذه المحاولة بالـ milli-IQD. المحاولة المُستردّة تظهر 0.
created_atstringوقت الإنشاء (ISO 8601، UTC).
updated_atstringآخر تحديث.
كيف نخصم
- نخصم سعر القناة قبل الاتصال بالمزوّد، ونعيده فوراً إذا فشلت. لذلك تظهر القناة الفاشلة بسعر 0، و
price_milliهو الصافي. - إذا كان الرصيد لا يكفي لأول قناة، يرجع
402 insufficient_balanceولا يُنشأ ولا يُرسل شيء. - عند فشل كل القنوات يرجع
502 delivery_failedمع استرداد كامل، ويصلك الحدثverification.failed.
أخطاء أخرى
| HTTP | code | متى |
|---|---|---|
402 | spend_cap_reached | تجاوز حد الصرف الشهري للمشروع |
403 | forbidden | IP خادمك خارج القائمة المسموحة |
403 | test_number_required | مفتاح اختبار مع رقم غير مسجّل كرقم اختبار |
409 | idempotency_conflict | تعارض في Idempotency-Key |
503 | no_channel_available | لا قناة مفعّلة ومسعّرة لوجهة الرقم |