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_….

سەرپەڕەکان (Headers)

  • 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لا قناة مفعّلة ومسعّرة لوجهة الرقم