الربط لمنصات SaaS متعددة المستأجرين

مفتاح واحد لمنشأة واحدة

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

الحالة (أ): منصتك تصدر فواتير لعملائها

أنت البائع. لمنشأتك حساب في وندرفاتورة ومفتاح API، وكل عميل لديك مشترٍ في فواتيرك.

1. أنشئ مفتاحًا لمنشأتك بصلاحيات invoices:write وinvoices:issue وinvoices:read.
2. عند نجاح الدفع أنشئ الفاتورة مع external_reference يساوي معرّف الدفعة أو فترة الفوترة.
3. احفظ customer.id المُعاد مع سجل العميل لديك وأعد استخدامه في المرة التالية.
4. اقرأ الفاتورة حتى يصبح zatca.deliverable مساويًا true ثم أرسل public_url مع إيصالك.

صفحة واجهة فوترة الاشتراكات تشرح ذلك بالتفصيل. ويمكن لتطبيق خادم سجّلته في «تطبيقاتي» فعل الشيء نفسه ببيانات اعتماد العميل في OAuth: رمزه يعمل لمنشأتك أنت فقط.

الحالة (ب): عملاؤك يصدرون فواتير لمشتريهم عبر منتجك

كل عميل لديك بائع ويحتاج منشأته الخاصة في وندرفاتورة على باقة تشمل ربط التطبيقات (الباقات التي تشمل الوصول إلى الواجهة البرمجية). يربط كل عميل منشأته بتطبيقك مرة واحدة عبر OAuth:

1. سجّل تطبيقك من الإعدادات ← المطورون ← تطبيقاتي، مع عنوان إعادة التوجيه الدقيق والصلاحيات التي يحتاجها منتجك.
2. يضغط عميلك «ربط وندرفاتورة» في منتجك، فترسله إلى /oauth/authorize مع PKCE وstate.
3. يسجّل الدخول ويختار منشأته ويوافق. يصلك رمز (code) على عنوان إعادة التوجيه، فتستبدله من /oauth/token برمز وصول ورمز تحديث، وتحفظ رمز التحديث مشفرًا مقرونًا بذلك العميل.
4. استجابة الرمز تسمّي المنشأة (company_id)، وكل استجابة من الواجهة تكررها في meta.company_id. رمزك لعميل لا يصل أبدًا إلى بيانات عميل آخر.
5. يستطيع عميلك فصل تطبيقك في أي وقت من لوحة تحكمه فتتوقف رموزه فورًا. عالج 401 invalid_token بأن تطلب منه الربط من جديد.

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

ومن دون OAuth يعمل الأمر نفسه بـ مفتاح لكل منشأة عميل:

1. ينشئ عميلك مفتاحًا في حسابه هو في وندرفاتورة، بالصلاحيات التي يحتاجها منتجك فقط، ويدخله في منتجك.
2. احفظ كل مفتاح مشفرًا ومرتبطًا بحساب ذلك العميل. لا تشارك مفتاحًا بين منشأتين أبدًا.
3. استدعِ الواجهة بمفتاح المنشأة التي تنتمي إليها الفاتورة، وتأكد من الربط مرة واحدة بـ GET /ping الذي يعيد اسم المنشأة.
4. يستطيع عميلك إلغاء المفتاح من حسابه في أي وقت. عالج 401 بأن تطلب منه إعادة الربط.

العزل

• المفتاح يقرأ ويكتب بيانات منشأته فقط. معرّف الفاتورة أو العميل من منشأة أخرى يُعامل تمامًا كمعرّف غير موجود.
• معرّفات المنتجات ونسب الضريبة تُطابق مع منشأة المفتاح.
• يُسجل كل طلب مقرونًا بالمفتاح الذي أرسله.