المطورون / Tools
إنشاء أداة OpenAPI
https://api.echonova.ai/v1/tools/openapiيستورد مستند OpenAPI، مضمَّنًا أو من عنوان URL عام، كأداة واحدة فيها عملية لكل نقطة نهاية. تُربط اتصالات المصادقة وترويسات الأسرار بمعرّفاتها، وتُرفض القيم النصية العادية التي تبدو كبيانات اعتماد. تُفهرس عملية الاستيراد قبل أن يردّ الطلب. أرسل `Idempotency-Key` لإعادة المحاولة بأمان. الحد الأقصى 5 استدعاءات في الدقيقة لكل مفتاح. تُربط الأسرار بمعرّفاتها من GET /v1/secrets، ولا تُدخل قيمها إلا في خزنة البوابة. الخدمة مجانية. يحتاج المفتاح إلى النطاق `tools:write`.
Headers
كلمة Bearer ثم مسافة ثم مفتاح API الذي يبدأ بـ ek_. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.
اختياري. كرّر المفتاح نفسه خلال 24 ساعة لإعادة المحاولة بأمان: تعود النتيجة الأولى، ولا يُنشأ شيء مرتين. الطلب الجديد يحتاج إلى مفتاح جديد.
متن الطلب
application/json
مستند OpenAPI بصيغة JSON، بحجم يصل إلى 5 ميغابايت. أرسل واحدًا فقط من `spec` أو `url`.
عنوان URL عام بروتوكول https لمستند OpenAPI. أرسل واحدًا فقط من `spec` أو `url`.
اسم الأداة، ويجب أن يكون فريدًا في مساحة العمل.
الغرض من واجهة البرمجة.
الخادم الذي تستدعيه الأداة.
أسماء العمليات المراد استيرادها. اتركه فارغًا لاستيراد الكل.
معرّف اتصال المصادقة المرسَل مع كل استدعاء. اعرض المعرّفات عبر GET /v1/auth-connections. اتركه فارغًا لواجهة عامة لا تحتاج مصادقة.
وصف كل عملية، والقيم الثابتة لها، ومصادقتها.
الاستجابة
200 application/json كل استجابة تستخدم هذا الغلاف.
النتيجة.
معرّف الأداة.
اسم الأداة، ويكون فريدًا في مساحة العمل.
`webhook` أو `openapi` أو `integration`.
وظيفة الأداة، أو `null`.
وقت إنشاء الأداة.
وقت آخر تغيير في الأداة.
يُعبَّأ لأدوات webhook. القيم الثابتة لا تُعاد أبدًا.
عنوان URL الذي تستدعيه الأداة.
طريقة HTTP للاستدعاء.
أقصى مدة للاستدعاء بالمللي ثانية، أو `null` للقيمة الافتراضية.
معرّف اتصال المصادقة المستخدم في الاستدعاء، أو `null`.
القيم التي يرسلها الاستدعاء.
مكان المعامل في الطلب.
مفتاح المعامل، أو اسم عنصر المسار.
نوع القيمة التي يأخذها المعامل.
هل يحتاج الاستدعاء إلى هذا المعامل.
يوضح للنموذج ما يضعه هنا، أو `null`.
`llm` أو `constant` أو `secret`. القيم الثابتة لا تُعاد أبدًا.
معرّف السر في الخزنة عندما تكون `valueType` هي `secret`، وإلا فهي `null`.
يُعبَّأ لأدوات OpenAPI.
عنوان مستند OpenAPI المستورد.
عدد العمليات التي استوردتها الأداة.
هل أصبح الاستيراد جاهزًا للوكلاء.
الخادم الذي تستدعيه الأداة، أو `null`.
أسماء العمليات المختارة للاستيراد، والقائمة فارغة للكل.
معرّف اتصال المصادقة المرسَل مع كل استدعاء، أو `null`.
سبب فشل الاستيراد، أو `null`.
يُعبَّأ لأدوات التكامل.
مزوّد التكامل.
مفتاح أداة التكامل.
قيمته true عند نجاح الطلب.
يكرر رمز حالة HTTP.
قيمته null عند النجاح.
الأخطاء
الغلاف نفسه، مع success بقيمة false و data بقيمة null. كل الأخطاء
متى يحدث. معامل أو عنصر في `fieldValues` قيمته `constant` واسمه يبدو كبيانات اعتماد، مثل Authorization أو token أو api key أو cookie. تذكر الرسالة الحقل ولا تذكر قيمته أبدًا.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم اتصال مصادقة.
متى يحدث. قيمة ثابتة تبدأ بـ Bearer أو Basic أو Token أو Digest، أو لها شكل JWT. تذكر الرسالة الحقل ولا تذكر قيمته أبدًا.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم اتصال مصادقة.
متى يحدث. عنوان webhook أو `baseUrlOverride` فيه مفتاح استعلام يبدو كبيانات اعتماد. تذكر الرسالة المفتاح ولا تذكر قيمته أبدًا.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم اتصال مصادقة.
متى يحدث. مفتاح يشبه بيانات الاعتماد مخفي في جزء الاستعلام أو في جزء المرجع (fragment) من عنوان webhook أو `baseUrlOverride`.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم اتصال مصادقة.
متى يحدث. عنوان `url` للوثيقة لا يستخدم https، أو يشير إلى عنوان loopback أو خاص أو link-local، أو ليس عنوان URL.
الحل. أرسل عنوان https عامًا، أو أرسل الوثيقة مضمّنة في `spec`.
متى يحدث. عنوان `url` للوثيقة يحمل اسم مستخدم أو كلمة مرور.
الحل. أرسل العنوان بدونهما، واستخدم header سريًّا أو اتصال مصادقة.
متى يحدث. قيمة `baseUrlOverride` لا تستخدم https، أو تشير إلى عنوان loopback أو خاص أو link-local، أو ليست عنوان URL.
الحل. أرسل عنوان https عامًا.
متى يحدث. قيمة `baseUrlOverride` تحمل اسم مستخدم أو كلمة مرور.
الحل. أرسل العنوان بدونهما، واستخدم header سريًّا أو اتصال مصادقة.
متى يحدث. تعذّرت قراءة المستند بوصفه مستند OpenAPI. يسمّي النص ما هو خاطئ، لذلك يختلف.
الحل. صحّح الوثيقة كما تقول الرسالة، ثم عاين الاستيراد من جديد.
متى يحدث. الجسم يحتوي على `spec` و`url` معًا، أو لا يحتوي على أيٍّ منهما.
الحل. أرسل واحدًا فقط منهما.
متى يحدث. مستند `spec` المضمَّن أكبر من 5 ميغابايت.
الحل. أرسله كعنوان `url` عام بدلًا من ذلك.
متى يحدث. المستند عند العنوان `url` أكبر من 5 ميغابايت.
الحل. أرسل مستندًا أصغر.
متى يحدث. لم يردّ عنوان `url` في الوقت المحدد، أو تعذّرت قراءته.
الحل. تحقّق من أن عنوان `url` عام ويردّ بسرعة، أو أرسل المستند مضمّنًا.
متى يحدث. ردّ عنوان `url` برمز خطأ. تذكر الرسالة الرمز.
الحل. تحقّق من عنوان `url`.
متى يحدث. ردّ عنوان `url` بشيء ليس مستند JSON.
الحل. أرسل المستند بصيغة JSON.
متى يحدث. قيمة `baseUrlOverride` مفقودة عند الإنشاء.
الحل. أرسل الخادم الذي تستدعيه الأداة في `baseUrlOverride`.
متى يحدث. `secretId` أو `connectionId` أو `authConnectionId` ليس معرّفًا صالحًا من 24 محرفًا سداسي عشريًا. تذكر الرسالة الحقل.
الحل. استخدم معرّفًا من GET /v1/secrets أو GET /v1/auth-connections.
متى يحدث. `secretId` في `fieldValues` غير معروف، أو يتبع مساحة عمل أخرى. تذكر الرسالة العملية.
الحل. استخدم معرّفًا من GET /v1/secrets.
متى يحدث. `connectionId` أو `authConnectionId` غير معروف، أو يتبع مساحة عمل أخرى، أو هو اتصال تديره قناة.
الحل. استخدم معرّفًا من GET /v1/auth-connections.
متى يحدث. `connectionId` في `operationEdits` غير معروف، أو يتبع مساحة عمل أخرى، أو هو اتصال تديره قناة. تذكر الرسالة العملية.
الحل. استخدم معرّفًا من GET /v1/auth-connections.
متى يحدث. سر في `fieldValues` يستهدف شيئًا غير معامل ترويسة.
الحل. أرسل السر كمعامل ترويسة.
متى يحدث. اسم في `operationEdits` ليس عملية من المستند. تذكر الرسالة الأسماء.
الحل. استخدم أسماء العمليات من المعاينة.
متى يحدث. اسم في `fieldValues` ليس معاملًا أو حقلًا في جسم الطلب لتلك العملية.
الحل. استخدم الأسماء من المعاينة.
متى يحدث. المستند فيه أكثر من 2000 عملية للاستيراد. تذكر الرسالة العدد.
الحل. أرسل `includeOperations` بالعمليات التي تحتاجها.
متى يحدث. قُبل الاستيراد لكنه لم يُعد معرّفًا تُحفظ الأداة تحته، ولم يُحفظ شيء.
الحل. أعد الاستدعاء، وإن استمر الفشل فتواصل مع الدعم.
متى يحدث. ترويسة `Idempotency-Key` أطول من 200 حرف، أو تحتوي على مسافة أو على حرف خارج ASCII القابل للطباعة.
الحل. أرسل من 1 إلى 200 حرف ASCII قابل للطباعة، مثل UUID.
متى يحدث. متن الطلب أو الاستعلام يحمل حقلًا لا تعرّفه نقطة النهاية.
الحل. احذف الحقل.
متى يحدث. header `Authorization` مفقود، أو قيمته لا تبدأ بـ `Bearer ek_...`، أو أن الرمز لا يطابق أي مفتاح، أو أن المفتاح محذوف أو معطّل أو منتهي الصلاحية، أو أن حسابه مغلق.
الحل. أرسل `Authorization: Bearer ek_...` بمفتاح API مفعّل.
متى يحدث. مساحة العمل التي يتبعها المفتاح ليس لديها اشتراك.
الحل. تحقّق من خطة مساحة العمل في البوابة.
متى يحدث. حالة الاشتراك ليست نشطة ولا تجريبية.
الحل. جدّد الاشتراك.
متى يحدث. المفتاح لا يملك النطاق `tools:write`. النطاق `agents:write` لا يمنح هذا الحق.
الحل. عدّل المفتاح وامنحه النطاق `tools:write`، أو استخدم مفتاحًا آخر.
متى يحدث. العضو الذي أنشأ المفتاح غادر مساحة العمل، أو لم يعد يملك الصلاحيتين معًا: إدارة الأدوات وإدارة واجهة برمجة التطبيقات للمطورين. يُفحص ذلك مع كل استدعاء.
الحل. امنح ذلك العضو الصلاحيتين مرة أخرى، أو أنشئ مفتاحًا بعضو يملكهما.
متى يحدث. أداة أخرى في مساحة العمل تحمل هذا الاسم. تذكر الرسالة الأداة.
الحل. اختر اسمًا آخر.
متى يحدث. أرسل هذا المفتاح `Idempotency-Key` نفسه خلال آخر 24 ساعة، مع جسم طلب مختلف أو وكيل مختلف.
الحل. استخدم `Idempotency-Key` جديدًا لطلب جديد.
متى يحدث. الطلب الأول بهذا `Idempotency-Key` لم ينتهِ بعد.
الحل. انتظر قليلًا، ثم أعد المحاولة بالمفتاح نفسه لتحصل على نتيجته.
متى يحدث. جسم JSON لمعاينة OpenAPI أو إنشائها أكبر من 6 ميغابايت. يُرفض الطلب قبل فحص مفتاح API، لذلك لا يظهر له سطر في سجل النشاط.
الحل. أرسل المستند كعنوان `url` عام بدلًا من المضمَّن.
متى يحدث. للطلب جسم وقيمة `Content-Type` فيه ليست `application/json`.
الحل. أرسل `Content-Type: application/json`.
متى يحدث. أرسل المفتاح أكثر من 5 طلبات إلى هذه النقطة خلال 60 ثانية. ترويسة `Retry-After` تحمل عدد الثواني للانتظار.
الحل. انتظر عدد الثواني في `Retry-After`، ثم أعد المحاولة.
متى يحدث. خطأ لم تصنّفه API.
الحل. تحقّق من الطلب، ثم أعد المحاولة بعد لحظة قصيرة؛ وتواصل مع الدعم إذا تكرر الخطأ.
متى يحدث. انقطاع مؤقت داخل API.
الحل. أعد المحاولة بعد لحظة قصيرة.
متى يحدث. انتهاء مهلة مؤقت داخل API.
الحل. أعد المحاولة بعد لحظة قصيرة.
curl -X POST "https://api.echonova.ai/v1/tools/openapi" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Orders API","baseUrlOverride":"https://api.example.com"}'{
"data": {
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Order lookup",
"type": "webhook",
"description": "Finds an order by its number.",
"createdAt": "2026-11-01T10:00:00.000Z",
"updatedAt": "2026-11-01T10:00:00.000Z",
"webhook": {
"url": "https://api.example.com/orders/{orderId}",
"method": "GET",
"timeoutMs": 10000,
"connectionId": "6650a1b2c3d4e5f6a7b8c9d0",
"parameters": [
{
"location": "header",
"name": "orderId",
"dataType": "string",
"required": true,
"description": "Finds an order by its number.",
"valueType": "llm",
"secretId": "YOUR_SECRET_ID"
}
]
},
"openapi": {
"apiTitle": "Orders API",
"operationCount": 12,
"status": "ready",
"baseUrl": "https://api.example.com",
"includeOperations": [
"getOrder"
],
"authConnectionId": "YOUR_AUTH_CONNECTION_ID",
"error": null
},
"integration": {
"provider": "slack",
"key": "add_reaction"
}
},
"success": true,
"statusCode": 200,
"errorMessage": null
}