# Быстрый старт

Первый чек в песочнице в пять шагов: документы программы, регистрация участника, расчёт покупки, проведение чека и
баланс. Понадобится ключ кассы песочницы `lk_test_…` — мы пришлём его вместе с тестовым магазином и SDK, напишите на
[hello@rebonus.ru](mailto:hello@rebonus.ru).

## Ключ и адрес

```bash
export LOYAL_BASE_URL=https://sandbox.rebonus.ru
export LOYAL_TERMINAL_KEY=lk_test_…   # ключ кассы песочницы
```

- Ключ передаётся в заголовке `Authorization: Bearer lk_test_…`. Это секрет сервера кассы или сайта: в коде страниц
  для покупателей и в мобильном приложении его быть не должно.
- В песочнице сообщения никому не уходят и принимаются только тестовые телефоны +7 900 000-00-00 … +7 900 000-99-99.
  Код подтверждения у них всегда `000000`.
- Суммы — целые копейки, количество — тысячные доли: 2 шт. — это `2000`.

## 1. Документы программы

Участник вступает в программу, принимая её правила и согласие на обработку персональных данных. Действующие версии
документов отдаёт API — касса показывает их покупателю до регистрации:

```bash
curl "$LOYAL_BASE_URL/api/v1/consent-documents" \
  -H "Authorization: Bearer $LOYAL_TERMINAL_KEY"
```

## 2. Код и регистрация

Отправьте код на телефон покупателя, проверьте его и зарегистрируйте участника. Изменяющие запросы Runtime API идут с
заголовком `Idempotency-Key`: повтор с тем же ключом после обрыва связи вернёт сохранённый ответ и ничего не сделает
второй раз. Ключ — новый для каждого действия и без данных покупателя: он хранится как есть.

```bash
CODE_KEY=$(uuidgen)
curl "$LOYAL_BASE_URL/api/v1/members:send-code" \
  -H "Authorization: Bearer $LOYAL_TERMINAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CODE_KEY" \
  -d '{"phone": "+79000000001"}'
```

В ответе — `verification_id`. Проверка кода — отдельный запрос без ключа идемпотентности: каждая попытка считается.

```bash
curl "$LOYAL_BASE_URL/api/v1/verifications/<verification_id>:verify" \
  -H "Authorization: Bearer $LOYAL_TERMINAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "000000"}'
```

Ответ `204` — код подтверждён. Теперь регистрация:

```bash
MEMBER_KEY=$(uuidgen)
curl "$LOYAL_BASE_URL/api/v1/members" \
  -H "Authorization: Bearer $LOYAL_TERMINAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $MEMBER_KEY" \
  -d '{
    "phone": "+79000000001",
    "verification_id": "<verification_id>",
    "consents": ["program_rules", "personal_data"],
    "first_name": "Анна"
  }'
```

Ответ `201` — участник с его `id` и балансом. Если телефон уже в программе, ответ — 409 `member_already_exists`, и
участника находят по телефону: `POST /api/v1/members:lookup` с `{"phone": "+79000000001"}`.

## 3. Расчёт покупки

Расчёт ничего не меняет: его можно повторять сколько угодно, например при каждом изменении корзины. Время покупки —
сейчас: чек старше 7 дней или из будущего (больше чем на 5 минут) получит 422 `invalid_receipt`.

```bash
NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl "$LOYAL_BASE_URL/api/v1/receipts:calculate" \
  -H "Authorization: Bearer $LOYAL_TERMINAL_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<EOF
{
  "purchased_at": "$NOW",
  "member": {"phone": "+79000000001"},
  "lines": [
    {"id": "1", "sku": "LATTE-M", "quantity": 2000, "amount": 48000},
    {"id": "2", "sku": "CROISSANT", "quantity": 1000, "amount": 18000}
  ]
}
EOF
```

В ответе — чек без номера: `points_earned` — сколько баллов начислится, `payable` — к оплате в копейках,
`max_redeemable_points` — сколько баллов можно списать в этой покупке. `points_earned` и `payable` есть и у каждой
строки в `lines`.

Чтобы списать баллы, добавьте `redeem_points` или `"redeem_maximum": true`. Если участника нашли по телефону или карте,
программа по умолчанию просит подтвердить списание кодом из SMS: его отправляет [`POST
/api/v1/receipts:send-redemption-code`](/docs/api/runtime/verifications/#sendRedemptionCode), а при регистрации чека
передают `redemption_confirmation`. Сайт и приложение магазина (кассы вида «Интернет-магазин» и «Мобильное
приложение») называют участника, который вошёл в свой аккаунт, по `id` — тогда по умолчанию код не нужен. Ответ
`redemption_confirmation_required: true` в расчёте говорит, что код всё же нужен.

## 4. Проведение чека

Тот же запрос с номером и бизнес-датой чека регистрирует его. `"confirm": true` проводит чек сразу; без него чек
резервирует баллы на 30 минут (статус `reserved`), а после оплаты его подтверждают
(`POST /api/v1/receipts/{receipt}:confirm`) или отменяют (`:cancel`).

```bash
NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
TODAY=$(date +%F)
curl "$LOYAL_BASE_URL/api/v1/receipts" \
  -H "Authorization: Bearer $LOYAL_TERMINAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt:till-1:$TODAY:0482" \
  --data @- <<EOF
{
  "number": "0482",
  "business_date": "$TODAY",
  "purchased_at": "$NOW",
  "member": {"phone": "+79000000001"},
  "lines": [
    {"id": "1", "sku": "LATTE-M", "quantity": 2000, "amount": 48000},
    {"id": "2", "sku": "CROISSANT", "quantity": 1000, "amount": 18000}
  ],
  "confirm": true
}
EOF
```

Ключ идемпотентности чека стройте из кассы, бизнес-даты и номера: тогда повтор после обрыва связи найдёт тот же чек,
даже если касса перезапустилась. Номер чека у кассы уникален в пределах бизнес-даты — второй чек с ним получит 409
`receipt_exists`.

## 5. Баланс

```bash
curl "$LOYAL_BASE_URL/api/v1/members/<id>/balance" \
  -H "Authorization: Bearer $LOYAL_TERMINAL_KEY"
```

`spendable` — сколько можно потратить сейчас, `pending` — баллы, которые ещё не стали доступны: за покупку они
становятся доступными через срок, заданный в правилах программы.

## То же на PHP и TypeScript

SDK отправляют те же запросы: метод называется как операция в справочнике, а ключ идемпотентности SDK создаёт сам и
держит одним на все повторы вызова. SDK присылаем вместе с ключами песочницы — как его подключить, сказано на страницах
[PHP SDK](/docs/sdk/php/) и [TypeScript SDK](/docs/sdk/typescript/). В Packagist и npm нашего SDK нет: пакет с тем же
именем там был бы чужим.

```php
use Loyal\Sdk\ClientOptions;
use Loyal\Sdk\RequestOptions;
use Loyal\Sdk\RuntimeClient;

$till = RuntimeClient::create(getenv('LOYAL_TERMINAL_KEY'), new ClientOptions('https://sandbox.rebonus.ru'));

$purchase = [
    'purchased_at' => gmdate('Y-m-d\TH:i:s\Z'),
    'member' => ['phone' => '+79000000001'],
    'lines' => [
        ['id' => '1', 'sku' => 'LATTE-M', 'quantity' => 2000, 'amount' => 48000],
        ['id' => '2', 'sku' => 'CROISSANT', 'quantity' => 1000, 'amount' => 18000],
    ],
];

$calculation = $till->calculateReceipt(body: $purchase);

$today = date('Y-m-d');
$receipt = $till->registerReceipt(
    body: ['number' => '0482', 'business_date' => $today, 'confirm' => true] + $purchase,
    options: new RequestOptions(idempotencyKey: "receipt:till-1:{$today}:0482"),
);
```

```ts
import { RuntimeClient } from '@loyal/sdk';

const till = new RuntimeClient({
  apiKey: process.env.LOYAL_TERMINAL_KEY!,
  baseUrl: 'https://sandbox.rebonus.ru',
});

const purchase = {
  purchased_at: new Date().toISOString(),
  member: { phone: '+79000000001' },
  lines: [
    { id: '1', sku: 'LATTE-M', quantity: 2000, amount: 48000 },
    { id: '2', sku: 'CROISSANT', quantity: 1000, amount: 18000 },
  ],
};

const calculation = await till.calculateReceipt({ body: purchase });

const today = new Date().toLocaleDateString('sv-SE'); // ГГГГ-ММ-ДД по часам кассы
const receipt = await till.registerReceipt(
  { body: { number: '0482', business_date: today, confirm: true, ...purchase } },
  { idempotencyKey: `receipt:till-1:${today}:0482` },
);
```

## Что дальше

- [Запросы и ответы](/docs/basics/) — учётные данные, повторы, ошибки, страницы, лимиты.
- [Чеки в справочнике](/docs/api/runtime/receipts/) — возвраты, отмена, офлайн-чеки; коды для списания баллов — в
  [«Кодах подтверждения»](/docs/api/runtime/verifications/).
- [Вебхуки](/docs/webhooks/) — события программы на ваш сервер.
- [Виджеты участника](/docs/widgets/) — карта покупателя на страницах сайта.
- [Мерчант за один запуск](/docs/sdk/php/quickstart/) — пример партнёра, который заводит магазин через Management API.
