الأجهزة ومفاتيح الإدخال

كيف تكتب ساعة العضو أو هاتفه أو مجمّع أجهزة الخطوات ومعدل ضربات القلب والتمارين في Kinora باستخدام مفتاح شخصي.

لحزمة الحزمة الكاملة

كيف تدخل البيانات

لا يسحب Kinora البيانات من Garmin أو Fitbit أو Apple Health أو أي خدمة أخرى. تصل البيانات لأن شيئًا ما يرسلها: المفتاح الخاص بالعضو يتيح لجهاز أو تطبيق أو مجمّع أجهزة كتابة أرقام حركة ذلك العضو وتمارينه عبر باب واحد، /api/ingest.

تربط المجمّعات مثل Terra و Rook و Spike حساب ساعة العضو مرة واحدة، ثم ترسل بياناتها إلى عنوان تعطيه لها. يحوّل مهايئ صغير خاص بك حمولتها إلى الشكل أدناه ويمرّرها بمفتاح ذلك العضو.
المهايئ ليس ضمن القالب: فهو الجزء الوحيد الذي يعتمد على المزوّد الذي تختاره.

في لوحة التحكم

في الإعدادات، تسرد بطاقة «الأجهزة المتصلة» كتالوج الأجهزة، كل جهاز متصل أو غير متصل، مع آخر مزامنة ومستوى البطارية. يأتي الزرع بساعة رياضية بنظام GPS، و Kinora Band Pro، وميزان جسم ذكي.
ينشئ ربط مصدر بيانات مفتاحًا: يسمّيه العضو، ويُعرض المفتاح كاملًا مرة واحدة لنسخه. بعد ذلك لا تُعرض إلا أحرفه الـ 12 الأولى.
يمكن إلغاء المفتاح في أي وقت، فيتوقف عن العمل فورًا.

المفاتيح

يخص المفتاح حسابًا واحدًا بالضبط. يكتب أرقام حركة ذلك الحساب وجلساته ولا شيء غير ذلك.
يحتاج إنشاء مفتاح إلى fitness.edit، ولا يملكها إلا دور العضو: رمز الطاقم يُرجع 403.
المفتاح هو kin_ يليه 64 حرفًا ست عشريًا. لا يحتفظ الخادم إلا ببصمة SHA-256 الخاصة به وأحرفه الـ 12 الأولى، لذا فإن تسرّب قاعدة البيانات لا يمنح أحدًا مفتاحًا صالحًا.

الطريقة	المسار	الصلاحية	وظيفته
`GET`	`/api/fitness/devices/keys`	`fitness.view`	مفاتيح الحساب غير الملغاة، الأحدث أولًا
`POST`	`/api/fitness/devices/keys`	`fitness.edit`	ينشئ مفتاحًا (`{ name }`، من 1 إلى 80 حرفًا) ويجيب بالمفتاح كاملًا، قابلًا للقراءة هذه المرة فقط
`DELETE`	`/api/fitness/devices/keys/:id`	`fitness.edit`	يلغي مفتاحًا؛ و`404 api_key_not_found` لمفتاح لا يخص الحساب
`GET`	`/api/fitness/devices`	`fitness.view`	كتالوج الأجهزة مع اتصال الحساب بكل منها
`POST`	`/api/fitness/devices/:key/toggle`	`fitness.edit`	يربط جهازًا أو يفصله
`POST`	`/api/fitness/devices/:key/sync`	`fitness.edit`	دائمًا `400 device_sync_unavailable`: الخادم لا يسحب شيئًا

إرسال البيانات

تقرأ كل مسارات /api/ingest المفتاح من الترويسة X-Api-Key ولا شيء غيرها؛ ولا يُقبل رمز bearer هناك. المفتاح المفقود يُرجع 401 api_key_missing، والمفتاح غير المعروف أو الملغى يُرجع 401 api_key_invalid.

01
تحقق من المفتاح
الطرفية
```
curl http://localhost:8000/api/ingest/whoami -H "X-Api-Key: kin_…"
```
النتيجة المتوقعة: يجيب بمعرّف الحساب واسم المفتاح.
02
أرسل أرقام يوم
POST /api/ingest/daily-metrics مع قائمة من الأيام. لا يلزم إلا date؛ والرقم الذي تتركه يحتفظ بقيمته، لذا يستطيع حزام معدل ضربات القلب وعدّاد الخطوات الإبلاغ عن اليوم نفسه من دون أن يمحو أحدهما الآخر. وإرسال تاريخ مرة أخرى يصحّح ذلك اليوم.
متن الطلب
```
{
  "days": [
    { "date": "2026-08-23", "steps": 15342, "distanceKm": 11.4, "activeKcal": 941, "totalKcal": 2680,
      "floorsClimbed": 14, "exerciseMinutes": 78, "activeMinutes": 96, "standHours": 11,
      "restingHr": 58, "avgHr": 74 }
  ]
}
```
النتيجة المتوقعة: { "written": 1 }. القيمة خارج النطاق (رقم سالب، أو standHours أكثر من 24، أو معدل ضربات قلب خارج 20 إلى 250) تُرجع 400.
03
أرسل التمارين
POST /api/ingest/sessions مع قائمة من الجلسات. يجب أن يحدد workoutSlug جلسة في الكتالوج (وإلا 404 workout_not_found). تُعرَف الجلسة بحسابها وجلستها ووقت بدئها، لذا فإن إرسالها مرة أخرى لا يحتسبها مرتين. وكل جلسة مرسلة تُعلَّم بأنها منجزة.
متن الطلب
```
{
  "sessions": [
    { "workoutSlug": "conditioning", "startedAt": "2026-08-23T07:12:00.000Z",
      "finishedAt": "2026-08-23T07:49:00.000Z", "minutes": 37, "kcal": 412 }
  ]
}
```

كل يوم يُكتب يسجّل اسم المفتاح بوصفه مصدره، ما يميّز اليوم المزامَن عن اليوم المُدخل يدويًا. وكل طلب مقبول يسجّل آخر استخدام للمفتاح.

كيف تدخل البيانات

في لوحة التحكم

المفاتيح

إرسال البيانات

تحقق من المفتاح

أرسل أرقام يوم

أرسل التمارين

تفضيلات ملفات تعريف الارتباط