الأدلة

ربط نظام طرف ثالث

لشركات البرمجيات — أنظمة تخطيط الموارد ونقاط البيع والتجارة الإلكترونية والمحاسبة — التي تربط حسابات عملائها في KWN.

تربط شركة KWN منتجك بالطريقة نفسها التي تربط بها أنظمتها: بمفتاح تنشئه وتسلّمه لك. لا تحتاج إلى حساب شريك: مفتاح لكل شركة من عملائك، يُستخدم من خوادمك.

ربط عميل

1. في منتجك، اطلب من العميل مفتاحًا برمجيًا من KWN، وأخبره بالنطاقات التي تحتاجها — أقل ما يؤدي المهمة (النطاقات).
2. ينشئه العميل من الإعدادات ← التكاملات ← مفاتيح الواجهة البرمجية باسم منتجك، ثم يلصقه في منتجك.
3. احفظه مشفّرًا، مرتبطًا بذلك العميل، على خادمك فقط.
4. أرسل GET /me فورًا: طابِق الرقم الضريبي للشركة واسمها مع سجلاتك، وتحقّق من أن المفتاح يحمل الصلاحيات التي تحتاجها (وeInvoicing.available إن كنت ترسل الفواتير).

تشغيل الربط

• ضع معرّفاتك في externalId على كل سجل تنشئه، وابحث عن السجلات بها — لا بالاسم أبدًا.
• أرسل Idempotency-Key مع كل إنشاء وأعد استخدامه عند إعادة المحاولة (منع التكرار).
• زامن عبر updatedSince بجدول زمني (الصفحات والمزامنة)؛ وابقَ ضمن حد المعدل لكل شركة، الذي تتقاسمه كل مفاتيحها.
• اعتمد على code في الرفض، لا على النص (الأخطاء).

عندما يتوقف المفتاح

الشركة تملك المفتاح ويمكنها إلغاؤه في أي وقت — وتتوقف كل المفاتيح ما دام حسابها في KWN غير نشط. تعني 401 API_KEY_INVALID أو MERCHANT_INACTIVE أن تتوقف عن استخدامه وتطلب من العميل إعادة الربط؛ لا تُعد المحاولة في حلقة. وتعني 403 أن المفتاح ينقصه نطاق أو أن خطة الشركة ينقصها تطبيق: أخبر العميل بأيهما.

ما لا يستطيعه الربط أبدًا

• الوصول إلى شركة أخرى. المفتاح مرتبط بشركة واحدة؛ وسجل شركة أخرى يجيب 404.
• إدارة المستخدمين أو المفاتيح أو الفوترة أو الإعدادات، أو رؤية البيانات المصرفية والملاحظات الداخلية.
• فعل ما يتجاوز صلاحيات الشخص الذي أنشأ المفتاح.

كل تغيير يجريه المفتاح يُسجَّل باسمه في سجل تدقيق الشركة، وترى الشركة آخر استخدام لكل مفتاح. سمِّ منتجك بوضوح ليعرفوه.