انتقل إلى المحتوى
Localtonet Localtonet لوحة التحكم

واجهة Localtonet REST API

مساعدة بشأن هذه الصفحة
في هذه الصفحة 8 أقسام
  1. المرجع التفاعلي
  2. قبل أن تبدأ
  3. عنوان URL الأساسي والمصادقة
  4. الاصطلاحات
  5. الأخطاء
  6. حدود المعدل
  7. أمثلة
  8. اعرض أنفاقك
  9. أنشئ نفق HTTP بنطاق فرعي عشوائي
  10. شغّل النفق
  11. مجموعات نقاط النهاية
  12. الأنفاق
  13. العمليات المجمّعة على الأنفاق
  14. إعداد النفق
  15. AuthTokens
  16. مجموعات التوكنات
  17. الخوادم
  18. مزوّدو SSO
  19. وصول VPN
  20. استكشاف الأخطاء وإصلاحها
  21. صفحات ذات صلة

تتيح لك واجهة REST API v2 ما تفعله لوحة التحكم مع الأنفاق: إنشاؤها وتشغيلها وإيقافها وحذفها وضبطها، وإدارة AuthTokens ومجموعات التوكنات ومزوّدي SSO. وتصادق كل طلب بمفتاح API الخاص بك.

المرجع التفاعلي #

كل نقطة نهاية، مع نماذج طلبها واستجابتها ونموذج لتجربتها، موجودة في المرجع التفاعلي:

  • localtonet.com/api: واجهة API v2، وهي الإصدار الحالي. ويمكنك الوصول إليها أيضًا بزر واجهة API في لوحة التحكم.
  • localtonet.com/api/v1: واجهة API v1، وتبقى متاحة للتكاملات الحالية. استخدم v2 للأعمال الجديدة.

تعرض هذه الصفحة الاصطلاحات ونظرة عامة على مجموعات نقاط النهاية. وللاطلاع على الحقول الدقيقة لطلب ما، افتح نقطة النهاية في المرجع.

قبل أن تبدأ #

  • مفتاح API الخاص بك. افتح لوحة التحكم واستخدم نسخ في بطاقة مفتاح API. راجع الحساب والأمان.
  • لإنشاء نفق: AuthToken للجهاز الذي سيشغّل النفق، وعميل Localtonet متصل بذلك التوكن. راجع AuthTokens.

أبقِ مفتاح API سريًا. من يملكه يستطيع إنشاء أنفاقك وتوكناتك وتغييرها وحذفها. ويؤدي تغيير في بطاقة مفتاح API إلى إنشاء مفتاح جديد وإبطال القديم.

عنوان URL الأساسي والمصادقة #

تبدأ كل نقاط نهاية v2 بـ:

عنوان URL الأساسي
https://localtonet.com/api/v2

أرسل مفتاح API توكنًا من نوع Bearer في ترويسة Authorization لكل طلب:

HTTP
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>

مفتاح API المنسوخ في لوحة تحكم فريق يعرض AuthTokens وأنفاق ذلك الفريق؛ أما مفتاح حسابك الشخصي فيعرض AuthTokens التي لا تنتمي إلى أي فريق.

الاصطلاحات #

الموضوعكيف تتصرف واجهة API
الصيغةأجسام الطلبات والاستجابات بصيغة JSON. أرسل Content-Type: application/json مع أي جسم.
معرّف النفققيمة tunnelId في المسار هي id الرقمي للنفق، كما تعيده نقاط نهاية القائمة والإنشاء.
AuthToken في المسار{token} هو نص AuthToken نفسه.
رموز النجاح200 مع جسم للقراءات، و201 لمعظم عمليات الإنشاء (تعيد نقاط نهاية إنشاء النفق النفق الجديد)، و204 بدون جسم لمعظم الإجراءات والتحديثات. ويعرض المرجع إجابة كل نقطة نهاية.
نقاط النهاية المجمّعةالمسارات التي تحتوي على /bulk/ تأخذ مصفوفة JSON وتقبل حتى 100 عنصر في الطلب الواحد (/tunnels/bulk/protocol-type: حتى 500).
الأنفاق الجديدةالنفق الذي تنشئه لا يكون قيد التشغيل بعد. شغّله بإجراء التشغيل. ونقاط النهاية proxy/with-detail فقط تستطيع تشغيل النفق في الاستدعاء نفسه، باستخدام isStartAfterCreate.

الأخطاء #

الحالةالمعنىالجسم
400جسم الطلب غير صالح، أو رُفضت العملية، مثلًا بسبب أحد حدود خطتك.في معظم نقاط النهاية يكون كائن مشكلة بصيغة JSON؛ ويحمل title الرسالة. وتُسرد أخطاء التحقق وأخطاء نقاط النهاية المجمّعة تحت errors.
401مفتاح API مفقود أو غير صالح.لا رسالة محددة
403, 409تعيدها بعض نقاط نهاية إعداد النفق ونقاط نهاية وصول VPN عندما لا يكون التغيير مسموحًا به أو يتعارض مع الإعداد الحالي.كائن مشكلة تكون رسالته في title.
404لم يُعثر على النفق أو الكائن، أو أنه لا يخصك.فارغ أو كائن مشكلة
429طلبات كثيرة جدًا.راجع حدود المعدل أدناه.

حدود المعدل #

للطلبات حد معدل. يُجاب الطلب الذي يتجاوز الحد بـ429 Too Many Requests. انتظر ثم أرسله مرة أخرى؛ واستخدم نقاط النهاية المجمّعة بدلًا من استدعاءات فردية كثيرة.

أمثلة #

استبدل <YOUR_API_KEY> بمفتاح API الخاص بك و<YOUR_TOKEN> بـ AuthToken الجهاز.

اعرض أنفاقك #

Bash
curl https://localtonet.com/api/v2/tunnels \
  -H "Authorization: Bearer <YOUR_API_KEY>"

الإجابة مصفوفة JSON فيها كائن لكل نفق. ومن حقوله id وtitle وurl (العنوان العام) وprotocolType وauthToken وserverId وclientIp وclientPort (الهدف المحلي) وstatus وconnectionStatus. وإذا لم تكن لديك أنفاق بعد، فالإجابة هي 404 بدلًا من مصفوفة فارغة.

أنشئ نفق HTTP بنطاق فرعي عشوائي #

احصل أولًا على رمز الخادم الذي تريد استخدامه:

Bash
curl https://localtonet.com/api/v2/servers \
  -H "Authorization: Bearer <YOUR_API_KEY>"

لكل عنصر serverCode وserverName وserverDomain. ثم أنشئ النفق. يعيد هذا المثال التوجيه إلى تطبيق ويب على المنفذ 3000 في الجهاز:

Bash
curl -X POST https://localtonet.com/api/v2/tunnels/http/random-subdomain \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "authToken": "<YOUR_TOKEN>",
    "serverCode": "<SERVER_CODE>",
    "protocolType": 1,
    "ip": "127.0.0.1",
    "port": 3000
  }'
الحقلالمعنىالقيم
authTokenAuthToken الجهاز الذي يشغّل النفق.مطلوب
serverCodeالخادم، من GET /servers.مطلوب
protocolTypeنوع النفق.1 HTTP، 5 File Server، 24 MCP Gateway
ipعنوان IP المحلي الذي يوجّه إليه النفق.عنوان IP صالح، مثل 127.0.0.1
portالمنفذ المحلي.من 1 إلى 65534
pathالمجلد المحلي المراد مشاركته.مطلوب لخادم الملفات فقط

الإجابة 201 Created مع النفق الجديد. دوّن قيمتي id وurl له.

شغّل النفق #

Bash
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
  -H "Authorization: Bearer <YOUR_API_KEY>"

الإجابة 204 No Content. يصبح النفق متاحًا عند url الخاص به عندما يكون عميل الجهاز متصلًا. وأوقفه مرة أخرى بالإجراء /actions/stop.

مجموعات نقاط النهاية #

كل المسارات أدناه نسبية إلى https://localtonet.com/api/v2.

الأنفاق #

الطريقةالمسارالغرض
GET/tunnelsعرض كل أنفاقك.
GET/tunnels/{tunnelId}الحصول على نفق واحد.
POST/tunnels/http/random-subdomainإنشاء نفق HTTP أو خادم الملفات أو بوابة MCP بنطاق فرعي عشوائي.
POST/tunnels/http/custom-subdomainإنشاء نفق بنطاق فرعي تختاره.
POST/tunnels/http/custom-domainإنشاء نفق على نطاقك الخاص.
POST/tunnels/tcp-udpإنشاء نفق TCP أو UDP أو TCP وUDP معًا.
POST/tunnels/proxyإنشاء نفق بروكسي HTTP أو SOCKS5 أو Shadowsocks أو VLESS.
POST/tunnels/proxy/with-detailإنشاء نفق بروكسي وإعادة تفاصيل اتصاله الكاملة.
POST/tunnels/shared-proxyإنشاء نفق بروكسي مشترك (دوّار).
POST/tunnels/{tunnelId}/actions/startتشغيل نفق.
POST/tunnels/{tunnelId}/actions/stopإيقاف نفق.
DELETE/tunnels/{tunnelId}حذف نفق نهائيًا.
PATCH/tunnels/{tunnelId}/titleتغيير العنوان.
PATCH/tunnels/{tunnelId}/local-ipتغيير عنوان IP المحلي.
PATCH/tunnels/{tunnelId}/local-portتغيير المنفذ المحلي.
PATCH/tunnels/{tunnelId}/port-reservedتفعيل حجز المنفذ لنفق TCP/UDP أو إيقافه.
PATCH/tunnels/{tunnelId}/legacy-connectتفعيل وضع الاتصال القديم أو إيقافه.
PATCH/tunnels/{tunnelId}/protocol-typeتغيير بروتوكول البروكسي لنفق بروكسي.
GET/tunnels/{tunnelId}/request-logsأحدث سجلات طلبات HTTP لنفق HTTP أو خادم الملفات.

العمليات المجمّعة على الأنفاق #

الطريقةالمسارالغرض
POST/tunnels/bulk/http/random-subdomainإنشاء عدة أنفاق HTTP بنطاقات فرعية عشوائية.
POST/tunnels/bulk/http/custom-subdomainإنشاء عدة أنفاق بنطاقات فرعية مخصصة.
POST/tunnels/bulk/http/custom-domainإنشاء عدة أنفاق على نطاقات مخصصة.
POST/tunnels/bulk/tcp-udpإنشاء عدة أنفاق TCP/UDP.
POST/tunnels/bulk/proxyإنشاء عدة أنفاق بروكسي.
POST/tunnels/bulk/proxy/with-detailإنشاء عدة أنفاق بروكسي وإعادة تفاصيل اتصالها.
POST/tunnels/bulk/shared-proxyإنشاء عدة أنفاق بروكسي مشتركة (دوّارة).
POST/tunnels/bulk/actions/startتشغيل عدة أنفاق. الجسم: مصفوفة من معرّفات الأنفاق، مثل [123, 456].
POST/tunnels/bulk/actions/stopإيقاف عدة أنفاق. الجسم: مصفوفة من معرّفات الأنفاق.
DELETE/tunnels/bulkحذف عدة أنفاق. الجسم: مصفوفة من معرّفات الأنفاق.
PATCH/tunnels/bulk/protocol-typeتغيير بروتوكول البروكسي لعدة أنفاق بروكسي.

إعداد النفق #

تغيّر نقاط النهاية هذه إعدادات نفق واحد. وكلها تبدأ بـ/tunnels/{tunnelId}. وما يفعله كل إعداد موضح في مرجع الإعدادات.

الطرقالمسار بعد /tunnels/{tunnelId}الغرض
GET وPOST وPATCH وDELETE/ip-restrictionsعرض قيود IP أو إضافتها أو ضبط وضع السماح أو الحظر أو حذفها كلها. احذف واحدًا بـ/ip-restrictions/{restrictionId}.
GET وPOST وPATCH وDELETE/access-controlsالأمر نفسه لضوابط الوصول إلى مسارات URL. احذف واحدًا بـ/access-controls/{controlId}.
GET وPATCH/headersترويسات HTTP المخصصة.
GET وPATCH/authenticationمصادقة HTTP الأساسية (Basic Authentication).
GET وPATCH/expirationتاريخ انتهاء النفق.
GET وPATCH/server-portمنفذ جانب الخادم لنفق TCP/UDP.
GET وPATCH/http-timeoutمهلة طلب HTTP.
GET وPATCH/rate-limitحد السرعة.
GET وPATCH/bandwidth-limitحد إجمالي نقل البيانات.
GET/bandwidth-usageاستهلاك النطاق الترددي الحالي. أعد ضبط العدّاد بـPOST /bandwidth-usage/reset.
GET وPATCH/argumentsوسائط سطر أوامر مخصصة للنفق.
GET وPOST/shared-proxy-clientsعرض عملاء نفق بروكسي مشترك (دوّار) أو إضافتهم. حدّث واحدًا أو احذفه بـPATCH أو DELETE /shared-proxy-clients/{clientId}.
GET/advanced-settingsكل الإعدادات المتقدمة للنفق في إجابة واحدة.
GET وPATCH/ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3قراءة إعداد متقدم واحد أو تبديله.
PATCH/ssl-streamتبديل إعداد تدفق SSL.
GET وPATCH/file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vlessقراءة قيمة واحدة أو تغييرها.
GET وPUT/token-groupsمجموعات التوكنات المعيّنة للنفق.
GET وPATCH/serverخادم النفق.

AuthTokens #

الطريقةالمسارالغرض
GET/auth-tokensعرض AuthTokens الخاصة بك.
GET/auth-tokens/detailعرض AuthTokens الخاصة بك مع التفاصيل.
GET/auth-tokens/{token}تفاصيل AuthToken واحد.
POST/auth-tokensإنشاء AuthToken.
DELETE/auth-tokens/{token}حذف AuthToken.
GET/auth-tokens/{token}/tunnelsأنفاق AuthToken.
GET/auth-tokens/{token}/ip-historyسجل تغييرات عنوان IP العام للجهاز.
GET وPATCH/auth-tokens/{token}/airplane-mode-settingsإعدادات أتمتة وضع الطيران.
POST/auth-tokens/{token}/change-ip-links/{airplaneModeSettingId}إضافة رابط تغيير IP.
DELETE/auth-tokens/{token}/change-ip-links/{id}حذف رابط تغيير IP.
POST/auth-tokens/{token}/restart-device-links/{airplaneModeSettingId}إضافة رابط إعادة تشغيل الجهاز.
DELETE/auth-tokens/{token}/restart-device-links/{id}حذف رابط إعادة تشغيل الجهاز.
GET وPATCH/auth-tokens/{token}/argumentsوسائط العميل المحفوظة على AuthToken.

مجموعات التوكنات #

الطريقةالمسارالغرض
GET/token-groupsعرض مجموعات التوكنات الخاصة بك.
GET/token-groups/{id}الحصول على مجموعة توكنات واحدة.
POST/token-groupsإنشاء مجموعة توكنات.
DELETE/token-groups/{id}حذف مجموعة توكنات.
POST/token-groups/{id}/auth-tokensإضافة AuthToken إلى المجموعة.
DELETE/token-groups/{id}/auth-tokens/{tokenId}إزالة AuthToken من المجموعة.

الخوادم #

الطريقةالمسارالغرض
GET/serversعرض الخوادم التي يمكنك إنشاء أنفاق عليها، مع serverCode الذي يُستخدم في طلبات الإنشاء.

مزوّدو SSO #

الطريقةالمسارالغرض
GET/sso-providersعرض مزوّدي SSO الخاصين بك.
GET/sso-providers/default-endpointsنقاط النهاية الافتراضية لنوع مزوّد SSO.
POST/sso-providersإنشاء مزوّد SSO أو تحديثه.
DELETE/sso-providers/{id}حذف مزوّد SSO.
GET/sso-providers/tunnel/{tunnelId}مزوّدو SSO المضبوطون لنفق. هنا tunnelId هو GUID النفق (guidId).
PUT/sso-providers/tunnel/{tunnelId}حفظ مزوّدي SSO لنفق.

راجع تسجيل الدخول الموحّد لمعرفة ما يفعله المزوّدون.

وصول VPN #

يمنح وصول VPN ملف جهاز WireGuard أو OpenVPN على نفق بروكسي؛ وتخرج حركة ذلك الجهاز كلها عبر البروكسي. تبدأ نقاط النهاية هذه بـ/tunnels/{tunnelId}/vpn-access.

الطريقةالمسار بعد /tunnels/{tunnelId}/vpn-accessالغرض
GET(لا شيء)عرض أجهزة VPN الخاصة بالنفق.
POST(لا شيء)إنشاء جهاز VPN.
DELETE/{peerId}حذف (إلغاء) جهاز VPN.
POST/{peerId}/regenerateإعادة توليد مفاتيح جهاز VPN.
GET/{peerId}/configتنزيل ملف إعداد جهاز VPN.
GET/{peerId}/qrرمز QR لإعداد جهاز WireGuard.
GET/{peerId}/credentialsاسم المستخدم وكلمة المرور لجهاز OpenVPN.

استكشاف الأخطاء وإصلاحها #

كل طلب يعيد 401

تحقق من الترويسة: يجب أن تكون Authorization: Bearer يليها مسافة ثم المفتاح، دون علامات اقتباس حول المفتاح. وإذا اخترت تغيير في بطاقة مفتاح API فلن يعمل المفتاح القديم؛ انسخ الجديد.

لا أرى AuthTokens الخاصة بفريقي

أنت تستخدم مفتاح API لحسابك الشخصي. انتقل إلى لوحة تحكم الفريق وانسخ مفتاح API هناك.

أُنشئ النفق لكن عنوانه لا يستجيب

النفق الجديد يكون متوقفًا. استدعِ POST /tunnels/{tunnelId}/actions/start، وتأكد من أن عميل Localtonet على الجهاز يعمل بـ AuthToken الذي استخدمته.

تظهر لي 429 Too Many Requests

للطلبات حد معدل. انتظر ثم أرسل الطلب مرة أخرى، واستبدل حلقات الاستدعاءات الفردية بطلب مجمّع واحد.

الدعم