المصادقة

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

إرسال مفتاحك

مرّر المفتاح في كل طلب باستخدام ترويسة x-api-key:

curl "https://navvo.io/api/v1/search?q=pharmacy" \
  -H "x-api-key: nvvo_YOUR_KEY"

بالنسبة لعناوين URL التي يجلبها المتصفّح مباشرةً ولا يستطيع إضافة ترويسات إليها — وأهمّها بلاطات الخرائط والأنماط في Navvo Maps — مرّر المفتاح كمعامل استعلام بدلًا من ذلك. يُقبَل كلٌّ من api_key وapiKey:

https://navvo.io/api/v1/tiles/style?style=standard&api_key=nvvo_YOUR_KEY

صيغة المفتاح

مفاتيح Navvo مسبوقة ببادئة وسهلة التمييز:

nvvo_<48 hex characters>

تُخزَّن تجزئة المفتاح فقط على الخادم، إلى جانب الأحرف الأربعة الأخيرة (للعرض). يُعاد النص الصريح مرّة واحدة فقط، عند إنشاء المفتاح.

النطاقات

يحمل كل مفتاح مجموعة من النطاقات. ينجح الطلب إلى نقطة نهاية ذات نطاق فقط إذا منح المفتاح ذلك النطاق. توجد أحد عشر نطاقاً:

تُنشأ المفاتيح الجديدة مع تفعيل ثمانية من الأحد عشر نطاقاً. والنطاقات geo وinsights وoptimize معطّلة افتراضيًا — اطلبها صراحةً إذا كنت بحاجة إلى الأسيجة الجغرافية أو التحليلات أو التحسين.

القائمة الحيّة المرجعية متاحة أيضاً للمطوّرين المُسجَّلين عبر GET /developer/scopes (كل نطاق بتسمية ووصف).

الحصول على مفتاح

أسرع طريقة للحصول على مفتاح هي بوابة المطوّرين على navvo.io/developer — وحدة تحكّم بالنقر لإدارة المؤسسات والمشاريع والمفاتيح ومراقبة الاستخدام الحيّ وتجربة الطلبات في بيئة اختبار. كل ما يلي متاح أيضًا كواجهة REST إذا فضّلت أتمتته.

تُنشأ مفاتيح API عبر نقاط نهاية بوابة المطوّرين، وهي محميّة برمز جلسة المستخدم (رمز JWT، وليس مفتاح API). التدفّق هو: حساب ← مؤسسة ← مشروع ← مفتاح. كل مؤسسة ومشروع ومفتاح مرتبط بالمستخدم الذي أنشأه — فأنت لا ترى وتدير إلا ما يخصّك.

1. أنشئ حسابًا / سجّل الدخول

curl -X POST "https://navvo.io/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "name": "Your Name",
    "password": "a-strong-password-min-10-chars"
  }'

curl -X POST "https://navvo.io/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "a-strong-password-min-10-chars"
  }'

يعيد كلاهما accessToken (رمز JWT من نوع Bearer) إضافةً إلى المستخدم والجلسة الخاصّين بك:

{
  "user": { "id": "uuid", "email": "you@example.com", "name": "Your Name", "roles": ["user"] },
  "sessionId": "uuid",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

أرسل هذا الرمز بصيغة Authorization: Bearer <accessToken> في جميع طلبات /developer/* و/auth/me.

2. أنشئ مؤسسة

curl -X POST "https://navvo.io/api/v1/developer/organizations" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Logistics", "slug": "acme-logistics" }'

3. أنشئ مشروعًا

curl -X POST "https://navvo.io/api/v1/developer/organizations/<orgId>/projects" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Driver App" }'

4. أنشئ مفتاح API

curl -X POST "https://navvo.io/api/v1/developer/api-keys" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "<projectId>",
    "label": "Driver App – production",
    "plan": "startup",
    "scopes": { "geo": true }
  }'

تحتوي الاستجابة على مفتاحك في الحقل key — هذه هي المرة الوحيدة التي يُعرَض فيها:

{
  "key": "nvvo_3f9c2a1e8b7d6c5f4a3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b",
  "id": "uuid",
  "label": "Driver App – production",
  "lastFour": "9c8b",
  "scopes": {
    "search": true, "geocode": true, "places": true, "routing": true,
    "traffic": true, "telemetry": true, "tiles": true, "imagery": true, "geo": true
  },
  "plan": "startup",
  "quotaPerMinute": 180,
  "quotaPerDay": 2500,
  "active": true
}

جسم الطلب — POST /developer/api-keys

إدارة المفاتيح

تتطلّب كل هذه النقاط رمز الجلسة Authorization: Bearer <accessToken> وهي مرتبطة بحسابك.

التعطيل مقابل الحذف

لإيقاف مفتاح مؤقتًا (وإعادة تشغيله)، اضبط active:

curl -X PATCH "https://navvo.io/api/v1/developer/api-keys/<keyId>" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

يُرفَض المفتاح غير المفعّل بالرمز 403 Forbidden حتى تعيد تفعيله. أما DELETE فيزيل المفتاح نهائيًا.

تدوير مفتاح

إذا تسرّب مفتاح أو فُقِد، فقم بتدويره — يولّد ذلك سرًّا جديدًا تمامًا ويُبطِل السابق فورًا، مع الإبقاء على نفس معرّف المفتاح ونطاقاته وحصصه:

curl -X POST "https://navvo.io/api/v1/developer/api-keys/<keyId>/rotate" \
  -H "Authorization: Bearer <accessToken>"

تتضمّن الاستجابة key الجديد بنصّه الصريح — ومرّةً أخرى، يُعرَض مرّة واحدة فقط. انشر السرّ الجديد في تطبيقاتك؛ يتوقّف القديم عن العمل فورًا.

الأخطاء

راجع الأخطاء لأجسام الاستجابات وحدود المعدّل لتفاصيل الحصص.