Recca Разработчикам
Меню

Песочница

Отдельный стенд для приёмки интеграции без боевых данных.

Песочница — отдельный экземпляр API Recca для разработки и приёмки. В ней можно создавать партнёров, заявки, конверсии и заявки на выплату, не трогая боевую сеть. Адрес CPA-двери: https://api-sandbox.recca.ru/federation/v1.

Чем она отличается от боя

  • Свои данные. У песочницы отдельная база. Ключи и данные боя в ней не существуют, а созданное в песочнице в бою не появится. Ключ для песочницы выпускается отдельно от боевого; запросите его, написав в поддержку.
  • Только API. Песочница отдаёт наружу только пути API. Интерфейс кабинета и витрины на ней не доступен, любой путь вне перечня отвечает 404.
  • Людям ничего не уходит. Сообщения людям (письма и подобные уведомления) из песочницы не отправляются: отказ тихим не бывает, а громким. Исключение — вебхуки на адрес, который назвали вы сами: они доставляются, иначе нельзя проверить свой приёмник.
  • Те же правила. Права ключа, лимит запросов, коды ошибок, идемпотентность и подпись вебхуков работают так же, как в бою. Версию контракта сверяйте по GET /federation/v1/cpa/self: она приходит в ответе пробы.

Убедитесь, что вы в песочнице

Не полагайтесь на адрес в конфигурации: его легко перепутать. Спросите сервер.

curl -s https://api-sandbox.recca.ru/federation/v1/cpa/self \
  -H "X-Recca-Tenant-Key: $RECCA_SANDBOX_KEY"

В ответе поле environment: sandbox — песочница, staging — стенд, production — бой. Код, который создаёт данные ради проверки, обязан продолжать только при sandbox. Если среда не объявлена, сервер называет себя боевым — это безопасная сторона: ваш набор откажется работать, а не начнёт писать данные в бой. То же поле есть у GET /federation/v1/self (общая дверь федерации).

Проба GET /federation/v1/cpa/self не расходует лимит запросов, поэтому её удобно звать при каждом запуске тестов.

Что стоит прогнать

Минимальная цепочка CPA-двери (права cpa:*, подробности — в разделе «CPA-API»):

  1. POST /federation/v1/cpa/partners — завести партнёра.
  2. GET /federation/v1/cpa/offers — выбрать оффер из каталога.
  3. POST /federation/v1/cpa/links — ссылка партнёра на оффер.
  4. POST /federation/v1/cpa/clicks — зафиксировать клик.
  5. POST /federation/v1/cpa/conversions — зарегистрировать конверсию; повтор с тем же external_id не создаёт дубль.
  6. GET /federation/v1/cpa/conversions/{external_id} — прочитать конверсию и расчёт.
  7. POST /federation/v1/cpa/payouts — запросить выплату; GET /federation/v1/cpa/partners/{external_id}/balance — баланс.

Для федерации сети: POST /federation/v1/users/upsert, затем POST /federation/v1/leads и POST /federation/v1/conversions с откатом через POST /federation/v1/conversions/{external_id}/reverse.

Приёмочный набор Go SDK

Go SDK содержит набор cpatest.Conformance: самопроверка, каталог, цепочка «партнёр → ссылка → клик → конверсия → повтор» и выплата. Он работает только против песочницы или стенда: на боевом адресе отказывает до первого запроса, и флага «разрешить бой» нет. Сначала набор спрашивает сервер о среде (environment), а потом уже пишет данные. Клиент выбирается явно: Environment: cpa.Sandbox; нулевое значение — боевая сеть. Подробности — в разделе «Go SDK».

Каждый шаг набора печатает request_id из ответа. Если шаг красный, назовите его в поддержку — по идентификатору находится запрос на сервере.

Вебхуки в песочнице

Укажите адрес приёма через PUT /federation/v1/cpa/self/webhook (право cpa:self:write) — секрет подписи приходит в ответе на первый вызов или при rotate_secret. Проверка подписи и повторы доставки не отличаются от боя; см. раздел «Вебхуки». Для локальной разработки используйте туннель к публичному HTTPS-адресу: адреса внутренних сетей и localhost не принимаются.

Что песочница не обещает

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

См. также