تكامل مع QuickBooks لا يمحو الحقول

يدخل تكامل QuickBooks Online الإنتاج. وبعد أسبوع يلاحظ أحد العملاء أن سجل مورّد فقد عنوان الفاتورة وشروط الدفع والرمز الضريبي. لم يحذفها أحد. غيّر شخص بريد المورّد من نموذج في تطبيقك.

هذا أول ما يجب معرفته عن هذه الواجهة، وهو الأمر الذي يصل أعمق ما يصل إلى الواجهة الأمامية.

التحديث استبدال

معظم الواجهات تعامل جسم الطلب كالحقول التي تريد تغييرها. أما QuickBooks Online فيعامله افتراضيًا كالكائن الذي تريد أن يصير إليه السجل. وما تتركه ليس باقيًا على حاله - بل يصير فارغًا.

والنموذج في تطبيق Next.js هو بالضبط ما يسقط في هذا. شاشة التحرير تعرف ثلاثة حقول لأن ثلاثة حقول هي المطلوب تغييرها. فتستقبل الـ Server Action ثلاثة حقول وترسل ثلاثة حقول. وصار في نظام المحاسبة مورّد بثلاثة حقول.

وهناك دفاعان، ويستحق الأمر كليهما. يمكن للطلب أن يعلن أنه تحديث جزئي، وهو معامل في النداء لا حيلة ذكية. ويمكن للمعالج أن يقرأ السجل الحالي ويطبّق التغيير عليه ويعيده كاملًا، فتكون الحمولة تامة بصرف النظر عن كيفية تأويل الواجهة لها.

الثاني يكلّف رحلة إضافية. لكنه يعني أيضًا أن السلوك لا يتوقف على تذكّر أحدهم لعلامة، وهذه مقايضة تستحق في كود يلمس دفاتر شخص ما.

النسخة تنتمي إلى النموذج

كل سجل في QuickBooks Online يحمل نسخة. والتحديث يجب أن يرسل النسخة التي بُني عليها، وإن تغيّر السجل بعد ذلك فالتحديث مرفوض.

هذا صحيح وهو السلوك المطلوب. وهو في الوقت نفسه شرط يقع على النموذج لا على عميل الواجهة، وهناك تخطئ الفرق.

تحمّل الصفحة سجلًا في النسخة 7 وترسم نموذجًا. يكتب الشخص أربع دقائق. وفي أثناء ذلك يحرّر أحد من المالية السجل نفسه في QuickBooks فيصير النسخة 8. يُرسل النموذج النسخة 7 فيُرفض.

الرد الخاطئ أن تُمسك ذلك وتجلب النسخة الحالية وتعيد الإرسال - لأن هذا يُسقط تغيير المالية في صمت. والرد الصحيح أن تخبر الشخص بما جرى وتُظهر له ما تغيّر. أي أن النسخة يجب أن تكون جزءًا من حالة النموذج، تُحمل عبر الـ Server Action، وأن يكون التعارض نتيجةً مرئية لا استثناءً في سجل.

وهو، لحسن الحظ، نمط التزامن المتفائل نفسه الذي يحتاجه أي نموذج متعدد المستخدمين. الواجهة المحاسبية تجعله إلزاميًا فقط.

أين يقع كل جزء من التكامل فعلًا

سؤال المعمار هو نفسه في أي تكامل محاسبي، والأجوبة تستحق التكرار هنا لأن QuickBooks يضيف تفصيلة.

نداء الرجوع للتصريح هو Route Handler. ومع رمز التصريح يعيد QuickBooks معرّف الشركة التي صُرّح لها، ويجب التقاط الاثنين في ذلك الطلب الواحد - فالرمز بلا قيمة إن لم تعرف لأي شركة ينتمي. ومعامل state يجب التحقق منه لا قراءته فقط، لأنه ما يمنع إلحاق تصريح شخص آخر بحساب مستخدمك.

وتذهب الرموز إلى جدول مفتاحه معرّف الشركة ذاك. لا على المستخدم، ولا في كوكي، ولا في شيء يمكن لمكوّن متصفح الوصول إليه. الشخص الواحد قد يصرّح لعدة شركات، فيكون الاتصال هو السجل والمستخدم إشارة فيه.

والقراءات والكتابات العادية تنتمي إلى Server Actions ومكوّنات الخادم، حيث توجد بيانات الاعتماد ولا يراها المتصفح أبدًا.

أما العمل الطويل فلا. الـ Server Action طلب له مهلة، والاستيراد الأولي وجولة التسوية وإعادة الاحتساب ليست طلبًا. تلك تذهب إلى طابور: تنشئ الـ Server Action سجل مهمة وتعود فورًا، وتُظهر الصفحة التقدّم. وهذا أشيع خطأ بنيوي في هذه التكاملات، وهو غير مرئي في التطوير حيث تحتوي شركة الاختبار إحدى عشرة فاتورة.

الـ Webhooks تذكر المعرّف ولا شيء غيره

يصل webhook من QuickBooks إلى Route Handler، موقّعًا، ويقول إن كيانًا من نوع ومعرّف معيّنين قد تغيّر. ولا يقول ما تغيّر ولا ما يحتويه السجل الآن.

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

وقد يصل الإشعار مرتين، وقد يصل بترتيب معاكس لتغييرٍ أجريته أنت. وكلاهما عادي. وكون المعالج آمنًا للتشغيل مرتين - وتجاهله إشعارًا عن نسخة يملكها بالفعل - هو الفرق بين مزامنة تتقارب وأخرى تتذبذب.

مطابقة العملاء هي المشروع

العمل التقني أعلاه أسبوعان. وبقية الوقت تذهب إلى مكان لا يشبه الهندسة.

يشترط QuickBooks أن يكون الاسم الظاهر للعميل فريدًا داخل الشركة، أي أن «Acme Ltd» في تطبيقك و«Acme Limited» في المحاسبة عميلان مختلفان ويبقيان كذلك حتى يقرر أحد أيهما أي. اضرب ذلك في ألفي سجل وعقد من الإدخال غير المتسق.

وتمرين المطابقة ذاك - أي جهة تملك الاسم، وما يحدث لأشباه المكرر، وأي حقل هو المفتاح - حديث مع فريق المالية لا تقدير هندسي. والفرق التي تعامله كمسألة استيراد بيانات تكتشفه ثلاثة أسابيع قبل الإطلاق.

متى لا يُبنى هذا

إن كان المطلوب أن تظهر الفواتير في QuickBooks ولا يرجع شيء، والحجم عشرات في الشهر، فموصّل جاهز يفعل ذلك بعد الظهر مقابل اشتراك. والتكامل في الاتجاهين يستحق عندما يكون التخطيط خاصًا بعملك، أو عندما يجعل الحجم التصحيح اليدوي مكلفًا، أو عندما يجب أن تكون البيانات في نظامك ليكون لها نفع.

ولا يستحق لتفادي رسم شهري صغير. الوقت يذهب إلى قواعد التسوية، وهي لا ترخص لأنك كتبت عميل الواجهة بنفسك.