Аналитика открытий пейформы

Дополнительная, необязательная интеграция

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

Как это работает

Создайте платёж обычным способом и сохраните его uuid и payment_url.
Когда покупатель нажал кнопку оплаты, ваш сервер регистрирует клик через POST и получает attempt_id.
Откройте прежнюю payment_url. Добавлять attempt_id в ссылку не нужно.
Позже запросите историю через GET: она содержит время клика и существующее время первого открытия формы.

Одна транзакция может иметь несколько кликов. Поле checkout_id связывает каждый клик с её UUID. У общей платёжной формы UUID сохраняется при выборе метода и создании транзакции. Прямые внешние формы провайдера, например CryptoBot, и выплаты не поддерживаются.

Регистрируйте именно наблюдаемый клик

Создание платежа или отправка ссылки покупателю ещё не являются кликом. Обычная URL-кнопка Telegram сама по себе не сообщает боту о нажатии: нужен callback, действие вашего приложения или переходный URL, на котором вы можете зафиксировать переход. Задержка или ошибка аналитики не должна блокировать оплату: ограничьте ожидание запроса и при необходимости повторите его с тем же ключом.

Зарегистрировать клик

POST/integration/transactions/{uuid}/checkout-attempts

Запрос выполняется с сервера мерчанта с заголовком X-Api-Key. Не передавайте API-ключ в браузер покупателя. Действуют обычные ограничения интеграционного API и разрешённых IP мерчанта.

Параметр пути

Поле	Тип	Описание
`uuid`обязательное	`UUID`	UUID транзакции или checkout-сессии из ответа создания платежа. Передаётся в пути URL, не в query-параметрах и не как `external_id`.

JSON-тело POST

Поле	Тип	Описание
`idempotency_key`обязательное	`UUID`	Сгенерируйте новый UUID для нового клика. Для повторной отправки того же клика используйте прежний ключ.

POST создаёт запись о клике, поэтому используется именно этот HTTP-метод. В этом запросе query-параметров нет. idempotency_key передаётся в JSON-теле с Content-Type: application/json.

curl -X POST "https://api.cashera.cash/api/v1/integration/transactions/9b1f2c4e-7a01-4b9d-8f1c-2eab57d90c11/checkout-attempts" \
  -H "X-Api-Key: $CASHERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key":"aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"}'

Повтор с тем же ключом в рамках одного checkout возвращает ту же запись и 201, не изменяя attempt_id и clicked_at. Второй вызов для подтверждения клика не нужен.

Получить историю кликов

GET/integration/transactions/{uuid}/checkout-attempts

Используйте тот же UUID и API-ключ мерчанта. Здесь page — query-параметр: целое число от 1 до 100000, по умолчанию 1. На странице до 50 записей, сначала новые по clicked_at, затем по attempt_id при одинаковом времени.

curl "https://api.cashera.cash/api/v1/integration/transactions/9b1f2c4e-7a01-4b9d-8f1c-2eab57d90c11/checkout-attempts?page=1" \
  -H "X-Api-Key: $CASHERA_API_KEY"

Поля записи

Поле	Тип	Описание
`attempt_id`	`UUID`	Идентификатор зарегистрированного клика.
`checkout_id`	`UUID`	UUID транзакции или checkout-сессии, к которой относится клик.
`clicked_at`	`datetime`	Первое получение сообщения о клике сервером Cashera, UTC. Это не время устройства покупателя.
`checkout_opened_at`	`datetime \| null`	Существующее время первого открытия checkout, UTC. null означает, что открытие пока не зафиксировано.

POST и GET возвращают Cache-Control: no-store. API не вычисляет статусы аналитики и не устанавливает порог ожидания: при позднем открытии следующий GET вернёт его время, исходный клик не изменится.

Как интерпретировать данные

checkout_opened_at фиксирует первый успешный запрос данных формы на backend, а не полную отрисовку страницы. Поле относится ко всей транзакции, а не к каждому клику. Если форму открыли раньше, новый клик вернёт прежнее время открытия — это не подтверждает, что повторный переход был успешным.

Для аналитики считайте уникальные checkout_id с кликом и с зафиксированным открытием. Отдельно учитывайте транзакции, открытые до зарегистрированного клика. Не делите число записей с датой открытия на число кликов: повторные клики исказят результат.

Отсутствие открытия не доказывает блокировку

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

Ошибки и ограничения

Поле	Тип	Описание
`401`	`Unauthorized`	Отсутствует или неверен API-ключ.
`403`	`Forbidden`	Доступ запрещён, в том числе IP не входит в разрешённый список мерчанта.
`404`	`Not Found`	Checkout не существует, принадлежит другому мерчанту или не поддерживается этим методом.
`409`	`Conflict`	Достигнут предел 100 кликов на checkout. Повтор уже зарегистрированного ключа остаётся доступен.
`422`	`Unprocessable Entity`	Неверный или отсутствующий idempotency_key либо недопустимый page.
`429`	`Too Many Requests`	Превышен общий лимит интеграционного API. Не опрашивайте историю в частом цикле.