مرجع · v1

مرجع API ايتوس

نقاط الاتصال التي تستخدمها إضافة ووردبريس وموقع aetosseo.com للتواصل مع Cloudflare Worker. الإصدار v1 مستقر. آخر تحديث 2026-08-10.

Base URLhttps://aetos-api.sa7fy-af.workers.dev

المبادئ

Public-first

الـ endpoints العامة مصمّمة تتنادى بدون session token. الـ endpoints الإدارية تحت /admin/* بتتطلب bearer token (مش documented public).

موقّع لما يهم

ردود license check بتحمل توقيع Ed25519 من السيرفر. الـ plugin بيرفض ردود غير موقّعة. ده البوابة الموثوقة، والفحوصات المحلية defense-in-depth.

URLs ثابتة

الـ versioning في الـ path (/v1/). مش هنكسر contract لـ endpoint v1. شكل جديد يروح لـ /v2/.

أكواد status محافِظة

200 = نجاح، 400 = فشل validation، 401 = فشل auth (admin)، 404 = resource مش موجود، 429 = rate limited، 500 = خطأ سيرفر. مش بنستخدم 2xx-with-error-in-body.

CORS صارم

الـ endpoints العامة بتقبل POST من aetosseo.com + من مواقع plugin مرخّصة. مفيش wildcard origin.

نقاط الاتصال

Health

GET/healthzعام

فحص حياة الـ Worker. بيرجّع 200 + timestamp لما قاعدة البيانات شغالة.

Response

{ "ok": true, "time": 1716200000000 }

عام، Licensing (الـ WP plugin بيستدعيها)

POST/v1/license/checkعام · الـ plugin بيبعت الـ license key + domain

فحص حياة من الـ plugin. بيرجّع response موقّع Ed25519 من السيرفر فيه الـ tier + expiry + nonce. الـ plugin بيتحقق من التوقيع قبل ما يصدّق الرد.

Request body

{ "license_key": "AETOS-XXXX-XXXX-XXXX", "domain": "example.com", "plugin_version": "4.0.15" }

Response

{ "ok": true, "tier": "pro", "status": "active", "expires_at": 1747756800000, "nonce": "...", "signature": "..." }

GET/v1/dl?license=AETOS-...عام · license key مطلوب

تنزيل ZIP الإصدار الحالي. الـ Worker بيلاقي الـ manifest entry لإصدار الـ KV-stored ZIP. لو الـ User-Agent فيه placeholder "{LICENSE_KEY}" حرفي، الـ Worker بيستبدله بالـ key الحقيقي (legacy updater recovery).

Response

ملف ZIP مباشر + هيدر Content-Disposition

عام، Newsletter

POST/v1/newsletter/subscribeعام

اشتراك في النشرة الأسبوعية عن السيو وظهور الذكاء الاصطناعي. لو الـ Worker عنده RESEND_API_KEY، الرد بيكون "pending_confirmation" وبيبعت إيميل تأكيد. غير كده (legacy fallback) الرد بيكون "subscribed" فوراً.

Request body

{ "email": "you@example.com", "locale": "ar", "source_label": "blog" }

Response

{ "ok": true, "status": "pending_confirmation" }

GET/v1/newsletter/confirm?token=...عام · token من إيميل التأكيد

بيؤكّد اشتراك pending. بيحوّل لـ /ar/newsletter/confirmed/ عند النجاح. بيرجّع 404 HTML عند token غير صالح.

Response

302 Location: https://aetosseo.com/ar/newsletter/confirmed/

عام، Orders

POST/v1/orders/createعام

بينشئ order pending لـ tier (Pro أو Agency). بيرجّع order ID + رابط تعليمات الدفع. فيه honeypot على السيرفر للـ spam (silent reject لو الـ hidden "website" field مليان).

Request body

{ "tier": "pro", "domain": "example.com", "email": "you@example.com", "country": "SA", "method": "bank_sar" }

Response

{ "ok": true, "order_id": "AET-...", "amount_cents": 7900, "currency": "USD" }

شكل الـ Errors

كل رد فيه error بنفس الشكل. error هو كود ثابت تقدر تقراه آلياً (مش نص مترجم). detail قابل للقراءة، ممكن يتشال في production.

{ "ok": false, "error": "validation_failed", "issues": [ ... ] }

الـ Authentication

الـ endpoints العامة مش محتاجة token. License check و plugin ZIP download بيستخدموا الـ license key للتحقق، الـ Worker مش بيقبل license لو فشل round-trip Ed25519 verification أو لو الـ tuple HMAC غير صالح. شوف سياسة الأمان للـ threat model الكامل.

لقيت تضارب؟ كلمنا، بنحدّث الصفحة دي في كل patch.