التحقق والرسائل
إنشاء عملية تحقق
نولّد رمزاً ونرسله عبر سلسلة القنوات، مع تبديل تلقائي واسترداد عند الفشل.
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_….
سەرپەڕەکان (Headers)
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 | لا قناة مفعّلة ومسعّرة لوجهة الرقم |