وثائق API.

المصادقة

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

Authorization: Bearer athr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

إرسال رسالة

يُرسل نص أو صورة أو ملف إلى رقم واحد. الطلب يُقبل فوراً (202) ويدخل قائمة الإرسال — تابع الحالة عبر 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" }
// أو، إن كان الرقم لا يستطيع الإرسال الآن، تُقبل الرسالة ويأتيك الحكم في الرد نفسه:
{ "message_id": "01J…", "status": "failed", "error": "number not connected" }

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

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 }

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

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

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

عند بلوغ الحد اليومي accepted → failed in the log

لا نرفض الطلب عند البوابة. يُقبل (202) ويُسجَّل في سجل الإرسال بحالة failed وسبب واضح — نفس الشكل الذي يرجعه GET /v1/messages/:id:

{ "message_id": "01J…", "status": "failed", "error": "daily limit reached" }

الحد يتجدد منتصف كل ليلة بتوقيت السعودية ويرتفع تلقائياً حتى 120 رسالة/يوم للأرقام النظيفة. تكاملك لا يحتاج أي منطق خاص: أرسل، واقرأ الحالة من الرد أو من السجل.

أسباب الفشل التي قد تراها في error

رقم غير متصل لكنه لم يخرج من واتساب يُقبل ويبقى queued — إن عاد الاتصال أُرسلت الرسالة، وإلا فشلت في السجل بسبب واضح. الرسائل التي تصل أثناء صيانة مؤقتة من جهتنا تنتظر وتُرسل تلقائياً بعدها.

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

الوتيرة

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

رموز الأخطاء

كل خطأ يرجع بهيكل موحد: { "error": { "code": "…", "message": "…" } }. الأخطاء هنا هي أخطاء الطلب نفسه فقط؛ أي سبب يمنع إرسال رسالة مقبولة يظهر في حالتها لا كرمز HTTP.