مرجع API

سيُولَّد مرجع API الكامل تلقائياً من مواصفات OpenAPI 3.1 الخاصة بنا في اللحظة التي تستقر فيها الواجهة. نُفضّل شحن صفحة placeholder بدلاً من توثيق وهمي لنقاط نهاية قد تتغير. في هذه الأثناء، إليك الشكل، وما سيغطّيه، وما يمكنك فعله اليوم.

الشكل (قابل للتغيير)

REST فوق HTTPS. JSON دخولاً وخروجاً. الإصدار في المسار: /v1/.... يوجد مخططان للمصادقة، والمخطط الذي ترسله يعلن أي نوع من principal أنت: Authorization: ApiKey <prefix>.<secret> للاستدعاء البرمجي، وAuthorization: Bearer <token> لجلسة مسجَّلة الدخول. كل مسار يقرر بنفسه الأنواع التي يقبلها، فلا يمكن استنتاج أي شيء من الـ URL: معظم مسارات المشروع تقبل الاثنين، و/v1/mcp/* لا يقبل إلا مفاتيح API، ومسارات الحساب وstaff لا تقبل إلا الجلسة. وأي حالة أخرى تُرجع 401. تُربَط scopes مفتاح API بدور مشروع قبل التحقق من الصلاحيات (project:read يصبح viewer، وproject:write أو cdn:write يصبح developer). انتبه لـBearer: على /v1/feedback/* و/v1/in-context/* يحمل رمز مستخدم نهائي محدود النطاق، وهي عائلة رموز مختلفة عن الجلسة؛ تحقق من أيهما تتوقعه تلك الواجهة. لا يُطبَّق rate limit إلا على ثلاث واجهات (feedback، bundle، missing)، وتحمل headers الخاصة بها بادئة حسب العائلة: X-Feedback-RateLimit-Limit و-Remaining و-Reset، إضافة إلى X-Feedback-Quota-Remaining. لا وجود لأي header عام باسم X-RateLimit-*، وكل endpoints /v1/ الأخرى لا تُرجع أي header للتحديد إطلاقاً. ويجري العد حسب المؤسسة، لا حسب مفتاح API: إصدار مفتاح ثانٍ لا يرفع ميزانيتك، بل يتقاسمها.

curl

1# تأخذ كل نقطة نهاية مفتاح API في رأس Authorization2curl https://api.sonenta.dev/v1/projects \3  -H "Authorization: ApiKey snt_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }

تأتي مفاتيح API من Org Settings → API Keys في لوحة التحكم. نفس المفتاح يصلح لـ CLI، وخادم MCP، والاستدعاءات المباشرة لـ REST, يستهلك API الـ bearer فقط.

الموارد التي ستراها عند الإطلاق

هذه هي الموارد التي ستكشفها V1 API. الشكل الدقيق, الحقول، رموز الأخطاء، التصفح, سيُحسم عند نشر مواصفات OpenAPI.

المورد	ما الذي يمثّله	عمليات V1
Projects	Workspaces. Create وlist وarchive ونقل الـ ownership.	GET · POST · PATCH · DELETE
Locales	مجموعة لغات على مستوى المشروع. إضافة لغة، تعيينها كافتراضية، تفعيلها/تعطيلها للعملاء.	GET · POST · PATCH · DELETE
Namespaces	حِزم منطقية للمفاتيح داخل المشروع (مثل "checkout" و"common").	GET · POST · PATCH · DELETE
Keys	مفاتيح الترجمة مع وصفها وروابط لقطات الشاشة وأقصى طول وقواعد الجمع.	GET · POST · PATCH · DELETE
Translations	قيمة المفتاح لكل لغة. حالات draft وin-review وapproved، وتاريخ المراجعات.	GET · POST · PATCH · DELETE
Missing keys	طابور SDK في الـ runtime. قوائم، تجميع حسب التكرار، وضع علامة triaged.	GET · PATCH
Webhooks	الاشتراك في أحداث الترجمة. V2.	V2

ماذا تفعل اليوم

تقريباً كل ما قد تحتاج إلى API لأجله مكشوف بالفعل عبر CLI أو خادم MCP أو SDK في الـ runtime. استخدمها, عند إطلاق API، يمكن لكودك التحول إلى استدعاءات HTTP مباشرة دون تغيير ما يفعله فعلاً.

CLI

@sonenta/cli

Push وpull وimport وexport, يغطّي معظم احتياجات الأتمتة.

MCP

إعداد Claude Desktop

اقرأ المفاتيح، اقترح ترجمات، راجع diffs الخاصة بالـ PRs من أي وكيل.

SDK

React + i18next

اقرأ الترجمات والتقط المفاتيح الناقصة في الـ runtime لديك.

مرجع

كل الوثائق

فهرس بكل ما نشرناه حتى الآن.

متى يصل المرجع العام؟

ستُقدَّم مواصفات OpenAPI العامة على https://api.sonenta.dev/openapi.json فور تجميد سطح V1. عندها ستتحول هذه الصفحة من placeholder إلى مرجع مُعرَّض بالكامل (Stoplight أو عارض مشابه فوق المواصفات), بلا نص تسويقي، فقط كل نقطة نهاية، كل حمولة، كل رمز خطأ، مولَّدة من المصدر.