البدء: مفاتيح API والاستدعاء الأول.

ما الذي تقدّمه واجهة البرمجة

تمنح KENJTEC API برامجك الخاصة الوصول إلى حسابك: قراءة النماذج وردودها، والمتاجر والطلبات — والكتابة: إنشاء المواقع ونشرها، وإدارة سجلات DNS، وكتابة الفواتير، ورفع الوسائط. ويُضاف إلى ذلك Webhooks — إذ نتصل بخادمك فور حدوث أي أمر. كما يمكن للذكاء الاصطناعي الخاص بك العمل عبر MCP بالمفتاح نفسه.

العنوان هو https://api.kenjtec.com/v1. وواجهة البرمجة مضمّنة في كل باقة مدفوعة، دون أي تكلفة إضافية.

إنشاء مفتاح

يسجّل كل برنامج دخوله بمفتاح واجهة برمجة خاص به. ويحمل المفتاح صلاحيات: forms:read يقرأ النماذج والردود، وorders:read يقرأ المتاجر والطلبات، وwebhooks:manage ينشئ Webhooks ويحذفها. ولـمسارات الكتابة صلاحيات خاصة بكل قسم. امنح كل برنامج مفتاحًا خاصًا به — وعندها يمكنك إلغاء أحدها دون التأثير في البقية.

1. 1افتح لوحة التحكم واختر قسم المطوّر ضمن «الإعدادات».
2. 2ضمن «مفاتيح واجهة البرمجة» امنح المفتاح اسمًا، مثل «مزامنة المخزون».
3. 3ضمن «ما المسموح لهذا المفتاح؟» اختر فقط الصلاحيات التي يحتاجها البرنامج.
4. 4انقر على «إنشاء مفتاح» وانسخ المفتاح فورًا.

يُعرض المفتاح مرة واحدة فقط. لا نخزّن سوى مجموع تحقّق — فإذا فقدته، فألغِه عبر «إلغاء» وأنشئ مفتاحًا جديدًا.

الاستدعاء الأول

أرسل المفتاح مع كل طلب في الترويسة Authorization. ويخبرك /v1/me بالحساب الذي ينتمي إليه المفتاح وبالصلاحيات التي يحملها.

curl https://api.kenjtec.com/v1/me \
  -H "Authorization: Bearer kt_api_…"

{
  "id": 1042,
  "object": "account",
  "email": "ana@deine-firma.com",
  "handle": "cafe-lumen",
  "address": "https://cafe-lumen.kenjtec.ai",
  "key": { "name": "Lager-Abgleich", "scopes": ["orders:read"] }
}

المسارات

هذه هي المسارات المتاحة. ويوجد الوصف الكامل القابل للقراءة آليًا في https://api.kenjtec.com/openapi.json — ويمكن منه إنشاء مكتبات برمجية لأي لغة برمجة.

GET    /v1/me
GET    /v1/forms
GET    /v1/forms/{id}
GET    /v1/forms/{id}/responses
GET    /v1/forms/{id}/responses/{id}
GET    /v1/shops
GET    /v1/orders          ?shop_id=  &status=  &payment_status=
GET    /v1/orders/{id}
GET    /v1/webhooks
POST   /v1/webhooks
DELETE /v1/webhooks/{id}

GET    /v1/sites
GET    /v1/sites/{id}
POST   /v1/sites
POST   /v1/sites/{id}/edit
POST   /v1/sites/{id}/publish
POST   /v1/sites/{id}/unpublish
GET    /v1/domains
GET    /v1/domains/{id}/dns_records
POST   /v1/domains/{id}/dns_records
PATCH  /v1/domains/{id}/dns_records/{id}
DELETE /v1/domains/{id}/dns_records/{id}
GET    /v1/customers
POST   /v1/customers
GET    /v1/invoices        ?kind=invoice|quote
GET    /v1/invoices/{id}
POST   /v1/invoices
POST   /v1/invoices/{id}/issue
POST   /v1/invoices/{id}/cancel
GET    /v1/media
POST   /v1/media/uploads
POST   /v1/media/{id}/confirm
GET    /v1/brands
GET    /v1/brands/{id}

تظهر الملفات الواردة في ردود النماذج باسمها، لا بعنوان. ويمكنك تنزيلها في FormBuilder.

القوائم والمبالغ والأوقات

تأتي القوائم مرتّبة من الأحدث إلى الأقدم، بحد أقصى 100 عنصر في كل استدعاء (limit، والقيمة الافتراضية 25). وللحصول على الصفحة التالية، أرسل معرّف العنصر الأخير بوصفه starting_after؛ ويخبرك has_more بما إذا كان هناك المزيد.

المبالغ أعداد صحيحة بأصغر وحدة للعملة — السنت لليورو، والين الكامل للين. والأوقات بتوقيت UTC وفق ISO 8601.

curl "https://api.kenjtec.com/v1/orders?payment_status=paid&limit=50" \
  -H "Authorization: Bearer kt_api_…"

الأخطاء والحدود

لكل خطأ الشكل نفسه: كائن error يحتوي على type وmessage. يعني 401: المفتاح مفقود أو خاطئ أو ملغى. ويعني 403: المفتاح يفتقر إلى صلاحية — أو لم يعد لدى الحساب باقة مدفوعة (type plan_required). ويعني 404: العنصر غير موجود، أو لا ينتمي إلى حسابك.

يُسمح لكل مفتاح بـ120 طلبًا في الدقيقة. وعند تجاوز ذلك تردّ واجهة البرمجة بالرمز 429 وتذكر في Retry-After عدد الثواني المتبقية حتى المحاولة التالية.

{
  "error": {
    "type": "permission_error",
    "message": "This API key lacks the scope 'orders:read'."
  }
}

لا تقبل واجهة البرمجة إلا المفاتيح، ولا تقبل أبدًا تسجيل دخولك في المتصفح. مكان المفتاح هو خادمك — وليس أبدًا موقعًا إلكترونيًا أو تطبيقًا يقوم الآخرون بتنزيله.