Watsy
التحقق والرسائلإنشاء عملية تحقق

التحقق والرسائل

إنشاء عملية تحقق

نولّد رمزاً ونرسله عبر سلسلة القنوات، مع تبديل تلقائي واسترداد عند الفشل.

POSThttps://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-Keystring

    1 إلى 255 حرفاً. يمنع التكرار عند إعادة المحاولة خلال 24 ساعة. انظر Idempotency.

  • X-Request-Idstring

    اختياري، 8 إلى 64 حرفاً. نعيده في الرد، وإلا نولّد واحداً.

جسم الطلب

application/json
  • phonestringإلزامي

    رقم المستلم بأي صيغة مدعومة.

  • channelsstring[]

    ترتيب القنوات، من 1 إلى 3 بدون تكرار. الافتراضي من إعدادات المشروع (whatsapp ثم telegram ثم sms).

    القيم:whatsapptelegramsms

  • code_lengthintegerالافتراضي: 6

    طول الرمز من 4 إلى 8. الافتراضي من إعدادات المشروع.

  • ttl_secondsintegerالافتراضي: 300

    صلاحية الرمز من 60 إلى 1800 ثانية.

  • localestringالافتراضي: ar

    لغة الرسالة.

    القيم:aren

  • metadataobject

    بياناتك الخاصة (حتى 2KB، والمفاتيح حتى 64 حرفاً). تعود في الردود والـ webhooks.

  • client_ipstring

    عنوان IP للمستخدم النهائي (من طلب تطبيقك، IPv4 أو IPv6). حد الطلبات لكل IP يُحسب عليه فقط؛ بدونه لا يُطبّق حد الـ IP. أرسله دائماً حتى نحميك من شخص واحد يطلب رموزاً لأرقام كثيرة.

الرد (201)

application/json
  • idstringإلزامي

    معرّف عملية التحقق (UUID).

  • objectstringإلزامي

    دائماً verification.

  • modestringإلزامي

    نوع المفتاح الذي أنشأ العملية.

    القيم:livetest

  • phonestringإلزامي

    الرقم بصيغة E.164 بعد التوحيد.

  • statusstringإلزامي

    حالة العملية. انظر جدول الحالات.

    القيم:pendingsentverifiedfailedexpiredcanceled

  • channelstring | nullإلزامي

    آخر قناة جُرّبت، أو التي وصل منها الرمز.

  • channelsstring[]إلزامي

    سلسلة القنوات المطلوبة بالترتيب.

  • attemptsintegerإلزامي

    عدد الفحوصات حتى الآن.

  • max_attemptsintegerإلزامي

    حد الفحوصات من إعدادات المشروع (الافتراضي 5).

  • attempts_remainingintegerإلزامي

    الفحوصات المتبقية.

  • localestringإلزامي

    لغة الرسالة.

    القيم:aren

  • metadataobjectإلزامي

    بياناتك كما أرسلتها، أو {}.

  • expires_atstringإلزامي

    نهاية صلاحية الرمز.

  • verified_atstring | nullإلزامي

    وقت التحقق الناجح.

  • created_atstringإلزامي

    وقت الإنشاء.

  • price_milliintegerإلزامي

    صافي ما خُصم لكل المحاولات بالـ milli-IQD (1 دينار = 1000).

  • messagesmessage[]إلزامي

    محاولة لكل قناة جُرّبت، بالترتيب.

    عرض الحقول الفرعية
    • idstring

      معرّف محاولة الإرسال.

    • objectstring

      دائماً message.

    • verification_idstring

      عملية التحقق التي تتبعها المحاولة.

    • channelstring

      القناة.

      القيم:whatsapptelegramsms

    • providerstring

      المزوّد الذي نفّذ المحاولة: meta_cloud (رقم Watsy على واتساب)، whatsapp_own (رقمك الخاص)، telegram_gateway، أو test في وضع الاختبار.

    • statusstring

      delivered يظهر عندما يرسل المزوّد تقرير تسليم (واتساب حالياً).

      القيم:pendingsentdeliveredfailed

    • error_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.

أخطاء أخرى

HTTPcodeمتى
402spend_cap_reachedتجاوز حد الصرف الشهري للمشروع
403forbiddenIP خادمك خارج القائمة المسموحة
403test_number_requiredمفتاح اختبار مع رقم غير مسجّل كرقم اختبار
409idempotency_conflictتعارض في Idempotency-Key
503no_channel_availableلا قناة مفعّلة ومسعّرة لوجهة الرقم