الأجهزة

أضف أرقام واتساب واعرضها واربطها، واضبط حدود إرسالها.

الجهاز رقم واتساب واحد. يضيف أغلب المستخدمين الأجهزة ويربطونها من لوحة التحكم (راجع الأجهزة)، ويتيح الـ API لبرنامجك فعل الشيء نفسه.

فصل الرقم وحذف الجهاز يتمّان من لوحة التحكم فقط.

كائن الجهاز

الحقل	النوع	المعنى
`id`	رقم	معرّف الجهاز، يُستخدم في الروابط مثل `/v1/devices/1/messages`.
`label`	نص	الاسم الذي أعطيته للجهاز.
`phone_number`	نص أو `null`	الرقم المرتبط، أرقامًا فقط. `null` حتى أول ربط.
`status`	نص	`pending_qr` أو `connected` أو `disconnected` أو `logged_out`. راجع الحالات.
`daily_cap`	رقم أو `null`	الحد اليومي للإرسال. `null` تعني الحد الافتراضي.
`hourly_cap`	رقم أو `null`	الحد بالساعة. `null` تعني الحد الافتراضي.

إضافة جهاز

POST /v1/devices

حقل المحتوى	مطلوب	المعنى
`label`	نعم	اسم للجهاز.

curl -X POST https://api.wa.goupdev.net/v1/devices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Sales"}'

الرد 201:

{
  "id": 7,
  "tenant_id": 3,
  "label": "Sales",
  "phone_number": null,
  "status": "pending_qr",
  "daily_cap": null,
  "hourly_cap": null,
  "created_at": "2026-10-08T09:30:00.000Z"
}

بعدها اطلب رمز QR (أدناه) وامسحه.

الخطأ	السبب
`400 {"error": "label is required"}`	الحقل `label` مفقود أو فارغ.
`402 {"error": "Device Quota reached"}`	لا تسمح باقتك بمزيد من الأجهزة.

طلب رمز QR

GET /v1/devices/{id}/qr

الرد 200، والرمز صورة PNG يمكنك وضعها مباشرة في <img src="...">:

{ "qr": "data:image/png;base64,iVBORw0KGgo..." }

يتغير الرمز كل بضع ثوانٍ، وتنتهي صلاحية كل رمز بعد 30 ثانية. اطلبه كل بضع ثوانٍ واعرض أحدثه حتى تصبح حالة الجهاز connected.

الخطأ	السبب
`404 {"error": "No QR available. Device may already be connected."}`	لا يوجد رمز الآن: الجهاز متصل، أو الرمز التالي لم يجهز بعد. تحقق من `status`.
`404 {"error": "Device not found"}`	لا يوجد جهاز بهذا المعرّف في مؤسستك.

عرض الأجهزة

GET /v1/devices

الرد 200: مصفوفة من كائنات الأجهزة، الأقدم أولًا. لكل جهاز أيضًا last_connected_at: وقت آخر اتصال، أو null.

[
  {
    "id": 7,
    "label": "Sales",
    "phone_number": "9665XXXXXXXX",
    "status": "connected",
    "daily_cap": null,
    "hourly_cap": null,
    "last_connected_at": "2026-10-08T09:31:12.000Z"
  }
]

عرض جهاز واحد

GET /v1/devices/{id}

الرد 200: كائن الجهاز مع tenant_id. استخدمه للتحقق من status قبل الإرسال.

الخطأ	السبب
`400 {"error": "invalid id"}`	المعرّف ليس عددًا صحيحًا موجبًا.
`404 {"error": "Device not found"}`	لا يوجد جهاز بهذا المعرّف في مؤسستك.

ضبط حدود الإرسال

PATCH /v1/devices/{id}

حقل المحتوى	المعنى
`dailyCap`	أكبر عدد من الرسائل خلال 24 ساعة. `null` للحد الافتراضي. احذفه لإبقاء القيمة الحالية.
`hourlyCap`	أكبر عدد من الرسائل خلال ساعة. `null` للحد الافتراضي. احذفه لإبقاء القيمة الحالية.

curl -X PATCH https://api.wa.goupdev.net/v1/devices/7 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dailyCap": 300, "hourlyCap": 40}'

الرد 200:

{ "id": 7, "daily_cap": 300, "hourly_cap": 40 }

الخطأ	السبب
`400 {"error": "Cap exceeds admin ceiling"}`	أحد الحدود أعلى من الحد الأقصى المسموح.
`404 {"error": "Device not found"}`	لا يوجد جهاز بهذا المعرّف في مؤسستك.

إعادة الاتصال

POST /v1/devices/{id}/reconnect

يبدأ اتصال الجهاز من جديد. للجهاز الذي حالته logged_out يظهر بعدها رمز QR جديد لمسحه. الرد 200: كائن الجهاز.

كائن الجهازنسخ رابط العنوان

إضافة جهازنسخ رابط العنوان

طلب رمز QRنسخ رابط العنوان

عرض الأجهزةنسخ رابط العنوان

عرض جهاز واحدنسخ رابط العنوان

ضبط حدود الإرسالنسخ رابط العنوان

إعادة الاتصالنسخ رابط العنوان