# تنسيقات الحقول

النموذج اللي يخمن اسم الحقل يحصل إما على `400` أو، الأسوأ، رد مؤكد ببطاقة مختلفة. أدناه العقد الدقيق.

## جسم طلب الخريطة

| حقل | النوع والتنسيق | إلزامي |
|---|---|---|
| `date` | `YYYY-MM-DD`، ويجب أن يكون تاريخًا حقيقيًا في التقويم | نعم |
| `time` | `HH:mm:ss` | نعم، أو `timeUnknown: true` |
| `timezoneOffset` | عدد، ساعات من UTC، مثال `5.75` | لا، الافتراضي `0` (UTC) |
| `timezone` | اسم منطقة IANA، مثال `Europe/Kyiv`، أو `auto` | لا، وعند الإرسال، يستبدل `timezoneOffset` |
| `latitude` | درجات عشرية، الشمال موجب | نعم |
| `longitude` | درجات عشرية، الشرق موجب | نعم |
| `houseSystem` | حرف واحد، الافتراضي `P` | لا |
| `city` | نص، فقط للعلامة | لا |
| `zodiacType` | `tropical` أو `sidereal` | لا |

<Aside type="caution">
`city` لا تقوم بأي جيوكود. هذا الحقل للعلامة في واجهتك، وهو **أبدًا** لا يستبدل الإحداثيات.
</Aside>

## الاختصارات القصيرة تُرفض

`lat`، `lon`، `lng`، `long`، `tz`، `tzOffset`، `utcOffset`، `gmtOffset`، `timeZone`، `time_zone` يرجعون `400 INVALID_FIELD` مع اسم الحقل الصحيح:

```json
{ "error": { "code": "INVALID_FIELD",
  "message": "Unsupported field \"tz\". Rename it to \"timezoneOffset\" (numeric hours from UTC, e.g. 5.75; a zone name goes in timezone)." } }
```

الحالة وفواصل القيمة غير مسموحة: `TZ_Offset` و `tzoffset` يُرفضان بنفس الطريقة. يتم الإبلاغ عن **جميع** الحقول المكتشفة مرة واحدة، وليس الأول فقط، حتى يمكنك تصحيحها دفعة واحدة.

السبب صارم: قبل هذا الفحص، الحقل اللي ما قرأه الـ API كان صامتًا يعطي إزاحة `0`، وكانت الاستجابة بطاقة مؤكدة للـ UTC. إزاحة ثلاث ساعات تعادل تقريبًا 45° من الصعود، أي علامة أخرى صاعدة، دون أي تحذير.

## `timezone`: اسم المنطقة بدلًا من الإزاحة

الإزاحة يجب أن تكون تلك التي كانت على الساعات **في ذلك التاريخ** بالضبط، ومن السهل إدخالها يدويًا بشكل خاطئ: كييف في مايو 1990 كانت تتبع التوقيت الصيفي لموسكو، UTC+4، وليس +3. أرسل `timezone`، وسيأخذ الخادم الإزاحة من قاعدة بيانات المناطق الزمنية، بما في ذلك التوقيت الصيفي.

```json
{ "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv",
  "latitude": 50.45, "longitude": 30.52 }
```

- `auto` يحدد المنطقة بناءً على `latitude` و `longitude`. قرب الحدود يكون الاسم أدق.
- إذا جاء `timezone` و `timezoneOffset` معًا، يُطبق `timezone`. `input.timezoneOffset` في الاستجابة يُظهر الإزاحة التي تم استخدامها.
- الوقت الذي تكرر (عند إرجاع الساعات للخلف) يُؤخذ من المرة الأولى. الوقت الذي لم يحدث (عند تقديم الساعات للأمام) يحصل على الإزاحة التي كانت سارية قبل التغيير.
- بدون `time` (فقط التاريخ أو `timeUnknown: true`) تُقرأ المنطقة عند الظهر المحلي.
- يُرفض بـ `400 INVALID_FIELD`: قيمة فارغة، اختصارات مثل `EST` أو `PST`، إزاحة مكتوبة نصيًا مثل `+03:00`، أسماء غير موجودة في القاعدة، و `auto` بدون إحداثيات. يُقبل `UTC` و `GMT`.
- كل كائن يُعالج بشكل منفصل، لذا يمكن أن يكون `chart1` و `chart2` في مناطق مختلفة.

<Aside type="note">
قبل عام 1970 قاعدة بيانات المناطق الزمنية ليست موثوقة لكل مكان: أمستردام في يونيو 1930 تُرجع +1، رغم أن الساعات كانت تُظهر +0:20. إذا كان الوقت المحلي لتلك الولادة معروفًا، أرسل `timezoneOffset`.
</Aside>

## `houseSystem`: حرف، ليس اسم

يُقبل بالضبط هذه الـ 25 كودًا من Swiss Ephemeris:

`P` `K` `R` `C` `E` `W` `B` `M` `O` `A` `T` `V` `D` `F` `G` `H` `I` `i` `L` `N` `Q` `S` `U` `X` `Y`

الحالة مهمة: `I` هو Sunshine حسب ماكرانسكي، `i` حسب ترايندلم. اسم النظام (`"Placidus"`، `"Koch"`) يُعيد `400`. سابقًا كان يعمل عشوائيًا لأن المحرك يقرأ من السلسلة الحرف الأول فقط، ومن نفس السبب `"Zodiac"` كان صامتًا يعطي Placidus.

## وقت الولادة غير معروف

بدلاً من الظهر المفترض، أرسل `timeUnknown: true` ولا ترسل `time`. عندها تكون `houses`، `houseAspects`، `chartSect` و `siderealTime` قيمتها `null`، وليس مفترضة. التفاصيل: [Conventions API](/api-conventions/#невідомий-час-народження).

## المفاتيح غير المعروفة لا تُرفض

الجسم يقبل الحقول الزائدة بصمت: المفتاح غير المعروف يُتجاهل ببساطة. لذلك خطأ في اسم حقل غير موجود في قائمة الرفض أعلاه لن يظهر. راجع المواصفات: [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).

## التالي

- [الأخطاء الشائعة](/agent-setup/mistakes/)
- [العقبات](/agent-setup/gotchas/)