Дополнительные услуги сети

Базовое подключение, обычные лайки, мэтчи и переписка не требуют покупки дополнительных услуг. Площадка может подключиться и пользоваться сетью без них. Мы предоставляем услуги площадке для её пользователей, а не принимаем оплату от людей напрямую. Цены и состав предложений своим пользователям площадка определяет сама.

На старте все четыре услуги сети стоят 0 ₽. Даже нулевой заказ требует подтверждения, отдельного ключа и создаёт право на услугу. Это позволяет проверить интеграцию до появления ненулевых цен. TEST-кредиты тестового контура не являются деньгами и не используются в боевом контуре. Ненулевые RUB-платежи в текущем релизе не поддерживаются.

Что можно подключить

Сутки — ровно 24 часа. Права персональные: заказ указывает external_id пользователя своей площадки. Сетевой суперлайк расходует одну единицу с первого исполненного действия; защитный предел 5 суперлайков за сутки не является бесплатной квотой. Обычные лайки остаются бесплатными. Мэтчи не истекают по времени, их срок не продаётся. Жалобы, блокировки, удаление и выход из сети остаются бесплатными.

Подключение без поломки действующей интеграции

Сначала проверьте GET /v1/capabilities: commerce_enabled означает доступность полного API услуг, но не подключение вашей площадки к нему. commerce_live_zero_only сообщает о режиме только нулевых RUB-заказов; commerce_pilot — об отдельном TEST-only пилоте разработки, в production он выключен.

Существующие боевые интеграции сохраняют прежнее поведение суперлайков и отмен до явного подключения. До перехода реализуйте заказы, права и устойчивые идентификаторы действий; затем свяжитесь с нами через форму. Администратор подключит рабочий расходный аккаунт и передаст отдельный X-Commerce-Key по приватному каналу. Кабинет пока не выпускает этот ключ и не оформляет заказы сам. Обычный API-ключ продолжает использоваться отдельно. Оба ключа хранятся только на сервере площадки.

Получать продвигаемые анкеты можно бесплатно, без расходного аккаунта. Не нужно включать все услуги сразу.

Котировка, подтверждение, право

1. GET /v1/commerce/catalog — актуальные SKU, валюта, цена за единицу, допустимое количество и fulfillment_ready. Рабочий каталог — RUB, тестовый — TEST; не подменяйте один другим.
2. POST /v1/commerce/quotes — котировка на свою анкету; действует пять минут. Ничего не списывает и не запускает.
3. POST /v1/commerce/orders — подтверждение с обычным Bearer-ключом и отдельным X-Commerce-Key. external_order_ref — устойчивый идентификатор заказа вашей системы.
4. GET /v1/members/{external_id}/entitlements — выданные права. GET /v1/members/{external_id}/boost — состояние и остаток буста.

# Только на сервере площадки. UUID котировки берём из ответа первого запроса.
curl -X POST 'https://api.pereval.dating/v1/commerce/quotes' \
  -H "Authorization: Bearer $PEREVAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"member":"user-123","sku":"boost","quantity":40}'

curl -X POST 'https://api.pereval.dating/v1/commerce/orders' \
  -H "Authorization: Bearer $PEREVAL_API_KEY" \
  -H "X-Commerce-Key: $PEREVAL_COMMERCE_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"quote_id":"<UUID из ответа>","external_order_ref":"boost-order-42"}'

При потере ответа повторите подтверждение с тем же external_order_ref и quote_id: вернётся тот же заказ, без второй активации или продления. Другой UUID с прежним идентификатором — конфликт. Не создавайте новый заказ, пока не выяснили результат предыдущего. Цена сохраняется из котировки; отключённая услуга или просроченная котировка не подтверждается.

GET /v1/commerce/balance возвращает TEST-баланс либо нулевой RUB-баланс; это не банковский счёт и не способ пополнения рублями. Услуги, права и нулевые заказы проходят тот же учёт и авторизацию. Сеть не выполняет автопополнение и автопродление.

Буст: запуск, выдача и время

• Буст начинается немедленно после успешного подтверждения заказа, в том числе нулевого. Аудитория и первый показ не являются условиями запуска.
• Повторная покупка продлевает тот же активный буст без усиления и сброса истории ротации. После завершения начинается новое поколение.
• Отмены запущенного буста и добровольного возврата нет. Скрытие/удаление анкеты не останавливает время. Площадка отвечает за свои предупреждения пользователю и расчёты с ним.
• При уже включённом инкогнито новый буст отвергается до исполнения заказа: 409 boost_incompatible_with_incognito. Включить инкогнито во время буста можно: приватность действует сразу, время продолжает идти.
• Фильтры, согласия, блокировки и модерация важнее продвижения. Нет гарантии числа просмотров, лайков, мэтчей или результата при пустой аудитории.

Получающая площадка включает формат:

PUT /v1/commerce/delivery
{ "format": "search", "enabled": true }

Поддерживаются swipe и search; отключение — {"format":"none","enabled":false}. Площадка с картой может покупать исходящие бусты для своих пользователей; получение продвижения на карту пока не поддерживается. Не выдавайте обычную точку на карте за исполненный буст.

Приоритет — не более 20% дополнительных мест в устойчивой API-последовательности (позиции 5, 10, 15 и далее), без дублей; при отсутствии подходящих бустов идут обычные анкеты. Площадка сохраняет приоритет в своём интерфейсе. Это не обязательство показывать рекламу и не подтверждение фактического просмотра человеком.

Для одного поиска/листания сохраняйте X-Feed-Request-Ref и параметры вместе с next_cursor. Повторы и страницы относятся к одному поиску, явный новый поиск получает новый идентификатор. Сессия длится 15 минут, до 200 кандидатов; изменённые фильтры требуют нового поиска. Уже материализованная страница не увеличивает счётчик второй раз; пригодность анкеты перепроверяется перед ответом. Дневной лимит общий с обычной лентой.

Событий «показ карточки» от площадки не требуется. api_placements означает дополнительные места в API, а не просмотры. Техническая пауза часов сети при обнаруженном перерыве более 10 секунд сохраняет остаток и автоматически возобновляет буст с тем же поколением. Это консервативный механизм: он не обнаруживает каждый частичный сбой или недоступность отдельной площадки. Маленькая аудитория сама по себе не является сбоем.

Суперлайки и отмены: повтор действий

После подключения расходного аккаунта передавайте X-Action-Ref для суперлайков и отмен через REST. В MCP-инструменте like для суперлайка можно передать тот же идентификатор в аргументе action_ref. Если передаёте и аргумент, и заголовок, значения должны совпадать. При повторе используйте тот же идентификатор, отправителя, получателя, вид действия и текст. Повтор через REST или MCP расходует право только один раз и создаёт одно событие. Заказы и отмену решений оформляйте через REST.

Суперлайк и расход права атомарны: ошибка исполнения не тратит единицу. Сообщение — часть суперлайка, отдельной услуги «написать без мэтча» нет. Отмена требует действующего права на сутки, без счётчика операций; нельзя отменить мэтч или восстановить удалённую переписку. После истечения права новый rewind возвращает 402 entitlement_required.

Инкогнито: срок и приватность

PUT /v1/members/{external_id}/incognito с {"enabled":true} включает режим при действующем праве; false выключает его бесплатно. Покупка суток выдаёт право, но сама не включает режим. Следующие покупки продлевают период без пересечений; выключение не приостанавливает срок.

Истечение права не публикует анкету автоматически: режим остаётся включённым, новое получение ленты блокируется до продления или явного выключения инкогнито. Предыдущие раскрытия и уже открытые мэтчи не исчезают из чужих кешей. Обычное скрытие через consent.network:false бесплатно и не требует инкогнито.

Ошибки и события

Основные ответы: 402 entitlement_required, 403 commerce_forbidden, 409 commerce_conflict, 409 quote_expired, 409 boost_incompatible_with_incognito, 422 invalid_commerce_request, 503 commerce_unavailable, 503 live_payments_unavailable. Для TEST-остатка — 402 insufficient_test_credits. Сначала устраните причину; не повторяйте заказ с новым идентификатором вслепую.

Буст передаёт boost.started, boost.extended, boost.paused, boost.resumed, boost.completed через обычную очередь событий. Подпись и защита от повторов — как у других вебхуков. Неизвестное событие безопасно игнорируйте, сохраняя совместимость. После восстановления старого бэкапа сверяйте более новые заказы и действия до возобновления выдачи прав; одной очистки или повторной доставки outbox для этого недостаточно.

Поля и примеры всех операций — в справочнике API. Цены берите из каталога, а не из текста документации. Сеть не обязывает площадку продавать эти услуги пользователю и не отменяет правил против фейков и сбора базы.