المصادقة

تتم مصادقة كل طلب إلى واجهة تكامل 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": "[email protected]",
    "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": "[email protected]",
    "password": "a-strong-password-min-10-chars"
  }'

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

{
  "user": { "id": "uuid", "email": "[email protected]", "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": "starter",
    "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": "starter",
  "quotaPerMinute": 255,
  "quotaPerDay": 100000,
  "unlimited": false,
  "active": true
}

يحمل كل كائن مفتاح حقلًا منطقيًا للقراءة فقط هو unlimited. تكون قيمته true فقط للمفتاح الذي جعلته Navvo غير محدود. وما دامت قيمته true يحتفظ المفتاح بقيمتَي quotaPerMinute وquotaPerDay، لكنهما لا تُفرَضان. ولا يمكنك ضبط unlimited عبر واجهة المطوّرين البرمجية: فهو، مثل أي حقل غير معروف في الجسم، يُحذَف من الطلب. تواصل مع Navvo إن احتجت إلى مفتاح غير محدود.

جسم الطلب — 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 الجديد بنصّه الصريح — ومرّةً أخرى، يُعرَض مرّة واحدة فقط. انشر السرّ الجديد في تطبيقاتك؛ يتوقّف القديم عن العمل فورًا.

تقييد المفتاح

يمكنك قصر المفتاح على الأماكن التي يُفترض أن يُستخدم منها. يحمل المفتاح قائمتين. كل قائمة فيها عناصر يجب أن تتطابق، والقائمة الفارغة تعني عدم وجود قيد من ذلك النوع:

اضبطهما في بوابة المطورين (مفاتيح API ← تعديل)، أو عبر الواجهة البرمجية:

curl -X PATCH "https://navvo.io/api/v1/developer/api-keys/<keyId>" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "restrictions": { "referrers": ["example.com", "*.example.com", "localhost:3000"] } }'

المواقع. اكتب اسم المضيف، مع منفذ اختياري: example.com أو app.example.com أو localhost:3000. يشمل *.example.com كل النطاقات الفرعية لكنه لا يشمل example.com نفسه، فاذكر الاثنين إن احتجت إليهما. يُقبَل البروتوكول أو المسار ثم يُحذف (https://example.com/* يُحفَظ بصيغة example.com). وعند عدم ذكر منفذ يُقبَل أي منفذ. يُرفَض الطلب الذي لا يذكر أي موقع، أي الطلب الخالي من Origin وReferer معًا، مثل الطلب الآتي من خادم، أو من متصفح تحذف إعدادات الخصوصية فيه الترويستين.

عناوين IP. اكتب عناوين أو نطاقات CIDR، بصيغة IPv4 أو IPv6: 203.0.113.7 أو 198.51.100.0/24 أو 2001:db8::/32.

تتّسع كل قائمة لـ 50 عنصرًا كحدّ أقصى. وفي طلب PATCH:

• القائمة التي لا ترسلها تحتفظ بعناصرها؛
• [] تفرغ القائمة؛
• "restrictions": null يزيل القائمتين معًا.

يُرفَض العنصر غير الصالح بالرمز 400 وتذكره الرسالة باسمه، ولا يُحذف أي عنصر بصمت. وتتضمّن كل استجابة تخصّ مفتاحًا الحقل restrictions بقائمتيه، وتكونان فارغتين إذا لم يكن المفتاح مقيّدًا.

يعيد الطلب المرفوض الرمز 403 مع code، ومعه الموقع أو عنوان IP الذي جاء منه الطلب، لتعرف ما الذي يجب إضافته:

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "KEY_WEBSITE_NOT_ALLOWED",
  "message": "This API key is not allowed from this website",
  "details": { "website": "copycat.example" }
}

تُفحَص القيود قبل النطاقات والحصّة، فلا يُحتسب الطلب المرفوض من حصّة المفتاح. أما بيئة الاختبار في البوابة فتعمل على خوادم Navvo نيابةً عنك ولا تطبّق هذه القيود.

الأخطاء

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