أثر — وثائق API للمطورين

Authentication

المصادقة

كل طلب يحمل مفتاحك في ترويسة Authorization. تنشئ المفاتيح من لوحة التحكم (مفاتيح API) — يظهر السرّ مرة واحدة عند الإنشاء فاحفظه بأمان، ويمكنك إلغاؤه فوراً في أي وقت.

Authorization: Bearer athr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

المفاتيح القديمة بالبادئة hud_live_ ما تزال صالحة. طلب بلا مفتاح صحيح يرجع 401 unauthorized.

POST/v1/messages

إرسال رسالة

يُرسل نص أو صورة أو ملف إلى رقم واحد. الطلب يُقبل فوراً (202) ويدخل قائمة الإرسال — تابع الحالة عبر message_id.

الحقول

الحقل	النوع	الوصف
`to`	نص · مطلوب	رقم المستلم. تُقبل الصيغ السعودية المعتادة: `0512345678` أو `966512345678` أو `+966512345678` (وحتى الأرقام العربية ٠٥…).
`type`	نص · اختياري	`text` (الافتراضي) أو `image` أو `document`. الفيديو غير مدعوم (`415`).
`text`	نص	نص الرسالة — مطلوب عندما يكون النوع `text`.
`media_url`	رابط	رابط `https` عام للصورة أو الملف — مطلوب للنوعين `image` و`document`. الروابط الداخلية/الخاصة مرفوضة.
`caption`	نص · اختياري	تعليق يظهر مع الصورة أو الملف.
`filename`	نص · اختياري	اسم الملف المعروض للمستلم (للنوع `document`).
`instance_id`	نص · اختياري	اتركه فارغاً — حسابك يحوي رقم واتساب واحداً ويُحدَّد تلقائياً.
`idempotency_key`	نص · اختياري	مفتاح فريد من عندك: تكرار الطلب بنفس المفتاح يرجع نفس `message_id` دون إرسال مكرر. مفيد عند إعادة المحاولة بعد انقطاع.

أمثلة

# text — رسالة نصية
curl -X POST https://api.athrcom.com/v1/messages \
  -H "Authorization: Bearer athr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"0512345678","text":"تذكير: اجتماع أولياء الأمور غداً الساعة ٧ مساءً"}'

# image — صورة مع تعليق
curl -X POST https://api.athrcom.com/v1/messages \
  -H "Authorization: Bearer athr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"0512345678","type":"image","media_url":"https://example.com/schedule.png","caption":"جدول الأسبوع"}'

# document — ملف PDF باسم ظاهر
curl -X POST https://api.athrcom.com/v1/messages \
  -H "Authorization: Bearer athr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"0512345678","type":"document","media_url":"https://example.com/report.pdf","filename":"تقرير-الطالب.pdf"}'

الاستجابة الناجحة 202 Accepted

{ "message_id": "01J…", "status": "queued" }

القبول (202) يعني دخول الرسالة قائمة الإرسال — لا يعني التسليم الفوري. الإرسال الفعلي يجري بوتيرة طبيعية مدروسة حفاظاً على جودة رقمك (انظر «الحدود والإيقاع»).

GET/v1/messages/{id}

متابعة الحالة

curl https://api.athrcom.com/v1/messages/01J… \
  -H "Authorization: Bearer athr_live_…"

{ "message_id": "01J…", "status": "sent", "error": null,
  "queued_at": 1781200000000, "sent_at": 1781200042000, "delivered_at": null }

الحالة	المعنى
`queued`	في قائمة الإرسال (تشمل الانتظار لنافذة الإرسال أو لدور الرسالة في الوتيرة).
`sending`	قيد الإرسال الآن.
`sent`	سُلِّمت إلى واتساب بنجاح.
`delivered`	وصل إشعار التسليم لجهاز المستلم.
`failed`	تعذّر الإرسال — التفاصيل في حقل `error`.

الطوابع الزمنية أعداد ميلّي‑ثانية (Unix epoch ms).

Limits & Pacing

الحدود والإيقاع

نرفع حدّ الإرسال تدريجياً مع ثبات رقمك — وتيرة مدروسة وسلوك قريب من الاستخدام الطبيعي يحميان جودة الرقم:

المرحلة	عمر الرقم	الحد اليومي
1	الأسبوع الأول	`30` رسالة/يوم
2	الأسبوع الثاني	`120` رسالة/يوم
3	الأسبوع الثالث	`400` رسالة/يوم
4	بعد ٢١ يوماً	`1,000` رسالة/يوم

عند بلوغ الحد اليومي 429 cap_exceeded

{ "error": {
    "code": "cap_exceeded",
    "message": "بلغت الحدّ اليومي (30 رسالة) لهذا الرقم. …",
    "daily_cap": 30,
    "resets_at": "2026-06-13T21:00:00.000Z",
    "resets_at_ms": 1781730000000 } }

الحد يتجدد منتصف كل ليلة بتوقيت السعودية ويرتفع تلقائياً مع تقدم مراحل الإحماء. عالجها في تكاملك كجدولة لليوم التالي، لا كفشل.

نافذة الإرسال

الإرسال يجري بين 06:00 و24:00 بتوقيت السعودية. الطلبات خارج هذه النافذة تُقبل (202) وتبقى queued حتى السادسة صباحاً ثم تُرسل تلقائياً — احتراماً لأوقات الأهالي وحفاظاً على سمعة رقمك.

الوتيرة

تُرسَل الرسائل تباعاً بوتيرة طبيعية (حتى ~5 رسائل في الدقيقة لكل رقم) — الدفعة الكبيرة تتوزع تلقائياً.
قد تتأخر الرسالة حتى ~5 دقائق عن لحظة الطلب (توزيع مدروس) — صمّم تكاملك على «الإرسال خلال دقائق» لا «فوراً».
الطلبات المتلاحقة جداً على الواجهة نفسها قد ترجع 429 rate_limited — أعد المحاولة بعد ثوانٍ.

Errors

رموز الأخطاء

كل خطأ يرجع بهيكل موحد: { "error": { "code": "…", "message": "…" } }

HTTP	الرمز	المعنى
`400`	`invalid_request`	حقل ناقص أو غير صالح — التفاصيل في `message`.
`401`	`unauthorized`	مفتاح API مفقود أو غير صحيح أو ملغى.
`402`	`payment_required`	لا اشتراك نشطاً — فعّل الاشتراك من لوحة التحكم (الفوترة).
`404`	`not_found`	الرسالة أو الجهاز غير موجود، أو لا رقم واتساب مرتبطاً بالحساب بعد.
`409`	`instance_not_ready`	رقمك غير متصل حالياً (إعادة اتصال أو يحتاج إعادة ربط من لوحة التحكم).
`415`	`unsupported_type`	نوع غير مدعوم — الفيديو غير متاح.
`429`	`cap_exceeded`	بلغت الحد اليومي — انظر «الحدود والإيقاع».
`429`	`rate_limited`	طلبات متلاحقة أكثر من اللازم — أعد المحاولة بعد ثوانٍ.
`500`	`internal`	خطأ من جهتنا — أعد المحاولة، وإن استمر تواصل معنا.