Ведіть своїх клієнтів та їхні кредити

Клієнт — користувач вашого застосунку, який платить за те, що Slen виконує для нього, кредитами — вашою власною одиницею, без валюти. Ваш застосунок створює клієнта, поповнює його кредити й називає клієнта в кожному запуску; Slen бере кредити за виклики моделей у запуску. Викликам цієї сторінки потрібен ключ із customers:write, а читанню — з customers:read.

Створити клієнта

// The external user id is your own opaque id of the customer — not an email address or a name.
$customer = $slen->customers()->create('user_8421');

echo $customer->externalUserId, ' ', $customer->status->value, PHP_EOL;

• Зовнішній ідентифікатор — ваш власний ідентифікатор клієнта. Тримайте його непрозорим — не адреса пошти й не ім’я: його видно в консолі й у кожній виписці.

• customers.create() гарантує, що клієнт існує: другий виклик відповідає тим самим клієнтом. Він не рухає кредити, і новий клієнт не має рахунків.

• Клієнт має по одному рахунку на кожен тип кредитів: default, якщо ви не назвали інший.

Поповнити й списати

use Slen\Sdk\Modules\Customers\Options\MovementOptions;

$account = $slen->customers()->topUp('user_8421', '100.0000', new MovementOptions(note: 'Invoice 7781', idempotencyKey: 'invoice-7781:topup'));

echo $account->balance, PHP_EOL;

• customers.topUp() додає кредити. Він створює рахунок цього типу кредитів, а також клієнта, коли їх ще немає.

• Примітка записується в рядок виписки: рахунок-фактура, причина.

• Ключ ідемпотентності називає рух: під тим самим ключем кредити рухаються один раз — Ключі ідемпотентності.

// A service of your own application, paid for in the customer's credits.
$charged = $slen->customers()->charge('user_8421', '5.0000', new MovementOptions(note: 'PDF export', idempotencyKey: 'export-991:charge'));

echo $charged->balance, PHP_EOL;

• customers.charge() бере кредити за послугу вашого власного застосунку, яку Slen не виконує: експорт, звіт, місце в команді. Виписка показує його окремим списанням, а не витратою виклику моделі.

• Списання, яке рахунок не може покрити, відхиляється з insufficient_credits, якщо рахункові не можна йти нижче нуля. Списання нічого не створює: списання для клієнта, якого Slen не знає, відхиляється з customer_not_found.

• customers.adjust() вручну коригує баланс, зі знаком: додатна сума додає кредити, від’ємна — забирає.

• Кредити — десятковий рядок не більше ніж із чотирма знаками після крапки: '5', '5.25'. Будь-яке інше значення, нуль і від’ємне поповнення чи списання відхиляються до надсилання запиту, з кодом invalid_request.

Прочитати баланс і виписку

$customer = $slen->customers()->get('user_8421');

foreach ($customer->accounts as $held) {
    echo $held->creditType, ' ', $held->available, PHP_EOL;
}

customers.get() відповідає клієнтом з усіма його рахунками. Рахунок має три суми:

• balance — скільки на рахунку;

• reserved — скільки на ньому тримають запуски, що тривають;

• available — balance мінус reserved: скільки може взяти новий запуск.

use Slen\Sdk\Modules\Customers\Options\EntryListOptions;

$statement = $slen->customers()->entries('user_8421', new EntryListOptions(limit: 2));

foreach ($statement->data as $entry) {
    echo $entry->entryType->value, ' ', $entry->credits, ' ', $entry->note, PHP_EOL;
}

customers.entries() читає виписку: кожен рух кредитів клієнта, спочатку найновіші, посторінково. Її можна звузити до одного типу кредитів і одного виду запису.

Сторінка несе курсор наступної: передайте його в наступний виклик і зупиніться, коли він дорівнює null. customers.list() так само читає клієнтів проєкту з їхніми рахунками. Він знаходить їх за частиною зовнішнього ідентифікатора, за статусом, за типом кредитів або за lowBalance — доступно менше кредитів, ніж число, яке ви передали.

Запуск, який оплачує клієнт

Назвіть клієнта в запуску, а тип кредитів — коли він не default, — Надіслати запит.

• Коли проєкт має ціну в кредитах для операції, кожен виклик моделі в запуску резервує цю ціну на рахунку клієнта до виклику моделі. Кредити забираються, коли виклик вдався, і повертаються, коли він не вдався.

• Операція без ціни в кредитах кредитів не бере. Ціни задають у консолі, а customers.prices() їх читає.

• Запуск, який рахунок не може оплатити, відхиляється до виклику моделі, з insufficient_credits.

• Платний запуск для клієнта, якого Slen не знає, відхиляється з customer_not_found. Спочатку створіть клієнта й поповніть його кредити.

use Slen\Sdk\Exceptions\InsufficientCreditsException;
use Slen\Sdk\Modules\Operations\Options\ExecuteOptions;

try {
    $slen->operations()->execute(
        'generate_email',
        ['messages' => [['role' => 'user', 'content' => 'Write a short follow-up email.']]],
        new ExecuteOptions(customer: 'user_9310', idempotencyKey: 'order-45:email'),
    );
} catch (InsufficientCreditsException $refused) {
    // The customer's account cannot pay for the run: nothing ran, nothing was held.
    echo $refused->errorCode, PHP_EOL;
}

insufficient_credits — одна з відмов у витраті, і обидва SDK кидають її як тип цієї родини — Коли витрату відхилено.

Налаштування рахунку

customers.updateAccount() задає два налаштування одного рахунку:

• чи може баланс іти нижче нуля — за замовчуванням ні;

• поріг, нижче якого рух надсилає вебхук customer.balance_low, — '0', значення за замовчуванням, його вимикає.

Виклик задає обидва одразу: налаштування, яке ви не передали, повертається до значення за замовчуванням. Він створює клієнта й рахунок, коли їх немає. Вебхук низького балансу надсилається один раз — коли рух опускає доступні кредити нижче порогу, — Вебхуки.

Заблокувати клієнта

use Slen\Sdk\Modules\Customers\Options\BlockOptions;

// New runs for the customer are refused from now on; the balance can still be settled.
$blocked = $slen->customers()->block('user_8421', new BlockOptions(reason: 'chargeback'));

echo $blocked->status->value, ' ', $blocked->blockReason, PHP_EOL;

• Нові запуски заблокованого клієнта відхиляються з customer_blocked. Запуск, який стояв у черзі чи чекав до блокування, відхиляється на наступному виклику моделі, який бере кредити. Обидва SDK кидають цей код як відмову політики.

• Поповнення, списання, коригування й виписка лишаються відкритими, щоб ви могли розрахуватися з клієнтом.

• customers.unblock() знімає блокування.

• customers.delete() видаляє клієнта без історії: без рухів і без балансу. Видалення клієнта з історією відхиляється з 409 і кодом customer_has_history — заблокуйте його натомість.

Що читати далі

• Коли витрату відхилено — запуск, відхилений через брак кредитів, і що з цим робити.

• Вебхуки — дізнайтеся, що кредити клієнта закінчуються.

• Кредити клієнтів — ті самі клієнти й рахунки в консолі.

• Об’єкти відповіді — кожне поле клієнта, рахунку й рядка виписки.

• Клієнти та кредити — ті самі операції через HTTP.