تحصيل الرصيد الائتماني من الحسابات

نظرة عامة

ليس متاحًا بعد. سيتم إطلاق تحصيل الرصيد الائتماني للتطبيقات رسميًا في أكتوبر. نُشرت هذه الصفحة مبكرًا للشركاء الذين يرغبون في تجربتها.

تُحصّل التطبيقات التي تتطلب أموالًا لتشغيلها — مثل مسجل مكالمات يدفع لمزوّد تفريغ صوتي، أو تطبيق إثراء يدفع مقابل كل تطابق — من مساحة العمل بالـ credits. يُعلن عن كل ما يُصدر التطبيق فواتير مقابله في كتلة billing واحدة ضمن إعدادات تطبيقك:

src/application-config.ts

import { defineApplication } from 'twenty-sdk/define';

export default defineApplication({
  // ...identity, variables...
  billing: {
    description: '$20/month + $0.02 per minute recorded',
    recurring: {
      platformFee: {
        period: 'MONTH',
        amountMicroCredits: 20_000_000,
        label: 'Platform fee',
      },
    },
    operations: {
      recordMeeting: {
        operationType: 'CALL_RECORDING',
        label: 'Meeting recording',
      },
    },
  },
});

recurring — رسوم ثابتة ورسوم لكل عضو تتولاها المنصة نيابةً عنك، مرة واحدة في كل فترة فوترة.
operations — ما تفرض رسومًا مقابله أثناء استخدامه، من دالة منطقية.
description — سطر ودود واحد يظهر للمشترين في إدراجك في السوق.

تُسجَّل العناصر الثلاثة جميعها في مقياس الرصيد نفسه وفي التفصيل نفسه ضمن Settings > Usage، لذلك ترى مساحة العمل فاتورة واحدة.

الرسوم المتكررة

الرسم المتكرر هو رسم اشتراك: مبلغ شهري ثابت، أو مبلغ لكل عضو في مساحة العمل، أو كلاهما. تُعلن عن المبلغ وتتولى المنصة تحصيله. لا يستدعي تطبيقك chargeCredits لهذه الرسوم مطلقًا.

src/application-config.ts

billing: {
  recurring: {
    platformFee: {
      period: 'MONTH',
      amountMicroCredits: 20_000_000,
      label: 'Platform fee',
    },
    seat: {
      period: 'MONTH',
      amountMicroCredits: 5_000_000,
      per: 'WORKSPACE_MEMBER',
      label: 'Per member',
    },
  },
},

الحقل	الوصف
`الفترة`	`MONTH` — الفترة الوحيدة المتاحة حاليًا
`amountMicroCredits`	المبلغ بالاعتمادات المصغّرة (1 USD = 1,000,000)، وهو عدد صحيح موجب يصل إلى 100,000,000 ($100). بالنسبة إلى رسم `WORKSPACE_MEMBER`، يكون هذا هو السعر لكل عضو، وليس الإجمالي
`per`	احذفه للرسم الثابت. يضرب `WORKSPACE_MEMBER` المبلغ في عدد الأعضاء في مساحة العمل عند تحصيل رسوم الفترة
`label`	ما يقرؤه المشرفون لذلك البند في Usage

كيفية تحصيلها:

مرة واحدة لكل فترة فوترة لمساحة العمل، عند حد الفترة الخاص بمساحة العمل، وليس في أول الشهر.
لا تُحتسب بالتناسب. يُحصَّل من تطبيق يُثبَّت في منتصف الفترة المبلغ الكامل لتلك الفترة؛ وإلغاء التثبيت يوقف الفترة التالية، ولا يردّ مبلغ الفترة الحالية.
تحتسب الرسوم لكل عضو جميع أعضاء مساحة العمل في لحظة تحصيل الرسم، لذا تدفع مساحة العمل التي يزداد عدد أعضائها في منتصف الفترة العدد الأعلى بدءًا من الفترة التالية.
للاشتراكات الشهرية فقط. لا تُحصَّل من مساحة عمل على خطة سنوية رسوم MONTH، بدلًا من تحصيلها مرة واحدة عن السنة كاملة.
محدودة. يُرفض ولا يُنشأ سعر مُعلَن يتجاوز $100، أو رسم لكل عضو يؤدي ضرب سعره في عدد الأعضاء إلى تجاوز $1,000 للفترة. تتولى المنصة نفسها تحصيل هذه الرسوم، ولذلك لن تسجل عملية خصم لا يمكنها تبريرها.

العمليات القابلة للفوترة

العملية هي ما يفرض تطبيقك رسومًا مقابله أثناء عمله. يربط كل إدخال اسم عملية تختاره بفئة الفوترة التي تقيسها المنصة، بالإضافة إلى التسمية التي تظهر لمشرفي مساحة العمل في Settings > Usage.

src/application-config.ts

billing: {
  operations: {
    recordMeeting: {
      operationType: 'CALL_RECORDING',
      label: 'Meeting recording',
    },
    summarizeMeeting: {
      operationType: 'AI_CHAT_TOKEN',
      label: 'Meeting summary',
    },
  },
},

يجب أن تكون operationType إحدى فئات الفوترة في المنصة: AI_CHAT_TOKEN أو AI_WORKFLOW_TOKEN أو WORKFLOW_EXECUTION أو CODE_EXECUTION أو WEB_SEARCH أو CALL_RECORDING أو EMAIL_SEND. وهي تحدد كيفية قياس الإنفاق ووحدة العد المطبقة (الرموز المميزة أو الاستدعاءات أو الدقائق) — وليست ما يقرؤه المشرفون. إنما label هي ذلك. يرفض الإصدار قيمة operationType غير معروفة، وقيمة label فارغة، واسمًا مستخدمًا لكل من رسم متكرر وعملية.

التحصيل

حصّل مقابل عملية مُعلن عنها بالاسم:

import { chargeCredits } from 'twenty-sdk/billing';

await chargeCredits({
  operation: 'recordMeeting',
  creditsUsedMicro: 250_000,
  quantity: 12,
});

creditsUsedMicro هو المبلغ بالاعتمادات الصغيرة (1 USD = 1,000,000). quantity هي عدد الوحدات التي يغطيها الرسم، وفق الوحدة التي تشير إليها فئة العملية — دقائق لـ CALL_RECORDING، واستدعاءات لـ CODE_EXECUTION، وهكذا. الملاحظات:

يتيح إعلان العمليات لـ Usage تقسيم إنفاق تطبيقك بحسب ما فُرضت رسوم مقابله. يستمر الإبلاغ عن التطبيق الذي لا يعلن شيئًا، كشريحة واحدة تحت اسم العرض الخاص به.
يُرفض تحصيل رسوم لعملية لا يعلن عنها ملف البيان الخاص بك. أضفها إلى billing.operations ثم قم بالمزامنة.
يمكن لعدة عمليات مشاركة operationType واحد. تظهر عمليتا إثراء كلتاهما مقاستين كـ CODE_EXECUTION على شكل شريحتين منفصلتين بتسميتين.
من دون operation، سمِّ فئة الفوترة مباشرةً باستخدام operationType، وبشكل اختياري باستخدام resourceContext حرّ التنسيق. الصيغتان متنافيتان: تحمل operation التسمية، بينما لا تحملها operationType.
لا يتسبب التحصيل مطلقًا في فشل دالتك. يُسجَّل خطأ الفوترة ويُتجاهل، ولا ينتج عن الاستدعاء أي إجراء خارج وقت تشغيل الدالة المنطقية كي لا تتعطل عمليات التشغيل والاختبارات المحلية.

التحقق قبل الإنفاق

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

import { getCreditAvailability } from 'twenty-sdk/billing';

const { hasAvailableCredits } = await getCreditAvailability();

if (!hasAvailableCredits) {
  return;
}

عندما لا تتوفر الاعتمادات، تأتي معه قيمة reason: إما no-credits أو no-subscription أو workspace-suspended. يغطي no-credits أيضًا حد كل الاستخدام الذي عيّنه مسؤول لتطبيقك ضمن الإعدادات → الفوترة → الحدود: قد تظل مساحة العمل تحتوي على أرصدة، لكن قد لا يتمكن تطبيقك من إنفاقها. الملاحظات:

يوضح ما إذا كان يمكن لتطبيقك الإنفاق في مساحة العمل هذه، وليس مقدار الرصيد المتبقي فيها. لا يرى تطبيقك الرصيد أو الخطة أو حدودها.
يفشل بشكل مفتوح. إذا انتهت مهلة التحقق أو تعذر الوصول إلى الخادم، فإنه يُبلغ بأن الاعتمادات متاحة، حتى لا يوقف خلل في البنية التحتية تطبيقك. تعامل معه كإشارة تستحق المراعاة، لا كقرار تفويض.
إنها لقطة آنية. قد تنفد الأرصدة بين التحقق والعمل — بما في ذلك بسبب رسومك الخاصة، إذ إن كل رسم تجريه يحرّك العداد نفسه الذي يقرأه هذا.
لا تُطبَّق البوابة بشكل موحد. ليست كل مسارات البريد الإلكتروني الصادر مقيّدة بالأرصدة، لذا فإن false هنا يخبرك بأنه لا ينبغي لتطبيقك الإنفاق الآن بدلًا من التنبؤ بدقة بالاستدعاءات التي ستفشل.

إخبار الأشخاص بالتكلفة

يخبر إعلان الرسوم المنصة بكيفية قياس تطبيقك؛ ولا يخبر المشتري بما سيدفعه. عيّن billing.description لذلك — سطر واحد قصير وودود يظهر في قائمة متجرك قبل أن يثبّت أي شخص التطبيق.

src/application-config.ts

billing: {
  description: '$0.02 per minute recorded, billed to your Twenty credits',
},

إنه نص حر عن قصد: فالأسعار الحقيقية تتضمن مستويات وحدودًا دنيا وأسعارًا لكل وحدة لا يمكن لرقم واحد التعبير عنها. اجعله في سطر واحد. التطبيق الذي يعلن عن operations أو recurring يطلب أيضاً موافقة المسؤول الذي يثبّته: تعرض شاشة التثبيت “خصم أرصدة من مساحة عملك”، وتعرض صفحة التطبيق “يخصم أرصدة”، مع ظهور description عند التمرير فوقه.

الإسناد

يُنسب الإنفاق إلى من شغّل عملية التشغيل، لذا يظهر في Usage by User. عمليات التشغيل التي لا يقف وراءها أحد (مثل webhook أو cron) ليس لها شخص مشغِّل — مرّر userWorkspaceId إذا كان تطبيقك يعرف إلى من ينتمي الإنفاق. يجب أن ينتمي إلى مساحة العمل التي ثُبّت فيها التطبيق، ويُتجاهل عندما يكون لعملية التشغيل مستخدم مشغِّل.

await chargeCredits({
  operation: 'recordMeeting',
  creditsUsedMicro: 250_000,
  quantity: 12,
  userWorkspaceId: ownerUserWorkspaceId,
});

مكان الحصول على واحد: context.userWorkspaceId في عملية تشغيل مُشغَّلة، أو listConnections()، التي تعيد userWorkspaceId لمالك كل اتصال. لا يوجد شخص مشغِّل للرسوم المتكررة، لذا يُبلّغ عنها مقابل التطبيق فقط، وليس مقابل عضو مطلقًا.

المطورون

التطبيقات

واجهة برمجة التطبيقات

الاستضافة الذاتية

المساهمة

مكتبة واجهة المستخدم

تحصيل الرصيد الائتماني من الحسابات

نظرة عامة

الرسوم المتكررة

العمليات القابلة للفوترة

التحصيل

التحقق قبل الإنفاق

إخبار الأشخاص بالتكلفة

الإسناد

​نظرة عامة

​الرسوم المتكررة

​العمليات القابلة للفوترة

​التحصيل

​التحقق قبل الإنفاق

​إخبار الأشخاص بالتكلفة

​الإسناد

نظرة عامة

الرسوم المتكررة

العمليات القابلة للفوترة

التحصيل

التحقق قبل الإنفاق

إخبار الأشخاص بالتكلفة

الإسناد