Barqiaبَرقية
اطلب وصول API← الرئيسية

واجهة بَرقية للمطوّرين

اربط منصّتك ببَرقية لإرسال رسائل واتساب والقوالب المعتمدة ورموز التحقق (OTP) عبر واجهة Meta الرسمية، واستقبل أحداث المحادثات عبر Webhooks. كل النقاط تحت /api/v1 وتُصادَق بمفتاح API.

المصادقة

كل طلبات الإرسال تُصادَق بمفتاح API يبدأ بـ bqk_. يحصل عليه التاجر من لوحة التحكم (المطوّرين/API) — يُعرض مرّة واحدة فقط. مرّر المفتاح بإحدى ثلاث طرق:

# 1) Authorization header (recommended)
Authorization: Bearer bqk_xxxxxxxxxxxxxxxxxxxx

# 2) query string
https://barqia.net/api/v1/send-message?token=bqk_xxxx

# 3) in the JSON body  →  { "token": "bqk_xxxx", ... }

واجهة API ميزة مدفوعة — تتطلّب باقة تتضمّن API. الطلبات تُحتسب من حصّة رسائلك وتخضع لقيود إلغاء الاشتراك.

نقاط الإرسال

POST/api/v1/send-message

إرسال رسالة نصية (داخل نافذة 24 ساعة).

curl -X POST https://barqia.net/api/v1/send-message \
  -H "Authorization: Bearer bqk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "toNumber": "9665xxxxxxxx", "text": "أهلًا بك في متجرنا 👋" }'
↩︎ Response
{ "success": true, "msg": "تم إرسال الرسالة", "messageId": "wamid.XXX" }
POST/api/v1/send_templet

إرسال قالب معتمد (خارج نافذة 24 ساعة). عدد وترتيب المتغيّرات يجب أن يطابق القالب المعتمد.

curl -X POST https://barqia.net/api/v1/send_templet \
  -H "Authorization: Bearer bqk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumber": "9665xxxxxxxx",
    "template_name": "barqia_booking_confirm",
    "language": "ar",
    "body_params": ["محمد", "خدمة التنظيف", "2026-07-01", "5:00 م"],
    "buttons": [{ "sub_type": "url", "index": 0, "parameter": "123" }]
  }'
↩︎ Response
{ "success": true, "msg": "تم إرسال القالب", "messageId": "wamid.XXX" }
POST/api/v1/otp/send

توليد وإرسال رمز تحقق من 6 خانات عبر قالب. صلاحية 5 دقائق، مع حدود إرسال (دقيقة/ساعة/يوم).

curl -X POST https://barqia.net/api/v1/otp/send \
  -H "Authorization: Bearer bqk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "toNumber": "9665xxxxxxxx", "template_name": "verify_code", "language": "ar" }'
↩︎ Response
{ "success": true, "msg": "تم إرسال رمز التحقق", "expiresInSeconds": 300 }
POST/api/v1/otp/verify

التحقق من الرمز. 5 محاولات كحد أقصى لكل رمز.

curl -X POST https://barqia.net/api/v1/otp/verify \
  -H "Authorization: Bearer bqk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "toNumber": "9665xxxxxxxx", "code": "123456" }'
↩︎ Response
{ "success": true, "verified": true, "msg": "تم التحقق" }

Webhooks (الأحداث الواردة)

سجّل رابط HTTPS من لوحة التحكم لاستقبال الأحداث. كل طلب موقَّع بـ HMAC-SHA256 في ترويسة X-Barqia-Signature لتتحقق منه.

  • message.received — رسالة واردة من عميل
  • message.status — تغيّر حالة الرسالة (تسليم/قراءة/فشل)
  • form.submitted — إرسال نموذج واتساب
POST  https://your-server.com/webhook   (your registered URL)
X-Barqia-Event: message.received
X-Barqia-Signature: sha256=<hex_hmac_of_raw_body>

{ "chat_id": "...", "from": "9665xxxxxxxx", "name": "محمد",
  "type": "button", "text": "تأكيد", "button_payload": "CONFIRM_123",
  "meta_msg_id": "wamid.XXX" }

تحقّق من التوقيع: HMAC-SHA256 للجسم الخام بالمفتاح السري (whsec_) الذي يظهر مرّة عند إنشاء الـ Webhook.

الحدود والملاحظات

  • حد عام: 100 طلب/دقيقة لكل عنوان.
  • OTP: تهدئة 60 ثانية + 5/ساعة + 20/يوم لكل رقم.
  • الأرقام بصيغة دولية بدون + (مثال: 9665xxxxxxxx).
  • الاستجابة JSON دائمًا، والأخطاء تُعيد success=false مع msg.

اطلب وصول API / شراكة

منصّتك تريد الربط مع بَرقية؟ أرسل بيانات منصّتك وحالة الاستخدام. يراجع فريقنا الطلب، وبعد الموافقة المبدئية تُرفع المستندات الرسمية بأمان داخل الحساب ثم يُصدَر مفتاح API.

© بَرقية — جميع الحقوق محفوظة