API

Адрес и авторизация

Базовый адрес по умолчанию — https://thanklyclub.com. Каждый запрос к /v1 передаёт ключ сайта из кабинета ThanklyClub и служебные заголовки.

• Authorization: Bearer <site_key> — ключ сайта.
• X-ThanklyClub-Site: адрес магазина, например https://shop.example/.
• X-ThanklyClub-Plugin: версия плагина, например 0.1.0.
• Content-Type: application/json.

Ошибки

Любой ответ с кодом не из 2xx считается ошибкой, тело — {"error": "текст"}. Плагин показывает этот текст владельцу магазина. Неверный ключ — 401, заблокированный кабинет — 403, неизвестный метод — 404.

Если сервер недоступен, плагин показывает страницу «Спасибо» без блока подарков.

GET /v1/site — проверка ключа

Возвращает {"ok": true, "site_id": "...", "merchant": "..."}. Плагин вызывает его по кнопке Test connection.

POST /v1/analyze — AI-анализ магазина

Тело — {"store": {...}}: снимок каталога с полями site (название, описание, адрес, локаль), store (валюта, страна, куда продаёт, число товаров, минимальная, медианная и максимальная цена), categories (название и число товаров) и products (название, цена, категории). Плагин ждёт ответа до 60 секунд.

Ответ: store_profile (краткое описание, основная и дополнительная вертикаль, ценовой сегмент, страна), recommendations — список {category, decision, score, reason}, а также brand_safety, model и analyzed_at.

category — только ключи таксономии ThanklyClub, неизвестные плагин отбрасывает. decision — allow, block или review. Плагин дополнительно сам принуждает: запрещённые категории — всегда block, чувствительные — никогда не allow.

POST /v1/offers — подарки для заказа

Вызывается один раз на заказ, ответ хранится в заказе, и письмо показывает те же подарки. Таймаут на стороне плагина — 4 секунды.

Тело запроса: context — место показа (thankyou или email), категории и названия товаров, число позиций, диапазон суммы (<25, 25-75, 75-200, 200+), валюта, страна, язык и признак повторного покупателя; rules — allowed (включённые категории) и blocked_domains; max — от 1 до 3. Персональных данных в запросе нет.

Ответ: request_id и массив offers. У каждого оффера: id, category, brand, title, description, cta, image, domain, click_url, terms. Тексты — на языке из context.language. Плагин отбрасывает офферы не из allowed и с доменов из blocked_domains.

POST /v1/events — показы

Тело — {"events": [...]}, до 50 событий: type, offer_id, request_id, placement, ts. Плагин отправляет события, не дожидаясь ответа.

Сервер учитывает показы (impression), причём один раз на запрос, оффер и место показа. Клики сервер считает сам по переходу через /c/, поэтому события click в статистику не идут.

GET /v1/stats?days=30 — статистика

Возвращает показы, клики, конверсии, заработок магазина и сумму на проверке за указанный период (от 1 до 365 дней), валюта — EUR. Плагин кэширует ответ на 15 минут.

Клик: GET /c/<offer_id>?r=<request_id>

click_url из ответа /v1/offers. Сервер проверяет, что оффер был в этом запросе и активен, записывает клик и перенаправляет покупателя к рекламодателю. В адрес рекламодателя добавляется параметр sub с идентификатором клика. Параметр p=email отмечает клик из письма.

По одному офферу из одного заказа засчитывается не больше трёх кликов — это защита от накрутки. Переход идёт с заголовком Referrer-Policy: no-referrer.

Постбэк: GET /postback

Рекламодатель или партнёрская сеть сообщает о конверсии запросом /postback?sub=<id клика>&payout=<сумма>&status=<статус>&secret=<секрет>.

sub — значение, полученное в ссылке перехода. payout — выплата в евро; если не передана, берётся ставка оффера. status — pending (на проверке), approved (подтверждена) или rejected (отклонена); по умолчанию pending. secret — секретный параметр постбэка, который ThanklyClub выдаёт при подключении.

Повторный постбэк с тем же sub обновляет статус и сумму существующей конверсии. Доля магазина считается от payout — 60%. Ответ: {"ok": true, "conversion_id": "...", "status": "..."}.

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