Песочница для интеграторов

Песочница — настоящая компания на нашей платформе, заведённая на неделю, на тарифе «Про»: открытый API и вебхуки включены. Тот же API и те же коды ошибок, что у боевых клиентов. Регистрироваться, вводить почту и ждать ответа не нужно: ключ выдаётся сразу, вместе с программой, точкой продаж и тремя гостями с картами.

Перед выдачей может появиться проверка «я не робот» — пройдите её, и песочница заведётся. Всё выданное показывается один раз и нигде не хранится: ключ, как и боевой, в базе лежит только отпечатком. Потеряли — возьмите новую песочницу.

Что внутри

1. Ключ API со всеми областями доступа

   Чеки, возвраты, поиск карты, купоны, заведение гостя и подтверждение номера — всё, что умеет открытый API. Ключ начинается с wlk_test_, чтобы его нельзя было перепутать с боевым в конфиге кассы.

2. Точка продаж и программа

   «Демо-точка» в московском часовом поясе и программа с приветственным бонусом в 100 баллов. Идентификатор точки для locationId отдаёт GET /program.

3. Три гостя с картами

   Телефоны, штрихкоды и балансы приходят в ответе. У двоих уже есть покупки, у третьей — только приветственный бонус. Проводить чек есть по кому с первой минуты — искать в пустой базе некого.

4. Кабинет с паролем

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

5. Страница выдачи карты

   Публичный адрес программы: можно пройти путь гостя целиком и поставить карту в свой телефон. Анкета спрашивает только имя.

Выдача отвечает одним JSON — форма выше показывает его целиком:

Как проверить, что всё работает

Проведите чек по любому из выданных штрихкодов. Заголовок Idempotency-Key обязателен — он защищает от двойного начисления при повторной отправке. Готовую команду с вашим ключом и первым из выданных гостей печатает сама выдача — поле «Первый запрос», её достаточно скопировать.

curl -X POST https://api.snovacard.ru/api/v1/transactions \
  -H "x-api-key: ВАШ_КЛЮЧ" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: demo-$(date +%s)" \
  -d '{"cardBarcode":"ШТРИХКОД_ГОСТЯ","amount":1000,"redeemPoints":0}'

Idempotency-Key — любая строка, уникальная для чека: номер чека из кассы, UUID, что угодно. В примере это секунды текущего времени, чтобы команда работала в любой оболочке без дополнительных утилит; повторная отправка с тем же ключом вернёт прежний ответ и баллы второй раз не начислит.

В ответе — начисленные баллы, новый баланс и сработавшие правила. Дальше стоит проверить списание: спросите карту по телефону (POST /cards/lookup), посмотрите maxRedeemPercent и проведите чек с redeemPoints. Подробно о методах — в описании API.

Чем песочница отличается от боевой компании

1. Живёт неделю

   Потом ночная уборка удаляет её целиком — с гостями, картами, историей и учётной записью владельца. Продлить нельзя — берите новую, это одна кнопка.

2. Код показывается, а не отправляется

   Никаких сообщений наружу: ни письма, ни SMS, ни звонка. На странице выдачи код виден прямо на форме, а POST /customers/phone-code возвращает его полем shownCode. На боевой компании код уходит гостю, и каналы выбирает владелец.

3. Ключ знает, что он песочный

   GET /program отвечает company.sandbox: true — по нему интеграция может показать разработчику код подтверждения, не нарушая правила для боевых ключей.

4. Оператор персональных данных — мы

   Заведения за песочницей нет, поэтому в согласии названы наши реквизиты. У настоящего клиента там его юридическое лицо и его ИНН.

5. Не больше трёх в сутки с одного адреса

   Выдача открыта без авторизации, и предел защищает её от перебора. Считается и выдача, сорвавшаяся на середине. Нужно больше — напишите нам, договоримся.

Кроме предела по адресу есть два общих: не больше 30 песочниц в час на всю платформу и не больше 500 живых одновременно. Упрётесь в них — выдача ответит RATE_LIMITED с просьбой повторить позже; в details.retryAfterSec — через сколько секунд.

Частые вопросы