المستخدمون والمزامنة

كل ما يحتاجه تطبيق مستهلك بتسجيل دخول: إنشاء الحساب/تسجيل الدخول، إعدادات الملف الشخصي والخصوصية، إدارة الأجهزة/الجلسات، تصدير البيانات وحذف الحساب (GDPR)، الأماكن المحفوظة والقوائم القابلة للمشاركة، سجل البحث/الزيارات، ومشاركة الموقع الحي مع وقت الوصول المتوقع. هذه هي الواجهة نفسها التي يعمل عليها تطبيق خرائط Navvo.

الحسابات والملف الشخصي

POST /auth/register

إنشاء حساب مستخدم. مجهول الهوية بطبيعته.

curl -s -X POST "https://navvo.io/api/v1/auth/register" \
  -H "content-type: application/json" \
  -d '{ "email": "lina@example.com", "name": "Lina", "password": "superStrongPass123!" }'

{
  "user": { "id": "…", "email": "lina@example.com", "name": "Lina", "roles": ["user"] },
  "sessionId": "3f6f2c1e-…",
  "accessToken": "eyJhbGciOi…"
}

accessToken هو Bearer JWT طويل العمر مرتبط بـsessionId — خزّنه بأمان وأرسله مع كل استدعاء خاص بالمستخدم. إبطال الجلسة (تسجيل الخروج، إدارة الأجهزة) يُميت الرمز من جهة الخادم.

POST /auth/login

الجسم نفسه (email، password) والمغلّف نفسه في الاستجابة كما في التسجيل. الحساب المعطَّل أو بيانات الاعتماد الخاطئة تعيد 400. وكما في التسجيل، لا يُطلب اختبار تحقق أبداً عند الاستدعاء بمفتاح API — حقل turnstileToken موجود فقط لنموذج المتصفح الخاص بموقع Navvo.

GET /auth/me

المستخدم المسجَّل دخوله + الجلسة الحالية.

curl -s "https://navvo.io/api/v1/auth/me" -H "authorization: Bearer $NAVVO_USER_TOKEN"

{
  "user": { "id": "…", "email": "lina@example.com", "name": "Lina", "roles": ["user"],
            "profile": { "avatar": { "type": "emoji", "value": "🌟" }, "privacy": { "saveHistory": true } } },
  "session": { "id": "…", "sessionId": "…", "lastSeenAt": "…", "expiresAt": "…", "revokedAt": null }
}

PATCH /auth/me

تحديث الملف الشخصي القابل للتعديل. كل الحقول اختيارية؛ لا يتغيّر إلا ما تُرسله.

curl -s -X PATCH "https://navvo.io/api/v1/auth/me" \
  -H "authorization: Bearer $NAVVO_USER_TOKEN" -H "content-type: application/json" \
  -d '{ "privacy": { "saveHistory": false, "personalization": true } }'

→ { "ok": true, "user": { … } }. يقرأ العميل الإعدادات مجدداً من GET /auth/me → user.profile.privacy. احترم saveHistory: false بعدم استدعاء POST /me/history.

POST /auth/logout

تسجيل خروج الجلسة الحالية من جهة الخادم (يُبطَل معرّف جلسة الرمز، فيتوقف الرمز عن العمل في كل مكان). → { "ok": true }

GET /auth/sessions · DELETE /auth/sessions

إدارة الأجهزة — اعرض جلسات المستخدم وأبطِلها.

{
  "items": [
    { "sessionId": "…", "current": true, "ipAddress": "94.…", "userAgent": "Mozilla/5.0 …",
      "lastSeenAt": "…", "createdAt": "…", "expiresAt": "…", "revokedAt": null }
  ]
}

• DELETE /auth/sessions/{sessionId} — إبطال جلسة واحدة → { "ok": true, "revoked": 1 }
• DELETE /auth/sessions?all=1 — «تسجيل الخروج من كل مكان آخر»: يُبطل كل الجلسات عدا الحالية → { "ok": true, "revoked": n }

GET /auth/me/export

تصدير البيانات بأسلوب GDPR — كل ما تخزّنه Navvo تحت الحساب، في مستند JSON واحد: { exportedAt, account, savedLocations, mapHistory, liveShares, signDisregards, sessions }.

DELETE /auth/me

حذف الحساب ذاتياً (متطلَّب متاجر التطبيقات). يمسح بيانات المستخدم تباعاً — الجلسات، الأماكن المحفوظة والسجل، مشاركات الموقع الحي — ثم يزيل الحساب.

→ { "deleted": true }

تسجيل الدخول الاجتماعي (OAuth)

المزوّدون يُهيّئهم مشغّل المنصة — اعرض الأزرار دائماً من القائمة الحية:

• GET /auth/providers (عام) → { "providers": [ { "id": "google", "label": "Google", … } ], "turnstile": { "enabled": true, "siteKey": "…" } }
• GET /auth/oauth/{provider}/start?next=/map — يعيد توجيه المتصفح (302) إلى صفحة موافقة المزوّد.
• GET /auth/oauth/{provider}/callback — يعود المزوّد إلى هنا؛ عند النجاح يهبط المتصفح على /map#nvauth=ok&token=<accessToken>. إذا كان البريد يعود لحساب بكلمة مرور، يكون الجزء nvauth=link ويؤكد العميل الربط عبر POST /auth/oauth/link بجسم { linkToken, password? }.

POST /auth/firebase

تبادل تسجيل الدخول عبر Firebase — المسار الموصى به للتطبيقات التي تستخدم Firebase Authentication (بريد/كلمة مرور، Google، Apple، Microsoft، Facebook، GitHub…). سجِّل دخول المستخدم عبر Firebase SDK ثم أرسل رمز المعرّف (ID token)؛ تتحقق Navvo منه مقابل شهادات Google العامة (المُصدِر والجمهور مثبّتان على مشروع Navvo)، وتجد الحساب أو تنشئه عبر البريد الموثَّق، وتعيد مغلّف المصادقة القياسي (user، sessionId، accessToken) — فيحصل المستخدم فوراً على وصول كامل لخدمات الأعضاء (الملاحة، أطلس، الأماكن المحفوظة…).

نموذج الوصول: الزائر مقابل المسجَّل

الخريطة الأساسية (البلاطات، الأنماط، التصفح، البحث، تفاصيل الأماكن، قراءات الترميز الجغرافي) مفتوحة. خدمات الأعضاء تتطلب رمز Bearer لمستخدم مسجَّل — أو مفتاح API الخاص بك كمطوّر: التوجيه/الملاحة (POST /routing/*، POST /traffic/route)، وكيل أطلس، الأماكن المحفوظة والقوائم، السجل، المشاركة الحية، التبليغ، ورموز الإشعارات. الاستدعاءات المجهولة لهذه تعيد 401.

رموز الإشعارات (Push)

سجِّل رمز FCM الخاص بالجهاز ليتمكن خادمك (أو Navvo عندما يفعّل المشغّل الإرسال) من الوصول للمستخدم:

• POST /me/push-tokens — الجسم { "token": "…", "platform": "web" | "android" | "ios" } (مصادقة Bearer). إعادة إرسال رمز موجود تعيد ربطه بالمستخدم الحالي.
• DELETE /me/push-tokens/{token} — لإلغاء التسجيل عند الخروج.

الأماكن المحفوظة

مفضّلات المستخدم باسم مخصص وأيقونة وملاحظة وقائمة ووسوم — تتزامن عبر الأجهزة.

GET · POST /me/saved-places

GET يعيد أحدث 100 من المفضلة. POST يحفظ نقطة:

• PATCH /me/saved-places/{id} — تحديث customName، note، icon، listName، tags.
• DELETE /me/saved-places/{id} → { "deleted": true, "id" }.

GET · POST /me/locations

مراسٍ مثبَّتة مثل المنزل والعمل: { "type": "home" | "work" | "favorite" | "custom", "label", "lat", "lng" }. يعرضها GET (الهندسة المخزّنة WKT بالصيغة POINT(<lng> <lat>) — خط الطول أولاً).

القوائم — GET · POST /me/lists

مجموعات مُسمّاة من أماكن الفهرس، قابلة للمشاركة اختيارياً.

• POST /me/lists بجسم { "name": "مقاهي نهاية الأسبوع", "public": false } — كل قائمة تحصل على shareSlug فريد؛ اضبط "public": true كي يعمل رابط مشاركتها.
• GET /me/lists — قوائم المستخدم مع أماكنها.
• POST /me/lists/{id}/places بجسم { "placeId": "…", "note"? } — إضافة مكان من الفهرس إلى قائمة.

GET /shared-lists/{shareSlug} — عام

عارض القوائم المشتركة — دون مصادقة؛ المعرّف هو السر، ولا تُحلّ إلا القوائم التي وسمها المالك بأنها public. الاستجابة منقّاة (لا معرّفات مستخدمين):

curl -s "https://navvo.io/api/v1/shared-lists/weekend-cafes-a1b2c3"

{
  "found": true, "name": "مقاهي نهاية الأسبوع", "updatedAt": "…",
  "places": [
    { "slug": "jordan-beans-cafe", "nameEn": "Jordan Beans Cafe", "nameAr": "…",
      "categories": ["cafe"], "rating": 4.6, "center": "POINT(35.913 31.953)", "note": null }
  ]
}

المعرّف المجهول/الخاص يعيد { "found": false }.

GET · POST · DELETE /me/history

سجل بحث/زيارات المستخدم (الأحدث أولاً، ويُعاد 100 كحد أقصى).

• GET /me/history → { "items": [ … ], "total" }
• POST /me/history بجسم { "name", "lat", "lng", "detail"?, "placeId"? } — تسجيل مُدخَل
• DELETE /me/history — مسح الكل → { "deleted": true }
• DELETE /me/history/{id} — إزالة مُدخَل واحد

الرحلات اليومية (وقت المغادرة + التنبيهات)

رحلات محفوظة (منزل→عمل ونحوها)، لكل منها أيام تكرار، وعمر دائم أو مؤقّت، وأي عدد من أوقات التنبيه قبل المغادرة. يقيّم الخادم كل رحلة مُفعّلة كل دقيقة وفق حركة المرور الحية، وعند اقتراب وقت المغادرة يرسل إشعاراً (عبر رموز الإشعارات المسجّلة للمستخدم) — مثل «غادر خلال ~15 دقيقة إلى العمل».

كل المسارات تتطلب مصادقة Bearer ومقيّدة بالمستخدم المسجّل.

• GET /me/commutes → { "commutes": Commute[] }
• POST /me/commutes بجسم Commute (بدون id) → { "commute" } (حد أقصى 20 لكل مستخدم)
• PUT /me/commutes/{id} (جسم Commute جزئي) → { "commute" }
• DELETE /me/commutes/{id} → { "ok": true }

{
  "id": "…",
  "name": "العمل",
  "from": { "lat": 31.95, "lng": 35.91, "label": "المنزل" },
  "to":   { "lat": 31.99, "lng": 35.95, "label": "المكتب" },
  "arriveBy": "09:00",
  "days": [0,1,2,3,4],
  "permanent": true,
  "expiresAt": null,
  "notifications": [{ "minutesBefore": 30 }, { "minutesBefore": 15 }],
  "enabled": true
}

مشاركة الموقع الحي

شارك موقعاً حياً تحت مفتاح متجدد يستحيل تخمينه. المشاركة تنتهي تلقائياً بعد ساعتين من آخر إشارة (ping)؛ وكل إشارة تمدّدها.

POST /me/live-share

بدء مشاركة: { "label"? } → { "shareKey": "…", "active": true, "expiresAt": "…" }. رابط العارض الذي تشاركه هو https://navvo.io/map?live=<shareKey>.

GET /me/live-share

مشاركات المستخدم النشطة: { "items": [ { "shareKey", "label", "lastPingAt", "expiresAt" } ] }.

POST /me/live-share/{key}/ping

ادفع الموقع الحالي (استدعِه كل بضع ثوانٍ أثناء المشاركة):

→ { "active": true } (و{ "active": false } بعد الإيقاف/الانتهاء — توقف عندها عن الإرسال).

POST /me/live-share/{key}/stop

إنهاء المشاركة → { "stopped": true }.

GET /live/{key} — عام

قراءة العارض — دون مصادقة، استعلم عنها بضع مرات في الدقيقة:

{
  "active": true, "lat": 31.9539, "lng": 35.9106, "heading": 270, "accuracy": 8,
  "label": "Lina", "updatedAt": "…",
  "destination": { "name": "المطار", "lat": 31.7226, "lng": 35.9932 },
  "etaSeconds": 1240, "arrivalTime": "2026-07-09T11:42:00.000Z"
}

تظهر destination وetaSeconds وarrivalTime فقط أثناء ملاحة المُشارِك (أي عندما يرسل حقول Share-ETA مع الإشارة) — وإلا فهي null. المفاتيح المنتهية/المجهولة تعيد { "active": false }؛ والمشاركة التي بدأت ولم تُرسل إشارة بعد تعيد { "active": true, "pending": true }.

روابط عميقة إلى خريطة Navvo

سلّم المستخدم من تطبيقك إلى تجربة خريطة Navvo الكاملة بروابط بسيطة: