اربط أنظمتك برسائل واتساب الرسميّة

واجهة REST بسيطة بمفتاح واحد، وأحداث موقّعة تصلك لحظة بلحظة — ابدأ في بيئة تجريبيّة لا تصل رسائلها لأحد.

عنوان الواجهة

https://whatsapp.nawa-tech.com/api/v1

المصادقة

كلّ طلب يحمل الترويسة x-api-key بمفتاحك من البوّابة — ويُدوَّر من «الربط البرمجيّ».

البيئة

كلّ استجابة تحمل environment: sandbox (تجريبيّ — محاكاة لا تصل أحداً) أو live.

ابدأ في ثلاث خطوات

أنشئ حساباً تجريبيّاً مجّانيّاً من البوّابة واحفظ مفتاحك وسرّ التوقيع. افتح البوّابة
أرسل أوّل رسالة (محاكاة في التجريبيّ).
استقبل الأحداث على رابطك وتحقّق من توقيعها — ثمّ اطلب التشغيل الحيّ.

curl -X POST https://whatsapp.nawa-tech.com/api/v1/messages/text \
  -H "x-api-key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"clientMessageId":"order-10045","to":"9665XXXXXXXX","templateName":"order_ready","templateLang":"ar","templateParams":["Ahmed","#10045"]}'

const r = await fetch('https://whatsapp.nawa-tech.com/api/v1/messages/text', {
  method: 'POST',
  headers: { 'x-api-key': process.env.SENDTO_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ clientMessageId: 'order-10045', to: '9665XXXXXXXX',
    templateName: 'order_ready', templateLang: 'ar', templateParams: ['Ahmed', '#10045'] }),
});
const out = await r.json(); // { success, environment, data: { status, messageId, ... } }

حدّ الطلبات للدقيقة لكلّ حساب (429 مع Retry-After) · الدفعة حتى 1000 نصّيّة و50 بوسائط · الوسيط حتى 5MB · الطلب حتى 20MB.

البدء والحالة

GET/api/v1/healthبلا مفتاح

حيّة؟

بلا مفتاح — هل الخدمة تعمل.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/health

الاستجابة

{
  "success": true,
  "service": "sendto-cloudapi-mini",
  "now": "2026-09-26T10:00:00.000Z"
}

GET/api/v1/readinessx-api-key

جاهزيّةُ الإرسال

هل قالبُ الدعوة معتمَدٌ عند Meta وأرقامُكم جاهزة.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/readiness \
  -H "x-api-key: sk_..."

GET/api/v1/limitsx-api-key

الطاقةُ اليوم

طاقةُ أرقامكم اليوم وموعدُ التصفير.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/limits \
  -H "x-api-key: sk_..."

GET/api/v1/sender/healthx-api-key

صحّةُ الأرقام

overall · readyForSending · aggregateCapacity · qualityRating · وسقوفُ حسابكم (fromApplication).

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/sender/health \
  -H "x-api-key: sk_..."

GET/api/v1/templatesx-api-key

القوالب

قوالبُكم: الحالة · الفئة · عددُ المتغيّرات · الرأس · الأزرار · usable.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/templates \
  -H "x-api-key: sk_..."

الإرسال

POST/api/v1/messages/textx-api-key

رسالةٌ واحدة

200 بالنتيجة مباشرةً · 202 للمجدولة أو المؤجَّلة بحاجز (والسببُ في message.deferred) · وتكرارُ clientMessageId يعيد النتيجةَ الأصليّة (duplicate: true).

الحقل	النوع	إلزاميّ	الوصف
clientMessageId	string	نعم	معرّفكم للرسالة (8–128) — مفتاحُ المطابقة ومنعِ التكرار 48 ساعة
to	string	نعم	رقمُ المستلم دوليّاً بالأرقام (8–20)
templateName	string		قالبٌ معتمَد — لازمٌ خارج نافذة المحادثة (24 ساعة)
templateLang	string		لغةُ القالب (ar · en …)
templateParams	string[]		متغيّراتُ القالب بالترتيب
message	string		نصٌّ حرّ — داخل نافذة المحادثة فقط
kind	"notification" \| "invitation"		الافتراض notification · الدعوة تحتاج eventId أو expiresAt
eventId	string		مناسبةٌ مسجَّلة (POST /events)
expiresAt	ISO-8601		انتهاءُ صلاحية الدعوة
scheduledFor	ISO-8601		لا تخرج قبله (حتى سنة)
deadline	ISO-8601		بعده تنتهي بلا إرسال (expired) وتعود لرصيدكم
mediaBase64 / mediaId	string		صورة jpeg/png أو PDF حتى 5MB (أو معرّفُ رفعٍ سابق) مع type: image\|document
sentFrom · fromPolicy	string · "prefer"\|"strict"\|"auto"		رقمُ إرسالٍ مطلوب وسياستُه
meta	object ≤ 4KB		يعود إليكم حرفيّاً في كلّ حدث
buttonUrl	https URL		رابطُكم لزرّ القالب (بطاقةُ المحفظة · صفحةُ الحجز) — نخزّنه ويفتح الضيفُ رابطاً عندنا يحوّله إليه ونعدّ الفتحات · لقالبٍ زرُّه على نطاقنا وحدَه
buttonPayloads	string[] (1–10 · كلٌّ 1–128)		حمولاتُ أزرار الردّ السريع بترتيبها في القالب — تعود إليكم حرفاً في message.received عند الضغط (حسابات raw · بلا حمولةٍ ⇒ clientMessageId)

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/messages/text \
  -H "x-api-key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"clientMessageId":"order-10045","to":"9665XXXXXXXX","templateName":"order_ready","templateLang":"ar","templateParams":["Ahmed","#10045"]}'

الاستجابة

{
  "success": true,
  "environment": "live",
  "data": {
    "clientMessageId": "order-10045",
    "messageId": "wamid.HBgM…",
    "status": "sent",
    "sentFrom": "9665XXXXXXXX",
    "fallbackUsed": false,
    "sentAt": "2026-09-26T10:00:01.000Z",
    "duplicate": false
  }
}

أكواد الخطأ

VALIDATION_ERROR INVALID_PHONE RECIPIENT_NOT_ALLOWLISTED BUTTON_URL_UNSUPPORTED INVALID_URL TEMPLATE_REQUIRED INVALID_BUTTON_PAYLOAD NO_ACTIVE_SUBSCRIPTION SUBSCRIPTION_EXPIRED QUOTA_EXHAUSTED FOLLOWUP_QUOTA_EXHAUSTED INVOICE_OVERDUE USAGE_CREDIT_LIMIT PARTNER_CAPACITY_EXHAUSTED

POST/api/v1/messages/otpx-api-key

رمزُ الدخول

بقالب «تحقّق» من Meta (نصُّه ثابتٌ منها) وزرِّ نسخ الرمز — أولويّةٌ أولى · لا يحجبه إيقافُ التسويق · وما لم يخرج خلال مهلته (10 دقائق افتراضاً) ينتهي ولا يُرسَل متأخّراً · والرمزُ يُمحى من سجلّاتنا بعد النهاية.

الحقل	النوع	إلزاميّ	الوصف
to	string	نعم	الرقمُ دوليّاً بالأرقام
code	string (1–15)	نعم	الرمز — بلا مسافات ولا روابط (حدُّ Meta)
clientMessageId · ttlSeconds · meta	string · integer (60–3600) · object		اختياريّة — ttlSeconds افتراضاً 600

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/messages/otp \
  -H "x-api-key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"to":"9665XXXXXXXX","code":"482913"}'

الاستجابة

{
  "success": true,
  "environment": "live",
  "data": {
    "clientMessageId": "otp_…",
    "messageId": "wamid.HBgM…",
    "status": "sent",
    "sentFrom": "9665XXXXXXXX",
    "duplicate": false
  }
}

أكواد الخطأ

INVALID_OTP INVALID_PHONE RECIPIENT_NOT_ALLOWLISTED VALIDATION_ERROR

POST/api/v1/messages/bulkx-api-key

دفعة

حتى 1000 نصّيّة و50 بوسائط · 202 بخمس قوائم: accepted · rejected (بكود كلّ رسالة) · duplicates (خلال 48 ساعة) · held · atRisk — و estimatedCompletionAt تقديرٌ محافظ. حقولُ الرسالة على الغلاف تُردّ FIELD_NOT_ALLOWED_IN_BULK.

الحقل	النوع	إلزاميّ	الوصف
messages	Message[]	نعم	حقولُ كلّ رسالة كما في «رسالةٌ واحدة»
batchName	string		اسمٌ للدفعة
eventId	string		مناسبةُ الدفعة
fromPolicy	string		سياسةٌ للدفعة كلّها

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/messages/bulk \
  -H "x-api-key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"batchName":"reminders-sep","messages":[{"clientMessageId":"rem-0001","to":"9665XXXXXXXX","templateName":"order_ready","templateLang":"ar","templateParams":["Sara","#1"]}]}'

الاستجابة

{
  "success": true,
  "environment": "live",
  "data": {
    "batchId": "b1f…",
    "batchName": "reminders-sep",
    "eventId": null,
    "total": 1,
    "accepted": [
      {
        "clientMessageId": "rem-0001"
      }
    ],
    "held": [],
    "atRisk": [],
    "rejected": [],
    "duplicates": [],
    "estimatedCompletionAt": "2026-09-26T10:05:00.000Z"
  }
}

أكواد الخطأ

VALIDATION_ERROR BATCH_TOO_LARGE FIELD_NOT_ALLOWED_IN_BULK INVALID_FROM_POLICY

POST/api/v1/messages/richx-api-key

رسالةٌ غنيّة

صورةُ رأسٍ + نصّ + حتى 3 أزرار ردّ (أو زرُّ رابطٍ واحد). داخل نافذة المحادثة، أو بقالبٍ معتمَد خارجها. زرُّ الاتّصال وcopyCode غيرُ متاحَين في الرسميّ (400 unsupported).

الحقل	النوع	إلزاميّ	الوصف
clientMessageId	string	نعم	معرّفكم للرسالة (8–128) — مفتاحُ المطابقة ومنعِ التكرار 48 ساعة
to	string	نعم	رقمُ المستلم دوليّاً بالأرقام (8–20)
message	string ≤ 1024	نعم	المتن
buttons	{id,text}[] \| [{text,url}]	نعم	نصُّ الزرّ ≤ 20 محرفاً
headerImage	base64 \| data:		صورةُ الرأس
title · footer	string ≤ 60		العنوانُ والتذييل

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/messages/rich \
  -H "x-api-key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"clientMessageId":"card-2201","to":"9665XXXXXXXX","message":"تذكرتك جاهزة","buttons":[{"id":"confirm","text":"تأكيد"},{"id":"decline","text":"اعتذار"}]}'

أكواد الخطأ

VALIDATION_ERROR SERVICE_WINDOW_CLOSED NO_ACTIVE_SUBSCRIPTION SUBSCRIPTION_EXPIRED QUOTA_EXHAUSTED FOLLOWUP_QUOTA_EXHAUSTED INVOICE_OVERDUE USAGE_CREDIT_LIMIT PARTNER_CAPACITY_EXHAUSTED

POST/api/v1/messages/uploadx-api-key

رفعُ وسيط

ارفع مرّةً واستعمل mediaId في رسائلَ كثيرة (بلا تكرارٍ للمحتوى).

الحقل	النوع	إلزاميّ	الوصف
mediaBase64	string	نعم	jpeg/png/pdf حتى 5MB
mimetype · filename	string		اختياريّان

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/messages/upload \
  -H "x-api-key: sk_..."

الاستجابة

{
  "success": true,
  "environment": "live",
  "data": {
    "mediaId": "ast_…",
    "mimetype": "image/png",
    "bytes": 48211
  }
}

أكواد الخطأ

MEDIA_TOO_LARGE INVALID_MEDIA

POST/api/v1/feedback/sendx-api-key

إرسالُ نموذج تقييم

نموذجُ تقييمٍ أنشأتموه في البوّابة ووافقنا عليه ونُشر عند Meta — يصل الضيفَ بزرٍّ يفتحه داخل واتساب. **مرّةً واحدةً لكلّ رقمٍ** (ALREADY_SENT) · **والردُّ الأوّلُ وحدَه يُحسب** ويصلكم feedback.submitted بنصوص الأسئلة · والتجريبيُّ يُرسل النموذجَ الجاهزَ محاكاةً.

الحقل	النوع	إلزاميّ	الوصف
formId	string	نعم	معرّفُ النموذج (أيُّ نسخةٍ منه — تُرسَل أحدثُ نسخةٍ منشورة)
to	string	نعم	رقمُ الضيف دوليّاً بالأرقام
clientMessageId	string		معرّفكم — تكرارُه يعيد النتيجةَ الأصليّة (duplicate:true)

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/feedback/send \
  -H "x-api-key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"formId":"6f1c…","to":"9665XXXXXXXX","clientMessageId":"visit-10045-rating"}'

الاستجابة

{
  "success": true,
  "environment": "live",
  "data": {
    "sendId": "a3b…",
    "jobId": "9e2…",
    "formId": "6f1c…",
    "version": 1,
    "to": "9665XXXXXXXX",
    "status": "queued",
    "duplicate": false
  }
}

أكواد الخطأ

FORM_NOT_FOUND FORM_NOT_SENDABLE ALREADY_SENT DUPLICATE_CLIENT_MESSAGE_ID RECIPIENT_NOT_ALLOWLISTED VALIDATION_ERROR

المتابعة والإلغاء

GET/api/v1/messages/:cidx-api-key

حالُ رسالة

timeline · invitation · attempts · error · meta — بمعرّفكم clientMessageId.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/messages/{cid} \
  -H "x-api-key: sk_..."

أكواد الخطأ

MESSAGE_NOT_FOUND

POST/api/v1/linksx-api-key

رابطُ تحويل

رابطٌ عندنا يحوّل إلى رابطكم ويعدّ فتحاته — https ومضيفٌ عامّ.

الحقل	النوع	إلزاميّ	الوصف
url	https URL	نعم	الوجهة
eventId · clientMessageId · expiresAt	string · ISO-8601		اختياريّة

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/links \
  -H "x-api-key: sk_..."

الاستجابة

{
  "success": true,
  "environment": "live",
  "data": {
    "code": "Ab3kP9xQr2",
    "shortUrl": "https://whatsapp.nawa-tech.com/l/Ab3kP9xQr2",
    "url": "https://…",
    "clicks": 0,
    "active": true
  }
}

أكواد الخطأ

INVALID_URL VALIDATION_ERROR

GET/api/v1/links/:codex-api-key

فتحاتُ رابط

clicks · firstClickAt · lastClickAt · active.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/links/{code} \
  -H "x-api-key: sk_..."

أكواد الخطأ

LINK_NOT_FOUND

POST/api/v1/batches/:batchId/cancelx-api-key

إلغاءُ دفعة

يُلغى ما لم يخرج (ويعود لرصيدكم) — وما كان في الإرسال لحظتَها يُعَدّ في inFlight.

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/batches/{batchId}/cancel \
  -H "x-api-key: sk_..."

المناسبات والردود

POST/api/v1/eventsx-api-key

تسجيلُ مناسبة

مواعيدُ الدعوات ونصوصُ الردّ ووجهةُ أحداثها. 201 جديدة · 200 تكرار · 409 EVENT_LOCKED لتغيير الموعد بعد خروج دعوة (إلّا confirmLockedChange: true).

الحقل	النوع	إلزاميّ	الوصف
eventId	string (4–64)	نعم	معرّفُكم للمناسبة
eventDate	ISO-8601	نعم	موعدُ المناسبة
callbackUrl	https URL	نعم	وجهةُ أحداث هذه المناسبة
texts.invalidReply · texts.nudge · texts.expired	string	نعم	نصوصُ الردّ على الضيف
defaults	object		مهلُ الدعوة (expiresAt …) و undeliveredTimeoutMinutes
defaults.sentFrom	string		رقمُ المناسبة الافتراضيّ (من أرقامكم) — تبدأ منه رسائلُها لكلّ ضيفٍ جديد، ومن راسلته يبقى على رقمه · null ⇒ تلقائيّ · ويتغيّر بعد القفل

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/events \
  -H "x-api-key: sk_..."

أكواد الخطأ

VALIDATION_ERROR EVENT_LOCKED INVALID_SENDER

GET/api/v1/events/:eventIdx-api-key

مناسبة

إعداداتُها + sentInvitations.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/events/{eventId} \
  -H "x-api-key: sk_..."

أكواد الخطأ

EVENT_NOT_FOUND

المستقبِلون والإيقاف

POST/api/v1/numbers/checkx-api-key

فحصُ أرقام

حتى 500 — true لمن سُلِّمت إليه رسالةٌ منّا · null لغيره (Meta لا تتيح الفحصَ المسبق — لا false).

الحقل	النوع	إلزاميّ	الوصف
numbers	string[]	نعم	الأرقام

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/numbers/check \
  -H "x-api-key: sk_..."

أكواد الخطأ

BATCH_TOO_LARGE

POST/api/v1/optouts/checkx-api-key

فحصُ الإيقاف

من طلب إيقافَ رسائلكم.

الحقل	النوع	إلزاميّ	الوصف
numbers	string[]	نعم	الأرقام

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/optouts/check \
  -H "x-api-key: sk_..."

DELETE/api/v1/optouts/:phoneNumberx-api-key

رفعُ إيقاف

بطلب صاحب الرقم وحدَه.

الطلب

curl -X DELETE https://whatsapp.nawa-tech.com/api/v1/optouts/{phoneNumber} \
  -H "x-api-key: sk_..."

الأحداث المرسَلة إليكم

نرسل كلّ حدث POST بـ JSON إلى رابطك (أو callbackUrl المناسبة). أيّ 2xx خلال 10 ثوانٍ نجاح — وإلّا نعيد: فوراً ثمّ بعد 10ث · 1د · 5د · 30د · 2س (ستّ محاولات) ثمّ يظهر في GET /api/v1/webhooks/failed.

الترويسات

X-Timestamp: 1790000000
X-Signature: sha256=hex(HMAC_SHA256(secret, "<X-Timestamp>.<rawBody>"))
X-Webhook-Id: whk_…   X-Delivery-Attempt: 1

تحقّق من التوقيع — Node.js

const crypto = require('crypto');
// rawBody: the exact request body string · ts: X-Timestamp · sig: X-Signature
function verify(rawBody, ts, sig, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

تحقّق من التوقيع — PHP

<?php
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_TIMESTAMP'];
$sig = $_SERVER['HTTP_X_SIGNATURE'];
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
$ok = abs(time() - (int)$ts) < 300 && hash_equals($expected, $sig);

الأحداث

message.status	sent · delivered · read · failed (بكودٍ وتفسيرٍ وإجراء) · expired (neverDelivered)
message.deferred	تأجيلٌ بسببه مرّةً لكلّ سبب: نافذةُ الإرسال · حدودُ الأرقام · INVOICE_OVERDUE · SENDING_PAUSED …
message.received	📮 حساباتُ raw: كلُّ ردٍّ خاماً كاملاً (message: نصّ · زرٌّ بحمولتكم · وسيط · موقع …) + repliedTo (button_payload · quoted_message · last_outbound موسوم · none) بـclientMessageId وmeta · lastOutbound · lastOutboundByKind · windowExpiresAt — والتفسيرُ عندكم
guest.confirmed · guest.declined · guest.replied_invalid · guest.unresolved · guest.replied_late · guest.message	ردودُ الضيف على الدعوة (answer · matchConfidence · slotMatch)
guest.opted_out · guest.opted_in	طلبُ الإيقاف ورفعُه
batch.progress · batch.completed	تقدّمُ الدفعة (كلَّ 5% أو 60 ثانية) واكتمالُها مرّةً
sender.health	تغيّرُ حال الرقم أو جودته عند Meta
feedback.submitted	تقييمُ ضيفٍ — الأوّلُ وحدَه: answers بنصوص الأسئلة (rating 1–5 · single · multi · comment) · formId · version · to · clientMessageId · meta

GET/api/v1/webhooks/failedx-api-key

أحداثٌ لم تُسلَّم

ما استُنفدت محاولاتُه الستّ — بحمولته.

الحقل	النوع	إلزاميّ	الوصف
limit · since	number · ISO-8601		اختياريّان

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/webhooks/failed \
  -H "x-api-key: sk_..."

POST/api/v1/webhooks/failed/:webhookId/retryx-api-key

إعادةُ حدث

يعود للتسليم بستّ محاولاتٍ جديدة وبالمعرّف نفسِه.

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/webhooks/failed/{webhookId}/retry \
  -H "x-api-key: sk_..."

GET/api/v1/media/inbound/:wamidبلا مفتاح

ملفُّ ضيف

الرابطُ يصلكم جاهزاً في mediaUrl بأحداث guest.* — موقَّعٌ فيعمل بلا مفتاح (ولو في <img>) · صالحٌ 7 أيّامٍ من الاستلام (صلاحيةُ Meta) ثمّ 410 · ولا نخزّن الملفّ: نزّلوه خلالها.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/media/inbound/{wamid}

أكواد الخطأ

INVALID_SIGNATURE MEDIA_EXPIRED MEDIA_NOT_FOUND META_ERROR

الرصيد والفواتير

الرسالة الفريدة هي الأولى لرقم في اشتراكك، والثانية لنفس الرقم «تابعة». ما لم يُسلَّم يعود لرصيدك. الفاتورة صالحة حتى موعد استحقاقها؛ بعده يُردّ القبول بـ 402 INVOICE_OVERDUE ويُؤجَّل الطابور، ويعود كلّ شيء وحده بالسداد.

GET/api/v1/balancex-api-key

الرصيد

الباقة · النوع (PACKAGE · MONTHLY · USAGE) · الحصّة (فريدة/تابعة) · مالُ «حسب الاستخدام» · suspended والفواتيرُ المفتوحة — وللشريك سعتُه.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/balance \
  -H "x-api-key: sk_..."

الاستجابة

{
  "success": true,
  "environment": "live",
  "data": {
    "billingMode": "ENFORCED",
    "suspended": false,
    "invoices": [],
    "subscription": {
      "package": "الأعمال",
      "billingType": "PACKAGE",
      "state": "ACTIVE",
      "unique": {
        "quota": 5000,
        "used": 1200,
        "remaining": 3800
      },
      "followup": {
        "quota": 1000,
        "used": 40,
        "remaining": 960
      }
    }
  }
}

GET/api/v1/invoicesx-api-key

الفواتير

كلُّ فاتورةٍ صالحةٌ حتى dueAt؛ بعده يتوقّف الإرسال (INVOICE_OVERDUE) ويعود وحدَه بالسداد من البوّابة.

الحقل	النوع	إلزاميّ	الوصف
status	OPEN\|OVERDUE\|PAID\|VOID		اختياريّ

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/invoices \
  -H "x-api-key: sk_..."

الاستجابة

{
  "success": true,
  "environment": "live",
  "data": [
    {
      "number": "INV-2026-000001",
      "kind": "USAGE",
      "status": "OPEN",
      "subtotal": "500.00",
      "vatPct": 0,
      "vatAmount": "0.00",
      "total": "500.00",
      "currency": "SAR",
      "issuedAt": "2026-09-26T10:00:00.000Z",
      "dueAt": "2026-09-27T10:00:00.000Z"
    }
  ]
}

GET/api/v1/invoices/:numberx-api-key

فاتورة

بنودُها ومبالغُها وحالُها.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/invoices/{number} \
  -H "x-api-key: sk_..."

أكواد الخطأ

NOT_FOUND

واجهة الشركاء

GET/api/v1/partner/accountx-api-key لحساب شريك

حسابُ الشريك

السعة (الكلّيّة · المستعمَلة · المتبقّية) · المديونيّة · السقف · المتاح · أقصى زيادةٍ الآن · الانتهاء · التحويلاتُ المنتظرة.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/partner/account \
  -H "x-api-key: sk_..."

الاستجابة

{
  "success": true,
  "environment": "live",
  "data": {
    "currency": "SAR",
    "ratePerMessage": "0.3700",
    "capacity": {
      "total": 20000,
      "used": 5120,
      "remaining": 14880,
      "pct": 26
    },
    "debt": "4000.00",
    "creditLimit": "10000.00",
    "creditAvailable": "6000.00",
    "maxTopupMessages": 16216,
    "expiresAt": null,
    "expired": false,
    "pendingTransfers": []
  }
}

أكواد الخطأ

NOT_A_PARTNER

POST/api/v1/partner/topupsx-api-key لحساب شريك

زيادةُ الحدّ

تُفعَّل فوراً ما دامت المديونيّةُ بعدها ≤ السقف — وإلّا 402 CREDIT_LIMIT_EXCEEDED بالأرقام وبأقصى ما يُطلب الآن.

الحقل	النوع	إلزاميّ	الوصف
messages	integer	نعم	عددُ الرسائل

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/partner/topups \
  -H "x-api-key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"messages":20000}'

أكواد الخطأ

CREDIT_LIMIT_EXCEEDED PARTNER_CAPACITY_EXPIRED INVALID_QUANTITY NOT_A_PARTNER

POST/api/v1/partner/transfersx-api-key لحساب شريك

الإبلاغُ بتحويل

لا يمسّ المديونيّة حتى نؤكّد الاستلام — ويُخصم المبلغُ المستلَم فعلاً.

الحقل	النوع	إلزاميّ	الوصف
amount	number	نعم	المبلغ
reference	string	نعم	رقمُ الحوالة — لا يتكرّر
transferDate · note	date · string		اختياريّان

الطلب

curl -X POST https://whatsapp.nawa-tech.com/api/v1/partner/transfers \
  -H "x-api-key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"amount":5000,"reference":"TRX-88213","transferDate":"2026-09-26"}'

أكواد الخطأ

REFERENCE_REQUIRED DUPLICATE_REFERENCE INVALID_AMOUNT NOT_A_PARTNER

GET/api/v1/partner/ledgerx-api-key لحساب شريك

الدفتر

كلُّ حركةٍ بمديونيّتها بعدها: TOPUP · TRANSFER_REPORTED · TRANSFER_CONFIRMED · TRANSFER_REJECTED · ADJUSTMENT.

الطلب

curl -X GET https://whatsapp.nawa-tech.com/api/v1/partner/ledger \
  -H "x-api-key: sk_..."

كلّ أكواد الخطأ

كلّ خطأ بالشكل { success: false, error: { code, message, … } } — والنصّ يسمّي السبب.

الكود	HTTP	الوصف
UNAUTHORIZED	401	x-api-key غائب
INVALID_API_KEY	401	مفتاحٌ غيرُ معروف
APP_INACTIVE	403	الحسابُ موقوف
RATE_LIMIT_EXCEEDED	429	تجاوزُ حدّ الطلبات في الدقيقة — Retry-After بالثواني
VALIDATION_ERROR	400	حقلٌ غائبٌ أو غيرُ صالح — النصُّ يسمّيه
INVALID_PHONE	400	الرقمُ ليس 8–20 رقماً
FORM_NOT_FOUND	404	لا نموذجَ تقييمٍ بهذا المعرّف لحسابكم
FORM_NOT_SENDABLE	409	النموذجُ لم يُنشر بعد (والتجريبيُّ: لم يُعتمَد بعد)
ALREADY_SENT	409	أُرسل هذا النموذجُ لهذا الرقم من قبل — التقييمُ مرّةً واحدة (previousSendAt)
DUPLICATE_CLIENT_MESSAGE_ID	409	clientMessageId مستعملٌ لرسالةٍ أخرى لهذا الحساب
RECIPIENT_NOT_ALLOWLISTED	403	الرقمُ خارج قائمة المستقبِلين المسموحة
BATCH_TOO_LARGE	400	فوق سقف الدفعة
FIELD_NOT_ALLOWED_IN_BULK	400	حقلُ رسالةٍ على غلاف الدفعة
INVALID_FROM_POLICY	400	fromPolicy: prefer · strict · auto
SERVICE_WINDOW_CLOSED	400	نصٌّ حرٌّ خارج نافذة المحادثة — استعملوا قالباً
MEDIA_TOO_LARGE	400	وسيطٌ فوق 5MB
INVALID_MEDIA	400	نوعٌ غيرُ jpeg/png/pdf
MESSAGE_NOT_FOUND	404	لا رسالةَ بهذا المعرّف
TEMPLATE_REQUIRED	400	templateName مطلوبٌ للدعوة على حسابكم — لا قالبَ افتراضيّ
INVALID_OTP	400	الرمزُ من 1 إلى 15 محرفاً بلا مسافات ولا روابط
INVALID_URL	400	رابطٌ غيرُ صالح — https ومضيفٌ عامّ
BUTTON_URL_UNSUPPORTED	400	زرُّ القالب ليس على نطاقنا — لا يقبل buttonUrl
INVALID_BUTTON_PAYLOAD	400	buttonPayloads: من 1 إلى 10 نصوص، كلٌّ من 1 إلى 128 محرفاً — لا قصَّ صامتاً
LINK_NOT_FOUND	404	لا رابطَ بهذا الرمز
INVALID_SENDER	400	الرقمُ ليس من أرقامكم
INVALID_SIGNATURE	403	رابطٌ غيرُ صالح
MEDIA_EXPIRED	410	انتهت صلاحيةُ الملفّ عند Meta (7 أيّام)
MEDIA_NOT_FOUND	404	لا ملفَّ لهذه الرسالة
META_ERROR	502	تعذّر التنزيلُ من Meta — نصُّها في الرسالة
EVENT_NOT_FOUND	404	لا مناسبةَ بهذا المعرّف
EVENT_LOCKED	409	تغييرُ موعدٍ بعد خروج دعوة — أكّدوه بـconfirmLockedChange
NOT_FOUND	404	غيرُ موجود
NO_ACTIVE_SUBSCRIPTION	402	لا اشتراكَ ساري
SUBSCRIPTION_EXPIRED	402	انتهى الاشتراك
QUOTA_EXHAUSTED	402	نفدت الرسائلُ الفريدة
FOLLOWUP_QUOTA_EXHAUSTED	402	رسالةٌ ثانيةٌ لرقمٍ أُرسل إليه تحتاج رصيدَ «تابعة»
INVOICE_OVERDUE	402	فاتورةٌ لم تُسدَّد في مهلتها — الإرسالُ موقوفٌ حتى السداد (ويحمل رقمَها ومبلغها)
USAGE_CREDIT_LIMIT	402	«حسب الاستخدام»: بلغت المديونيّةُ سقفَها
PARTNER_CAPACITY_EXHAUSTED	402	نفدت سعةُ الشريك — اطلبوا زيادة
PARTNER_CAPACITY_EXPIRED	402	انتهت مدّةُ اتّفاق الشريك
CREDIT_LIMIT_EXCEEDED	402	الزيادةُ تتخطّى سقفَ المديونيّة
INVALID_QUANTITY	400	عددُ الرسائل من 1 إلى 10,000,000
REFERENCE_REQUIRED	400	مرجعُ الحوالة مطلوب
DUPLICATE_REFERENCE	409	المرجعُ أُبلغ به من قبل
INVALID_AMOUNT	400	مبلغٌ غيرُ صالح
NOT_A_PARTNER	403	الواجهةُ للشركاء وحدَهم

SendTo — إحدى خدمات نواة تك