اصطلاحات URL ونقاط النهاية المجانية

إذا رأيت 404 على طلب عادي، فالأرجح أن البادئة خاطئة أو أنك تبحث عن Swagger UI في مسار غير معياري. تثبّت هذه الصفحة جميع عناوين URL القانونية والأسماء البديلة.

بادئة المسار

جميع نقاط النهاية تقع تحت /v1/. لا توجد بادئات أخرى.

✅ https://api.astroway.info/v1/chart
✅ https://api.astroway.info/v1/health
❌ https://api.astroway.info/api/chart        - 404 (missing /v1/ prefix)
❌ https://api.astroway.info/api/v1/chart     - 404 (our internal path, not exposed)
❌ https://api.astroway.info/v1/v1/chart      - 308 redirect to /v1/chart (typical SDK base-URL bug fix)

إذا استخدمت /api/<endpoint> خطأً، نعيد 404 مع الحقل error.code = "WRONG_PREFIX" وتلميح، ويمكن لـ SDK الخاص بك معالجة ذلك واقتراح المسار الصحيح.

هذا ليس وكيلًا لـ LLM

AstroWay هو API للحسابات الفلكية، وليس proxy لـ LLM. إذا جئت بعادات OpenAI SDK وحاولت ببساطة تغيير base_url إلى عنواننا، فلن ينجح ذلك:

❌ POST /v1/chat/completions            - doesn't exist
❌ POST /v1/completions                 - doesn't exist
❌ GET  /v1/models                      - doesn't exist (deliberately)
❌ POST /v1/embeddings                  - doesn't exist

لا ننشر قائمة مزوّدي الذكاء الاصطناعي لسببين:

لا يفيد المُدمِج عمليًا. أنت تستدعي /v1/interpret/natal أو /v1/horoscope/daily، وخادمنا يختار بنفسه LLM من عدة مزوّدين مع fallback تلقائي. تغيير المزوّد لا يغيّر شكل الاستجابة، بل الـ latency فقط وأحيانًا صياغة النص.
حرية تشغيلية. السلسلة تتغير دون إنذار (استبعاد HuggingFace في 2026-05-18، إضافة NIM/ZAI). لو أعلنّا models[] محددة لصارت عقدًا فعليًا.

الذكاء الاصطناعي حاضر فقط كتفصيل تنفيذي في /v1/interpret/* (الولادية، السيناستري، العبور)، و/v1/horoscope/* (البرج اليومي والأسبوعي)، و/v1/dev-assistant (مساعد التوثيق)، و/v1/reports/* (سرديات PDF). بقية نقاط النهاية، وعددها 750+، هي Swiss Ephemeris حتمي بلا ذكاء اصطناعي.

مواصفة OpenAPI 3.1

العنوان القانوني هو /v1/openapi.json. ولتسهيل التكامل أضفنا أسماء بديلة:

الاسم البديل	إلى أين	لماذا يوجد
`/v1/swagger.json`	301 → `/v1/openapi.json`	عُرف Swagger 2.0 / openapi-generator
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	الافتراضي في springdoc
`/v1/v3/api-docs`	301 → `/v1/openapi.json`	Spring Boot 3
`/v1/v2/api-docs`	301 → `/v1/openapi.json`	Spring Boot 2
`/v1/swagger/v1/swagger.json`	301 → `/v1/openapi.json`	ASP.NET Core
`/v1/swagger`، `/v1/swagger-ui`، `/v1/swagger-ui.html`	302 → `/v1/docs`	مضيف Swagger UI

Swagger UI التفاعلي متاح على /v1/docs (ومنعكس أيضًا في توثيق المتصفح على /docs/api/).

نقاط النهاية النظامية المجانية

هذه المسارات لا تحتاج مفتاح API ولا تخصم أرصدة، ويمكن استدعاؤها من أي واجهة أمامية أو نظام مراقبة أو health-check.

المسار	ما يعيده
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}`، فحص liveness سريع
`GET /v1/health/deep`	فحص الوصول لكل قاعدة بيانات (لـ UptimeRobot / Pingdom)، و503 إذا تعذر الوصول إلى قاعدة واحدة على الأقل
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}`، فحص ذاتي مفصّل للـ SDK
`GET /v1/openapi.json`	مواصفة OpenAPI 3.1 كاملة مع أمثلة و`x-codeSamples`
`GET /v1/docs`	Swagger UI تفاعلي
`GET /v1/reference/*`	مراجع قانونية (الأبراج، الكواكب، البيوت، الجوانب)، مع rate limit بحسب IP، بلا مفتاح
`GET /v1/i18n/langs`، `GET /v1/i18n/dict/:lang`	قائمة اللغات وقواميس الواجهة، للويدجت

نقاط نهاية مجانية تتطلب التسجيل

نقاط نهاية الحساب متاحة فقط برمز JWT (يُصدَر عند تسجيل الدخول)، لكنها لا تخصم أرصدة من رصيد الخطة.

البادئة	ما هي
`/v1/auth/*`	التسجيل، تسجيل الدخول، refresh، إعادة تعيين كلمة المرور
`/v1/me`، `/v1/me/*`	الملف الشخصي، الإحصاءات، الاستدعاءات الأخيرة
`/v1/keys`، `/v1/keys/*`	إدارة مفاتيح API
`/v1/admin/*`	لوحة الإدارة (تتطلب `api_role = admin`)
`/v1/messages`	الملاحظات من الويدجت (مجهولة، مع rate limit)
`/v1/dev-assistant`، `/v1/dev-assistant/stream`	مساعد ذكاء اصطناعي للتوثيق (مجهول، بحد منفصل)
`/v1/widget-config`	أعلام ميزات وقت التشغيل للويدجت
`/v1/embed/*`	ويدجت iframe قابلة للتضمين (rate limit بحسب IP)
`/v1/oauth/*`	تسجيل الدخول عبر Google / GitHub
`/v1/books/*`	Birth Book، رمز JWT بنطاق منفصل (تصدره إضافة WordPress mu-plugin)

نقاط نهاية الحسابات المدفوعة

جميع الحسابات الفلكية تخصم أرصدة من خطتك. التكلفة الدقيقة لكل منها في صفحة تكلفة نقاط النهاية. باختصار:

Tier	الأرصدة	أمثلة
0	0	`/v1/reference/*`، مراجع عامة بلا مفتاح
½	5	`/v1/kabbalah/sephiroth`، `/v1/fixed-stars/catalog`، جداول ثابتة
1	10	`/v1/planets`، `/v1/sun-times`، `/v1/moon-phase`
2	20	`/v1/chart`، `/v1/harmonics`، `/v1/horary`
3	50	`/v1/synastry`، `/v1/progressions`، `/v1/acg`
4	100	`/v1/transit-calendar`، `/v1/group-synastry`
5	250	`/v1/rectification/trutine`، سرديات الذكاء الاصطناعي `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	تقارير PDF: `/v1/reports/natal`، `/v1/reports/synastry`

خصومات الكاش: X-Cache: HIT (كاش idempotency لمدة 5 دقائق) يعني 0 أرصدة. نقاط نهاية الذكاء الاصطناعي (/interpret/*) خصم 50% عند cache hit.

ترويسات الاستجابة تحتوي على X-Credits-Used وX-Credits-Remaining وX-Credits-Limit، فيمكن للـ SDK تتبع الرصيد تلقائيًا.

اللغة في الاستجابات

تُحدَّد اللغة عبر ?lang= أو الترويسة Accept-Language. هناك 21 لغة مدعومة.

الحقول ذات المجموعات المغلقة (الأبراج، الكواكب، أيام الأسبوع، أطوار القمر، قاموس Human Design، أسماء الأركانا الكبرى في التاروت) تُعاد مرتين: يبقى المعرّف الإنجليزي في مكانه كعقد ثابت، وبجانبه يأتي الكائن localized مع الترجمة:

{
  "phaseName": "Waxing Gibbous",
  "moonSign": "Capricorn",
  "localized": { "phaseName": "Zunehmender Mond", "moonSign": "Steinbock", "sunSign": "Löwe" }
}

قارن القيم الإنجليزية، واعرض localized. تؤخذ هذه الأسماء من جدول مصطلحات صريح في الكود، لا من الترجمة الآلية: لا يمكن ترجمة المصطلحات كلمة بكلمة، وإلا تحوّل طور القمر إلى كلمة مالية.

في Human Design، مفاتيح المراكز في localized.centers هي المعرّفات نفسها الموجودة في centers[].name، لذا تتم المطابقة بالمفتاح لا بالنص المترجم. وفي التاروت يفعل localized.cards الشيء نفسه، والمفتاح هو slug البطاقة.

الحقول ذات المجموعات المفتوحة لا تزال إنجليزية وموثّقة كذلك: themes[] في كوكب اليوم، والكلمات المفتاحية ومعاني بطاقات التاروت، وأسماء القنوات والبوابات في Human Design. أسماء الأركانا الصغرى تُجمع من صيغ مجمّدة للرتبة والنوع، لذا فإن المجموعة كاملة من 78 بطاقة مترجمة وnameLocalized لها true؛ ويبقى الحقل false فقط حيث لا يستطيع الجدول إعطاء اسم. ترجم المجموعات المفتوحة من جهتك أو انتظر قواميس منفصلة.

الاستجابة المختصرة: `fields` و`precision`

يدفع الوكيل مقابل كل token يقرؤه. POST /v1/chart يعيد نحو 32 كيلوبايت، بينما يحتاج النموذج عادة إلى عمودين منها، وكل خط طول يأتي بأربع عشرة خانة عشرية حيث لا أحد يبني بدقة أعلى من الدقيقة القوسية.

معاملا طلب يحلّان ذلك في الخطوة الأخيرة، لذا يعملان على جميع نقاط النهاية:

fields: قائمة مسارات مفصولة بفواصل، نسبةً إلى data. يُطبَّق المسار على كل عنصر في المصفوفة، فـ planets.name تعني اسم كل كوكب، لا مفتاح المصفوفة.
precision: عدد صحيح من 0 إلى 15، يقرّب جميع الأعداد غير الصحيحة في الاستجابة. لا يمس الأعداد الصحيحة: المعرّف ليس قياسًا.

curl -X POST "https://api.astroway.info/v1/chart?fields=planets.name,planets.longitude&precision=2" \
  -H "X-Api-Key: aw_live_..." -H "Content-Type: application/json" \
  -d '{"date":"1990-05-15","time":"14:30:00","timezone":"Europe/Kyiv","latitude":50.45,"longitude":30.52}'

هذا الزوج من المعاملات على الخريطة الولادية يعطي 511 بايت بدل 32 410، أي استجابة أصغر بستين مرة.

المسار الذي لم يجد شيئًا لا يختفي بصمت. يأتي في الحقل _fields_unmatched بجانب الاستجابة: بعض الحقول اختيارية فعلًا وغائبة في استجابة معينة، لذا فهذا ليس خطأ. أما القائمة التي لم يطابق فيها أي مسار فهي خطأ مطبعي، وتعيد 400 FIELDS_UNKNOWN مع قائمة. الكائن الفارغ بدل الخريطة كان سيكون إجابة خاطئة واثقة.

يذهب المعاملان في الـ query لا في الترويسة، وهذا مقصود: مفتاح كاش الاستجابات يُبنى من الطريقة والمسار والجسم والـ query المرتّب والخطة. الوضع في ترويسة كان سيكرر حادثة 2026-08-22، حين لم يكن Accept-Language جزءًا من المفتاح فأُعطيت الاستجابة الألمانية للطالب التالي على أنها أوكرانية.

التشكيل يخص data فقط. الغلاف و_footer و_warning تبقى كاملة.

الأمر نفسه يعمل عبر MCP. كل أداة على mcp.astroway.info تقبل fields وprecision بجانب معاملاتها وتمررهما إلى الـ API بالـ query نفسه. كانت الخريطة الولادية عبر MCP تزن 91 737 بايت، لأن البيانات كانت تأتي مرتين: كتلة نصية بمسافات بادئة وحقلًا مُهيكلًا. ومع المسارات الثلاثة نفسها وprecision: 2 تصبح 1 182 بايت.

استدعاء الخريطة الولادية	البايتات
MCP، كما كان قبل 21.09.2026	91 737
MCP، بلا مسافات بادئة في الكتلة النصية	72 484
MCP، `precision: 2`	61 356
MCP، ثلاثة مسارات في `fields` مع `precision: 2`	1 182
REST، ثلاثة مسارات في `fields` مع `precision=2`	559

وقت الميلاد المجهول

جزء كبير من المستخدمين النهائيين لا يعرف وقت ميلاده الدقيق. إذا وضعت ظهرًا افتراضيًا وحسبت الخريطة كالمعتاد، فستظهر في الاستجابة طالع ورؤوس بيوت تبدو موثوقة، لكنها تخطئ بنحو برج لكل ساعتين من الخطأ.

لذلك يمكنك بدل time تمرير timeUnknown: true:

curl -X POST https://api.astroway.info/v1/chart \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-03-15","timeUnknown":true,"timezoneOffset":2,"latitude":50.45,"longitude":30.52}'

ما يعيده الـ API في هذا الوضع:

الحقل	القيمة
`planets`	محسوبة على الظهر المحلي
`aspects`	محسوبة، لكن جوانب القمر غير موثوقة (انظر أدناه)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	كتلة مع شرح: ما الذي أُسقط تحديدًا وأين يمكن أن يكون القمر

تحتوي الكتلة timeUnknown.moon على خط طول القمر في بداية اليوم ونهايته، والقوس الذي قطعه خلال اليوم (11.8-15.4°)، وقائمة الأبراج التي كان فيها، والعَلَم changesSign. قد يغيّر القمر برجه خلال اليوم، لذا يجدر عرض هذا النطاق للمستخدم لا إخفاؤه خلف رقم واحد.

يقبل العَلَم /v1/chart و/v1/synastry (في السيناستري يمكن ضبطه لأي من الشريكين على حدة). بقية نقاط النهاية تعتمد على البيوت أو الزوايا وتجيب بـ 400 TIME_UNKNOWN_UNSUPPORTED: الخطأ الصريح أفضل من عَلَم متجاهَل بصمت وطالع مختلَق في الاستجابة.

إصدارات الـ API

الإصدار الرئيسي في URL (/v1/). التغييرات الكاسرة (breaking) تأتي فقط مع /v2/، لا في المكان نفسه. التفاصيل: الإصدارات.

GET /v1/version يعيد النشر الحالي:

curl https://api.astroway.info/v1/version
# {
#   "version": "2.71.0",
#   "build_commit": "abc1234",
#   "started_at": "2026-05-27T10:42:00Z",
#   "uptime_seconds": 12345,
#   "docs_url": "https://api.astroway.info/docs/api/"
# }

يمكن للـ SDK استدعاء هذا عند البدء لتتبع “لماذا تغيّر السلوك فجأة”، فالحقل build_commit يحدد النشر بدقة.

الاستدعاءات الخاطئة التي نراها أكثر من غيرها

من تحليل سجلات الإنتاج على مدى 90 يومًا، هذه 5 أخطاء نموذجية للمُدمِجين:

/api/<endpoint> بدل /v1/<endpoint>: عادة من wp-json في WordPress. الآن نعيد JSON 404 مع تلميح.
/v1/v1/<endpoint>: الـ SDK مُعدّ بـ baseUrl = .../v1 ويضيف /v1/X فوقه. الآن 308 redirect.
/swagger.json بدل /v1/openapi.json: الاستكشاف التلقائي في Postman/Insomnia. الآن 301 redirect.
/v1/me، /v1/auth/keys/me بلا Authorization: Bearer <jwt> → 401. تحقق من أن الرمز يُمرَّر في الترويسة.
/v1/embed/natal بمفتاح API بدل رمز embed → 401. نقاط نهاية embed تقبل رمز embed عامًا من لوحة التحكم، لا مفتاح API.