> ## 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]
>
> Пока не запущено. Списание кредитов для приложений официально запускается в октябре. Эта страница опубликована заранее для партнёров, которые хотят с этим поэкспериментировать.

Приложения, работа которых стоит денег — например, средство записи звонков, оплачивающее поставщика расшифровки, или приложение для обогащения данных, оплачивающее каждое совпадение, — списывают с рабочей области **кредиты**. Всё, за что взимает плату приложение, объявляется в одном блоке `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` — одна понятная строка, показываемая покупателям в карточке вашего приложения на маркетплейсе.

Все три поступают на один и тот же счётчик кредитов и в одну и ту же разбивку **Настройки > Использование**, поэтому рабочая область видит единый счёт.

## Регулярные списания

Регулярное списание — это плата за подписку: фиксированная ежемесячная сумма, сумма за каждого участника рабочей области или и то и другое. Вы объявляете сумму, а платформа её списывает. Ваше приложение никогда не вызывает для этого `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` | Что администраторы читают для этой строки в разделе «Использование» |

Как они начисляются:

* Один раз за расчётный период рабочей области, в её собственную дату начала периода, а не первого числа месяца.
* Без пропорционального расчёта. С приложения, установленного в середине периода, списывается полная сумма за этот период; удаление приложения прекращает списания со следующего периода, но не возвращает средства за текущий.
* При списаниях за участника учитываются все участники рабочей области на момент начисления, поэтому рабочая область, которая выросла в середине периода, платит по увеличенному числу начиная со следующего периода.
* Только для ежемесячных подписок. С рабочей области на годовом тарифе не взимается плата `MONTH`; вместо этого она не списывается единовременно за весь год.
* Ограничено. Заявленная ставка выше $100 или плата с участника, ставка которой, умноженная на количество участников, превысила бы $1,000 за период, отклоняется и не повышается. Платформа сама начисляет эти суммы, поэтому она не создаст списание, которое не может обосновать.

## Платные операции

Операция — это то, за что ваше приложение взимает плату во время работы. Каждая запись сопоставляет выбранное вами имя операции с категорией выставления счетов, которую учитывает платформа, а также с меткой, показываемой администраторам рабочей области в **Настройки > Использование**.

```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` и так далее.

Заметки:

* Объявление операций позволяет разделять в разделе «Использование» расходы вашего приложения по тому, за что оно взимало плату. Приложение, которое ничего не объявляет, всё равно отображается как один сегмент под своим отображаемым именем.
* Списание за операцию, не объявленную в вашем манифесте, отклоняется. Добавьте её в `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`.

## Атрибуция

Расходы относятся к тому, кто инициировал запуск, поэтому они отображаются в **Использование по пользователям**. У запусков без инициатора (вебхук, cron) нет инициировавшего пользователя — передайте `userWorkspaceId`, если ваше приложение знает, кому принадлежат расходы. Он должен принадлежать рабочей области, в которой установлено приложение, и игнорируется, если у запуска есть инициировавший пользователь.

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

Где его получить: `context.userWorkspaceId` в запуске по триггеру или [`listConnections()`](https://docs.twenty.com/ru/developers/extend/apps/logic/connections), который возвращает `userWorkspaceId` владельца каждого подключения.

У регулярных списаний нет инициировавшего пользователя, поэтому они относятся только к приложению, а не к участнику.


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