الموصّلات

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

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

كيف تعمل الموصّلات

التدفق هو نفسه لكل مزود:

1. الإضافة — افتح مشروعًا ← علامة التبويب الموصّلات (أو المالية ← مصادر البيانات)، انقر ربط مصدر، واختر مزودًا.
2. التفويض — إما OAuth بنقرة واحدة (توافق على وصول القراءة على شاشة المزود نفسه) أو تلصق مفتاح / رمز API تنشئه في لوحة تحكم المزود. تعرض اللوحة الخطوات الدقيقة وترتبط مباشرة بالصفحة الصحيحة.
3. التحقق — يفحص Kordox بيانات الاعتماد فورًا ويخبرك إن كان هناك نطاق أو إذن ناقص.
4. المزامنة الأولية — يعمل السحب الأول تلقائيًا ويملأ السجل الحديث.
5. البقاء محدّثًا — يعيد Kordox المزامنة وفق جدول (كل ~6 ساعات)؛ ويمكنك أيضًا المزامنة يدويًا في أي وقت.
6. الإسناد — تُوجَّه المعاملات المتزامَنة إلى المشروع الذي تنتمي إليه (انظر إسناد المال إلى المشاريع).

مقصور على مشروع

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

الأمان — كيف تُعالَج بيانات الاعتماد

• للقراءة فقط بحكم التصميم. يطلب كل موصّل نطاقات قراءة فقط (الفوترة، الرسوم، الطلبات، تقارير التكلفة). لا شيء يحتفظ به Kordox يمكنه الإنفاق أو رد الأموال أو إعادة تهيئة حسابك.
• مشفّر أثناء التخزين. تُشفَّر مفاتيح API ورموز OAuth قبل التخزين ولا تُعاد إلى المتصفح بعد حفظها.
• أقل امتياز ممكن. حيث يدعم المزود بيانات اعتماد مقيّدة النطاق (مفاتيح Stripe المقيّدة، رموز Cloudflare المقيّدة، سياسات AWS IAM)، يطلب الدليل أضيق إذن يؤدي الغرض — مدرَج لكل موصّل أدناه.
• الإلغاء في أي وقت. يزيل الفصل وصول Kordox ويوقف المزامنة. تبقى البيانات المتزامَنة بالفعل في سجلك.

الموصّلات المتاحة

الفئة	المزودون	الربط عبر
الإيرادات	Stripe، Shopify، PayPal، Square	OAuth ‏(Stripe/Shopify) أو مفتاح API
النقد / البنك	Plaid (الأرصدة تغذّي المدرج المالي)	مفتاح API + رمز Link
تكلفة البنية التحتية	Cloudflare، AWS Billing، GCP Billing	مفتاح API أو OAuth ‏(GCP)
الإنفاق الإعلاني	Meta Ads، Google Ads	OAuth
الذكاء الاصطناعي والتوكنز	Anthropic ‏(Claude)، OpenAI	مفتاح Admin API
البريد الإلكتروني	إعادة توجيه/BCC + رد من سجل	ليس موصّلًا — انظر البريد الإلكتروني

المزامنة والحالة والحداثة

• الجدول. يعيد Kordox مزامنة الموصّلات النشطة تلقائيًا كل ~6 ساعات.
• المزامنة اليدوية. شغّل تحديثًا في أي وقت من صف الموصّل (أو مزامنة الكل لفئة). المزامنة اليدوية تشغّل السحب نفسه في وقت أبكر فحسب.
• الحالة. يعرض كل موصّل وقت آخر مزامنة، والمبلغ وعدد المعاملات خلال آخر 30 يومًا، والنسبة المئوية المسندة.
• يتطلب الانتباه. يظهر الموصّل الفاشل في الأعلى مع الخطأ الدقيق واختصار تحقّق / مزامنة / تهيئة. تُعاد أخطاء المصدر العابرة تلقائيًا وتتعافى ذاتيًا في المزامنة المجدولة التالية.
• السجل. يعرض زر السجل عمليات المزامنة الأخيرة ونتائجها.

ما يحتاجه كل موصّل

Stripe — المدفوعات

يزامن المدفوعات والتحويلات والمبالغ المستردة والرسوم إلى الربح والخسارة لكل مشروع. للقراءة فقط.

• الأذونات: مفتاح API مقيّد بصلاحية قراءة على Balance وCharges وRefunds وSubscriptions. (أضف كتابة على Checkout Sessions فقط إذا فعّلت إصدار فواتير العملاء — وهو مُعطَّل افتراضيًا وغير مطلوب للمزامنة.)
• الخطوات: Stripe ← Developers ← API keys ← أنشئ مفتاحًا مقيّدًا بالنطاقات أعلاه ← الصقه ← إضافة حساب. يستقر المال في حساب Stripe الخاص بك؛ ولا يمكن للمفتاح نقله.

Shopify — الطلبات

يزامن طلبات متجرك والمبالغ المستردة كإيرادات. للقراءة فقط.

• الأذونات (OAuth): read_orders، read_products.
• الخطوات: أدخل نطاق mystore.myshopify.com ← الربط عبر Shopify ← وافق على وصول القراءة ← يُعاد توجيهك إلى هنا وتُزامَن الطلبات كإيرادات.
• ستحتاج: حساب موظف يملك صلاحية تثبيت التطبيقات.

PayPal — المدفوعات

يزامن معاملات PayPal كإيرادات.

• الأذونات: تطبيق REST من PayPal — معرّف العميل + السر الخاصان به (بحث المعاملات للقراءة فقط).
• الخطوات: developer.paypal.com ← Apps & Credentials ← افتح/أنشئ تطبيق REST ← انسخ Client ID + Secret ← الصق الاثنين ← اختر Live (أو Sandbox) ← احفظ.

Square — المدفوعات

يزامن مدفوعات Square والمبالغ المستردة كإيرادات.

• الأذونات: رمز وصول من Square ‏(PAYMENTS_READ).
• الخطوات: developer.squareup.com ← تطبيقك ← Credentials ← انسخ رمز الوصول ← الصقه، وأضف اختياريًا Location ID لحصره بموقع واحد ← اختر البيئة ← احفظ.

Plaid — أرصدة البنوك

يربط أرصدة البنوك ليُحتسب المدرج المالي من النقد الفعلي.

• الأذونات: Client ID + Secret من Plaid ورمز item access token من Plaid Link (منتج Balance).
• الخطوات: انسخ Client ID + Secret من لوحة Plaid ← استخدم Plaid Link لربط البنك والحصول على رمز وصول ← الصق الثلاثة ← اختر البيئة (production/sandbox) ← احفظ.

Cloudflare — تكلفة البنية التحتية

يتابع استخدام Cloudflare وتكاليف الفوترة.

• الأذونات: رمز API مخصص بصلاحية واحدة — Account ← Billing ← Read، مقيّد بحسابك.
• الخطوات: اللوحة ← ملفي ← رموز API ← إنشاء رمز (قراءة الفوترة) ← انسخه ← الصقه، مع معرّف الحساب (الشريط الجانبي الأيمن في نظرة عامة لأي نطاق) ← احفظ. يتحقق Kordox فورًا.

AWS Billing — تكلفة البنية التحتية

يسحب تكلفة واستخدام AWS إلى الربح والخسارة للمشروع الصحيح.

• الأذونات: مستخدم/مفتاح IAM مسموح له باستدعاء ce:GetCostAndUsage ‏(AWS Cost Explorer). تغطيه سياسة AWSBillingReadOnlyAccess المُدارة.
• الخطوات: IAM ← أرفق السياسة لمستخدم ← أنشئ access key ← الصق access key ID + secret ← حدّد منطقة اختياريًا (الافتراضي us-east-1) ← احفظ.

GCP Billing — تكلفة البنية التحتية

يسحب إنفاق Google Cloud كي تقع تكاليف البنية التحتية في الربح والخسارة للمشروع الصحيح — لكل مشروع GCP وخدمة ويوم.

• الاتصال (بنقرة واحدة): اختر الاتصال بحساب Google الخاص بك وسجّل الدخول بالهوية المالكة لـ GCP لديك. يكتشف Kordox تلقائيًا حساب الفوترة وتصدير الفوترة إلى BigQuery — معظم الإعدادات لا تحتاج أي كتابة.
• الأذونات (OAuth): cloud-billing.readonly + bigquery.readonly.
• خطوة GCP اليدوية الوحيدة: تأتي بيانات التكلفة من تصدير BigQuery الخاص بـ Cloud Billing، والذي لا يمكن تفعيله إلا في وحدة التحكم — Billing ← Billing export ← Standard usage cost ← اختر مشروعًا ومجموعة بيانات. إن لم يكن مفعّلًا بعد، فإن قائمة فحص الموصّل تنقلك إلى هناك مباشرة. تصل أول البيانات بعد ~24 ساعة من التفعيل (بلا ملء بأثر رجعي).
• متقدم (بلا OAuth): الصق بدلًا من ذلك مفتاح JSON لحساب خدمة بصلاحية Billing Account Viewer + قراءة BigQuery — مفيد للحسابات الآلية.
• غيّرت شيئًا في GCP؟ استخدم إعادة الاكتشاف من Google على البطاقة لإعادة تشغيل الاكتشاف التلقائي واختيار حساب الفوترة الصحيح.

Meta Ads — الإنفاق الإعلاني

يستورد إنفاق إعلانات Meta ‏(Facebook/Instagram) كتكلفة لتكون الهوامش وCAC حقيقية.

• الأذونات (OAuth): ads_read.
• الخطوات: الربط عبر OAuth ← وافق على وصول القراءة ← اختر الحساب الإعلاني المراد مزامنته ← يُستورد الإنفاق كمصروفات.

Google Ads — الإنفاق الإعلاني

يستورد إنفاق Google Ads كتكلفة لهامش وCAC حقيقيين.

• الأذونات (OAuth): وصول القراءة إلى بيانات Google Ads؛ وستؤكّد معرّف العميل (customer ID).
• الخطوات: الربط عبر OAuth ← وافق على وصول القراءة ← اختر الحساب / أكّد معرّف العميل ← يُستورد الإنفاق كمصروفات.

Anthropic ‏(Claude) — الذكاء الاصطناعي والتوكنز

يتتبع إنفاق Claude API ومساحة العمل كتكاليف ذكاء اصطناعي، لكل مساحة عمل — ليكون حساب AI لكل مشروع حقيقيًا.

• الأذونات: دور مسؤول المؤسسة ومفتاح Admin API ‏(sk-ant-admin…). مفتاح API العادي لا يمكنه قراءة استخدام المؤسسة. يقرأ Kordox تقرير التكلفة اليومي فقط.
• الخطوات: console.anthropic.com ← الإعدادات ← مفاتيح Admin (وليس صفحة مفاتيح API العادية) ← أنشئ مفتاح Admin ← الصقه هنا.
• الإسناد: تُسنَد كل مساحة عمل في Claude إلى مشروع، تمامًا مثل مشاريع GCP.

OpenAI — الذكاء الاصطناعي والتوكنز

يتتبع إنفاق OpenAI API كتكاليف ذكاء اصطناعي، لكل مشروع.

• الأذونات: دور مالك/مسؤول في المؤسسة ومفتاح Admin API ‏(sk-admin…). يقرأ Kordox التكاليف اليومية فقط.
• الخطوات: platform.openai.com ← الإعدادات ← المؤسسة ← مفاتيح Admin ← أنشئ مفتاح مسؤول ← الصقه هنا.
• الإسناد: يُسنَد كل مشروع في OpenAI إلى مشروع.

إسناد المال إلى المشاريع

يوجّه Kordox كل معاملة متزامَنة إلى المشروع الذي تنتمي إليه، فيصبح الربح والخسارة لكل مشروع حقيقيًا بدلًا من "أيًّا كان الحساب الذي جاءت منه". كلتا الآليتين رجعيّتان — يعيد Kordox إسناد السجل القائم عند الحفظ وإعادة المزامنة.

تعيين المصدر — للمزودين ذوي الكيانات الفرعية النظيفة. تُعيَّن تكاليف GCP حسب مشروع السحابة، وCloudflare حسب الحساب، وClaude/OpenAI حسب مساحة العمل/المشروع. حرّره في المالية ← تكاليف السحابة ← الإسناد.

قواعد الإسناد — للمزودين بلا كيانات فرعية نظيفة (واصفات Stripe، مذكرات البنك). تقول القاعدة "الوصف يحتوي على X ← المشروع Y": أي معاملة يحتوي وصفها على ذلك النص (دون حساسية لحالة الأحرف) تقع على ذلك المشروع؛ وتفوز أول قاعدة مطابقة. حرّره في المالية ← مستكشف المال ← قواعد الإسناد، ثم احفظ وأعِد المزامنة.

مستكشف المال

يقسّم المالية ← مستكشف المال كل المال المتزامَن — الإيرادات، البنية التحتية، الإعلانات، الذكاء الاصطناعي، الرسوم — حسب الفئة أو المزود أو المصدر أو الخدمة أو المشروع أو النوع، عبر أي فترة. بدّل بين المال الداخل والمال الخارج والصافي، وصدّر العرض الحالي كمصنّف Excel أو تقرير PDF بعلامتك التجارية أو CSV.

استكشاف الأخطاء وإصلاحها

• "يتطلب الانتباه" مع خطأ مزامنة. افتح نص الخطأ — فهو يتضمن الآن حالة HTTP للمصدر. 401/403 يعني أن المفتاح/الرمز يفتقر إلى نطاق مطلوب (أعِد إنشاءه بالأذونات المدرجة أعلاه). تُعاد أخطاء 5xx العابرة وأخطاء حد المعدل تلقائيًا وتُحلّ في المزامنة المجدولة التالية.
• متصل لكن بلا بيانات. بعض المزودين متأخرون: يصل أول بيانات تصدير BigQuery في GCP بعد ~24 ساعة من تفعيله؛ وتتأخر تقارير تكلفة الذكاء الاصطناعي ~1–2 يوم. أمهله دورة، ثم زامِن.
• تكاليف على المشروع الخطأ. أعدّ الإسناد واحفظ وأعِد المزامنة — فهو يعيد إسناد السجل، وليس البيانات الجديدة فحسب.
• يفشل التحقق فورًا. بيانات الاعتماد خاطئة أو تفتقر إلى نطاق؛ وتسمّي اللوحة ما هو ناقص. أعِد إنشاء المفتاح والصقه مجددًا.