Списание кредитов

​

Обзор

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 — одна понятная строка, показываемая покупателям в карточке вашего приложения на маркетплейсе.

​

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

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; вместо этого она не списывается единовременно за весь год.
• Ограничено. Заявленная ставка выше $100 или плата с участника, ставка которой, умноженная на количество участников, превысила бы $1,000 за период, отклоняется и не повышается. Платформа сама начисляет эти суммы, поэтому она не создаст списание, которое не может обосновать.

​

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

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

​

Списание

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

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

• Объявление операций позволяет разделять в разделе «Использование» расходы вашего приложения по тому, за что оно взимало плату. Приложение, которое ничего не объявляет, всё равно отображается как один сегмент под своим отображаемым именем.
• Списание за операцию, не объявленную в вашем манифесте, отклоняется. Добавьте её в billing.operations и синхронизируйте.
• Несколько операций могут использовать один operationType. Две операции обогащения данных, учитываемые как CODE_EXECUTION, всё равно отображаются как два сегмента с метками.
• Без operation укажите категорию выставления счетов напрямую с помощью operationType, при необходимости добавив произвольный resourceContext. Эти две формы взаимоисключающие: operation содержит метку, а operationType — нет.
• Списание никогда не приводит к сбою вашей функции. Ошибка выставления счетов регистрируется и игнорируется, а вызов ничего не делает вне среды выполнения логической функции, поэтому локальные запуски и тесты не завершаются аварийно.

​

Проверка перед расходованием

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

const { hasAvailableCredits } = await getCreditAvailability();

if (!hasAvailableCredits) {
  return;
}

• Он показывает, может ли ваше приложение тратить средства в этой рабочей области, а не то, сколько средств в ней осталось. Ваше приложение не видит баланс, тарифный план или его лимиты.
• Он завершается с разрешением доступа. Если проверка истекает по времени или сервер недоступен, она сообщает, что кредиты доступны, чтобы сбой инфраструктуры не останавливал ваше приложение. Считайте это подсказкой, которой стоит следовать, а не решением об авторизации.
• Это снимок состояния. Кредиты могут закончиться между проверкой и выполнением — в том числе из-за ваших собственных списаний, поскольку каждое совершённое вами списание изменяет тот же счётчик, который считывается здесь.
• Ограничение применяется не везде одинаково. Не каждый путь отправки исходящих писем зависит от кредитов, поэтому значение false здесь указывает, что вашему приложению не следует тратить средства прямо сейчас, а не точно предсказывает, какие вызовы завершатся ошибкой.

​

Как сообщить людям о стоимости

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

​

Атрибуция

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