اربط برامجك الخاصة بمفاتيح API

تتيح واجهة API العامة لبرامجك الخاصة، أو لبرامج المطوّر الذي تتعامل معه، قراءة سجلاتك في Kluvan والكتابة فيها: المنتجات، والعملاء، والمخزون، والتقارير، ومستندات الحسابات، وموظفي الموارد البشرية، وإدارة العملاء (CRM)، والاشتراكات، والتطبيقات التي لديك. أنت تتحكم في كل مفتاح: ما يمكنه فعله، ولأي مدة، ولأي فرع.

قبل أن تبدأ

• المالك وحده يستطيع إنشاء المفاتيح وإلغاءها.
• لا يفتح المفتاح أبدًا تطبيقًا لا تملكه منشأتك، وتبقى كل قواعد باقتك وتطبيقاتك وفروعك سارية.

الخطوات

1. افتح الإعدادات ← وصول المطوّرين.
2. تحت مفتاح جديد، اكتب اسمًا تتعرف عليه، مثل «Warehouse scanner».
3. اضبط مدة الصلاحية بالأيام (1–365). القيمة الافتراضية 90.
4. تحت الفرع، أبقِ على كل الفروع أو اختر فرعًا واحدًا.
5. تحت يمكنه رؤية، حدّد كل نطاق يحتاجه المفتاح. يذكر كل نطاق قراءة أو كتابة، مثل المنتجات · قراءة.
6. حدّد الجملة التي تفيد بأنك تأذن بالوصول المختار.
7. اضغط إنشاء المفتاح.
8. انسخ المفتاح الآن. لا يُعرض إلا هذه المرة.
9. أعطِ المفتاح لبرنامجك. يرسله البرنامج في الترويسة Authorization: Bearer.

استدعاء الواجهة

• العنوان هو https://api.kluvan.com/v1/public-api. يعرض دليل المطوّرين (/developers) أمثلة وكل عملية مع النطاق الذي تحتاجه. ويُنزِّل OpenAPI 3.1 العقد الكامل، مع حقول الطلبات.
• كل عملية كتابة تحتاج إلى Idempotency-Key: قيمة UUID جديدة لكل تغيير. إذا ضاعت الإجابة، فأرسل الطلب نفسه بالقيمة نفسها مرة أخرى، لمدة تصل إلى 7 أيام؛ ولن يُطبَّق مرتين. أما القيمة نفسها مع طلب متغيّر فتُرفض.
• التغيير على سجل موجود يرسل أيضًا الإصدار الحالي للسجل (v)، فلا تكتب نسخة أقدم أبدًا فوق نسخة أحدث.
• المبالغ بأصغر وحدة في العملة (150.00 تساوي 15000).
• قوائم سجلات التطبيقات تُرجع حتى 50 سجلًا وقيمة next؛ مرّرها في after للحصول على الصفحة التالية.
• حتى 120 طلبًا في الدقيقة لكل مفتاح. بعد ذلك تكون الإجابة 429 مع Retry-After. كل خطأ يحمل كودًا (راجع دليل الأخطاء).

من المفيد أن تعرف

• نطاقات الكتابة تغيّر سجلات حقيقية وقد تشغّل إجراءات التطبيق، بآثارها على المخزون والمحاسبة. لا تعطِ المفتاح إلا النطاقات التي يحتاجها.
• مفاتيح الفروع تقرأ سجلات الفرع فقط. عمليات الكتالوج والعملاء وإدارة العملاء (CRM) والموارد البشرية والاشتراكات تحتاج إلى مفتاح لكل الفروع.
• لا يحتفظ Kluvan إلا ببصمة (hash) لكل مفتاح. فقدت مفتاحًا؟ ألغِه وأنشئ مفتاحًا جديدًا.
• إلغاء يوقف المفتاح فورًا. ويتوقف المفتاح أيضًا في آخر يوم له. يمكنك الاحتفاظ بما يصل إلى 20 مفتاحًا.
• يعرض نشاط API كل طلب: الوقت، والعملية، والمفتاح، والحالة. لا تُسجَّل أبدًا محتويات الطلبات ولا المفاتيح.
• لا توفر الواجهة الفوترة ولا تسجيل الدخول ولا تحصيل المدفوعات ولا webhooks: لا توجد إشعارات صادرة، لذلك يقرأ برنامجك القوائم التي يحتاجها.
• لا يمكن لجلسة متصفح مسجَّلة الدخول أن تستدعي هذه الواجهة، ومفاتيح تطبيقات المساعد منفصلة: راجع اربط تطبيق مساعد.