واجهة Localtonet REST API
في هذه الصفحة 8 أقسام
- المرجع التفاعلي
- قبل أن تبدأ
- عنوان URL الأساسي والمصادقة
- الاصطلاحات
- الأخطاء
- حدود المعدل
- أمثلة
- اعرض أنفاقك
- أنشئ نفق HTTP بنطاق فرعي عشوائي
- شغّل النفق
- مجموعات نقاط النهاية
- الأنفاق
- العمليات المجمّعة على الأنفاق
- إعداد النفق
- AuthTokens
- مجموعات التوكنات
- الخوادم
- مزوّدو SSO
- وصول VPN
- استكشاف الأخطاء وإصلاحها
- صفحات ذات صلة
تتيح لك واجهة 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 بـ:
https://localtonet.com/api/v2أرسل مفتاح API توكنًا من نوع Bearer في ترويسة Authorization لكل طلب:
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 الجهاز.
اعرض أنفاقك #
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 بنطاق فرعي عشوائي #
احصل أولًا على رمز الخادم الذي تريد استخدامه:
curl https://localtonet.com/api/v2/servers \
-H "Authorization: Bearer <YOUR_API_KEY>"لكل عنصر serverCode وserverName وserverDomain. ثم أنشئ النفق. يعيد هذا المثال التوجيه إلى تطبيق ويب على المنفذ 3000 في الجهاز:
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
}'| الحقل | المعنى | القيم |
|---|---|---|
authToken | AuthToken الجهاز الذي يشغّل النفق. | مطلوب |
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 له.
شغّل النفق #
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
للطلبات حد معدل. انتظر ثم أرسل الطلب مرة أخرى، واستبدل حلقات الاستدعاءات الفردية بطلب مجمّع واحد.