إعداد Uyumsoft للفاتورة الإلكترونية

يتواصل Convord مع Uyumsoft عبر طلبات JSON إلى BasicIntegrationApi لـ e-Invoice / e-Archive، واختياريًا DespatchApi لـ e-Waybill. المصادقة تطابق العينات الرسمية: كل طلب يتضمن userInfo مع Username وPassword. لا يوجد تدفق OAuth أو مفتاح API منفصل؛ ما تدخله في اللوحة هو هذا الزوج بالضبط.

الإعداد في لوحة التحكم

1. فعّل الفوترة ضمن الإعدادات → التكاملات.
2. اختر Uyumsoft كمزود فاتورة.
3. املأ الرقم الضريبي (VKN/TCKN) ومكتب الضرائب للشركة؛ يجب أن يطابقا حساب Uyumsoft.
4. أدخل اسم مستخدم التكامل وكلمة مرور التكامل من Uyumsoft واحفظ.
5. تأكد أن العملاء الذين تُصدر لهم فواتير لديهم VKN (10 أرقام) أو TCKN (11 رقمًا) صالح؛ وإلا يُمنع الإرسال برسالة واضحة.

مفتاح API مقابل اسم المستخدم / كلمة المرور

يستخدم التكامل كائن REST userInfo. الحقلان في Convord يطابقان Username وPassword. لا يوجد Bearer token إضافي أو حقل secret-key.

اختياريًا عيّن UYUMSOFT_USERNAME / UYUMSOFT_PASSWORD في .env على الخادم كاحتياطي على مستوى المستأجر؛ قيم الشركة في اللوحة لها الأولوية عند وجودها.

إعدادات الخادم (.env)

يجب على الاستضافة / DevOps التحقق من:

• UYUMSOFT_BASE_URL — مثل الإنتاج https://efatura.uyumsoft.com.tr/api أو الاختبار https://efatura-test.uyumsoft.com.tr/api (مع مسارات الإعداد في config).
• عناوين URL كاملة اختيارية: UYUMSOFT_INVOICE_API_URL، UYUMSOFT_DESPATCH_API_URL.
• اختبار smoke بعد النشر: php artisan uyumsoft:test

الرقم الضريبي للعميل

يلزم رقم ضريبي صالح للمشتري لإرسال Uyumsoft. Convord يتحقق قبل الإنشاء/الإرسال ويعرض خطأ صريحًا؛ حدّث سجل العميل وأعد المحاولة.

إذن التسليم الإلكتروني (DespatchApi)

وضع PDF/XML محلي لإذن التسليم لا يتطلب أعلام خادم إضافية. e-waybill Uyumsoft / GİB الحقيقي يحتاج:

• EINVOICE_PROVIDER=uyumsoft
• UYUMSOFT_DISPATCH_ENABLED=true — VKN/TCKN للمشتري مطلوب أيضًا في هذا الوضع.

حساب Uyumsoft وسلسلة الفواتير

حتى مع توصيل API صحيح، يجب أن يكون لدى مشروع Uyumsoft <strong>سلسلة/بادئة</strong> الفاتورة وإعدادات الحساب مكتملة. وإلا قد ترى أخطاء مثل سلسلة مفقودة. تواصل مع دعم Uyumsoft لإعداد الحساب.

بيئة الاختبار

استخدم توثيق Uyumsoft لعناوين URL وبيانات اعتماد العينة. أمر Artisan uyumsoft:test يختبر اتصال BasicIntegrationApi.

مزيد من المعلومات

لسياق تكامل أوسع، راجع دليل التكامل.