توثيق الـ REST API

آخر تحديث: 2026-10-14

المصادقة بمفتاح API من «المفاتيح والمعرّفات» بلوحة التطبيق، بالهيدر Authorization: Key ap_…. كل الطلبات والردود JSON. الحد الافتراضي 600 طلب بالدقيقة لكل تطبيق.

إرسال إشعار

POST /api/v1/notifications

curl

curl -X POST https://arabpush.com/api/v1/notifications \
  -H "Authorization: Key $ARABPUSH_KEY" -H "Content-Type: application/json" \
  -d '{
    "app_id": "APP_ID",
    "included_segments": ["Subscribed Users"],
    "excluded_segments": ["VIP"],
    "headings": { "ar": "عرض اليوم", "en": "Deal of the day" },
    "contents": { "ar": "خصم 30% لحد منتصف الليل", "en": "30% off until midnight" },
    "url": "https://shop.example/deal",
    "big_picture": "https://shop.example/banner.jpg",
    "buttons": [{ "id": "buy", "text": "اشتري", "url": "https://shop.example/buy" }],
    "data": { "order_id": "42" },
    "send_after": "2026-11-01T09:00:00Z",
    "delayed_option": "timezone",
    "delivery_time_of_day": "9:00AM",
    "idempotency_key": "deal-2026-11-01"
  }'

الجمهور: included_segments و excluded_segments (أسماء أو معرّفات)، أو include_aliases.external_id، أو include_subscription_ids.
template_id: بيبعث قالب جاهز، والحقول اللي بتبعتها بتتغلّب عليه.
idempotency_key (أو الهيدر Idempotency-Key): نفس المفتاح يعني نفس الإشعار، وما بينبعت مرتين.
الرد: { "id": "…", "recipients": 1234, "status": "queued" }

حالة إشعار وإلغاؤه

GET /api/v1/notifications/:id · DELETE /api/v1/notifications/:id (للمجدول أو الجاري) · GET /api/v1/notifications?limit=50&offset=0

المستخدمون

POST /api/v1/users بـ external_id و tags و language و timezone · GET/PATCH/DELETE /api/v1/users/by/external_id/:id (الحذف بيمسح كل اشتراكاته وسجلاته).

الشرائح والقوالب

GET/POST /api/v1/segments · DELETE /api/v1/segments/:id · GET/POST /api/v1/templates · GET/PATCH/DELETE /api/v1/templates/:id

segment

{ "name": "نشطين بالأردن",
  "filters": [[ { "field": "country", "op": "eq", "value": "JO" },
                { "field": "last_session", "op": "lt", "value": 168 } ]] }

الأخطاء

401 مفتاح ناقص أو غلط · 403 app_id مش تبع المفتاح · 400 بيانات غير صالحة (الرد فيه errors) · 400 أو 402 حد الخطة · 404 مش موجود · 429 تجاوز حد الطلبات.