> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> حدّد ما الذي تُصدر تطبيقك فواتير مقابله، واحصل على رصيد مساحة العمل من دالة منطقية.

## نظرة عامة

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

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

```ts src/application-config.ts theme={null}
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` لهذه الرسوم مطلقًا.

```ts src/application-config.ts theme={null}
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**.

```ts src/application-config.ts theme={null}
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` فارغة، واسمًا مستخدمًا لكل من رسم متكرر وعملية.

## التحصيل

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

```ts theme={null}
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` أي نموذج ولا يضيف أي رسوم للذكاء الاصطناعي من تلقاء نفسه، رغم أن الدالة التي تستدعيه تُرفَض مثل أي دالة أخرى؛ ويُحتسب رد العضو مثل أي دور في الدردشة. تُعد خطافات إلغاء التثبيت وقطع الاتصال استثناءً وتعمل دائمًا، لذا يظل من الممكن إزالة التطبيق بشكل سليم. قد يفشل التنفيذ الذي يتمكن من المرور رغم ذلك في مرحلة متأخرة، عند استدعاء للمنصة لم يكتبه، إذا نفدت اعتمادات مساحة العمل أثناء التشغيل.

اسأل أولًا:

```ts theme={null}
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` لذلك — سطر واحد قصير وودود يظهر في قائمة متجرك قبل أن يثبّت أي شخص التطبيق.

```ts src/application-config.ts theme={null}
billing: {
  description: '$0.02 per minute recorded, billed to your Twenty credits',
},
```

إنه نص حر عن قصد: فالأسعار الحقيقية تتضمن مستويات وحدودًا دنيا وأسعارًا لكل وحدة لا يمكن لرقم واحد التعبير عنها. اجعله في سطر واحد.

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

## الإسناد

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

```ts theme={null}
await chargeCredits({
  operation: 'recordMeeting',
  creditsUsedMicro: 250_000,
  quantity: 12,
  userWorkspaceId: ownerUserWorkspaceId,
});
```

مكان الحصول على واحد: `context.userWorkspaceId` في عملية تشغيل مُشغَّلة، أو [`listConnections()`](https://docs.twenty.com/ar/developers/extend/apps/logic/connections)، التي تعيد `userWorkspaceId` لمالك كل اتصال.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.