Посібники

Рецепт: API-кредити

Продавайте передплачені кредити на API чи AI-функцію й списуйте один за запит. Коли балансу бракує — відповідь 402 з посиланням на поповнення.

Відкрити як Markdown

Покупці наперед оплачують пакет кредитів; кожен запит витрачає кілька. Облік веде Perly Pay: витрата — один атомарний виклик, що не пускає в мінус, а кожен покупець має власну сторінку поповнення. Нічого не списується саме — коли кредити скінчилися, покупець поповнює. Усе про кредити — у Sell credits; тут рецепт навколо них.

З асистентом: цей рецепт робить у вашому проєкті скіл sell-credits плагіна Perly Pay для Claude Code — плагін і його приклад examples/api-credits (MIT) уже на шляху. Доти будь-який асистент прочитає той самий скіл з /.well-known/skills/perly-pay-sell-credits/SKILL.md.

Як це працює

1
Пакет кредитів
Продукт і ціна з model: "credit_pack", unit_amount у центах і credits. Один раз на режим.
2
Ваші користувачі — клієнти
Створюються раз з external_id (ваш ідентифікатор користувача); далі credits.* приймають цей ідентифікатор.
3
Поповнення
credits.topUpUrl(userId) — власна сторінка покупця: він обирає пакет і платить. Кожен сплачений пакет додає кредити.
4
Витрата за запит
Спершу credits.consume(userId, cost, { idempotencyKey }), потім робота. Повтор із тим самим ключем повертає перше списання.
5
Бракує?
insufficient_credits (409) нічого не списує: відповідайте 402 зі сторінкою поповнення, а не 500.

Spend one request's credits

try {
  await pay.credits.consume(userId, cost, { product: PRODUCT, action: "api", idempotencyKey: `req-${userId}-${requestId}` });
} catch (e) {
  if (e.code !== "insufficient_credits") throw e;
  return reply(402, { top_up: await pay.credits.topUpUrl(userId, { product: PRODUCT }) });
}
// now do the work

Запустіть приклад

1
Встановіть
npm install у examples/api-credits (Node 20.12+).
2
Ключ
Скопіюйте .env.example у .env і впишіть тестовий ключ (sk_test_…) у PERLY_PAY_SECRET_KEY.
3
Підготуйте
npm run setup створює продукт і ціну вашим ключем та друкує їхні ідентифікатори для .env.
4
Запустіть
npm start (або npm run dev), як каже його README.
5
Сплатіть без гаманця
Викличте POST /v1/shout (402), відкрийте сторінку, яку дає POST /top-up, оберіть пакет, натисніть Simulate payment на рахунку і викличте знову: 200 і X-Credits-Remaining: 499.

Пастки

Витрата без ключа ідемпотентності: повторений запит списує двічі.
Перевіряти баланс, а потім списувати двома кроками. consume сам не пускає в мінус; баланс — для показу.
Спершу робота, потім витрата. Навпаки: спершу витрата.
Тестові ідентифікатори з живим ключем. Продукти, ціни й вебхуки належать одному режиму: перед запуском повторіть налаштування з sk_live_….