Підписатися
Автор: publisher in api —

API-інтеграція Трекера та Партнерки: Повний Гайд з Кодом та Налаштуваннями для Автоматизації Звітів

API-інтеграція Трекера та Партнерки: Повний Гайд з Кодом та Налаштуваннями для Автоматизації Звітів

Прощавай, ручна аналітика: чому без API-автоматизації ви втрачаєте гроші

Забудьте про часи, коли ви годинами звіряли статистику в трекері та кабінеті партнерської програми (ПП), намагаючись зрозуміти реальний ROI. Сьогодні, коли швидкість прийняття рішень визначає, заробите ви чи зіллєте бюджет, ручна робота — це прямий шлях до збитків. Некоректні дані, затримка в оновленні статусів лідів, неможливість миттєво оцінити ефективність зв'язки — все це призводить до того, що ви продовжуєте лити трафік на неробочі кампанії.

Основна проблема криється у розриві даних. Трекер показує кліки та, можливо, апрувнуті конверсії через postback, але повну картину — апрув, треш, холд, реальний дохід — ви бачите лише в ПП. API-інтеграція вирішує цю проблему, створюючи єдиний інформаційний простір. Ви автоматично підтягуєте всі статуси та фінансові показники з партнерки прямо у ваш трекер. Це дозволяє будувати звіти на основі фінального заробітку, а не проміжних метрик, і оптимізувати кампанії по CPA, спираючись на фактичний дохід.

Підготовчий етап: що потрібно для старту

Перш ніж ми перейдемо до коду та налаштувань, переконайтеся, що у вас є необхідний технічний фундамент. Без цього будь-яка автоматизація буде крихкою.

  • Надійний трекер. Такі рішення як Keitaro або Binom — індустріальний стандарт. Вони мають гнучкий API для оновлення даних про конверсії.
  • Доступ до API партнерської програми. У кабінеті ПП знайдіть розділ "API" або "Developers". Там має бути ваш унікальний ключ (API Key) та документація з описом методів. Якщо його немає — пишіть сапорту.
  • VPS-сервер. Вам знадобиться місце для запуску скрипту-посередника. Невеликого VPS на Ubuntu 22.04 LTS з 1 vCPU та 1GB RAM буде достатньо.

Шлях джедая (без коду): Make / Zapier.

Якщо ви не хочете піднімати VPS і писати PHP, використовуйте візуальні конструктори.

  • Сценарій: Webhook від ПП (при зміні статусу ліда) -> HTTP Request в Keitaro (Admin API). Це коштує $10/міс і налаштовується за 15 хвилин мишкою. Ідеально для старту.

Базове налаштування безпеки сервера

Перш ніж розміщувати скрипт, убезпечте свій сервер. Це не опція, а вимога.


# Оновлюємо пакети
sudo apt update && sudo apt upgrade -y

# Встановлюємо простий файрвол UFW
sudo apt install ufw

# Дозволяємо тільки необхідні з'єднання (SSH, HTTP, HTTPS)
sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https

# Включаємо файрвол
sudo ufw enable

# Встановлюємо PHP та розширення для роботи з API
sudo apt install php-cli php-curl -y

Ці команди закриють усі непотрібні порти, залишаючи доступ лише для веб-трафіку та управління сервером через SSH.

Покрокова інструкція: налаштування API-синхронізації

Розглянемо найпоширеніший сценарій: ми хочемо раз на 15 хвилин забирати з партнерки статуси по всіх конверсіях за останню добу та оновлювати їх у трекері Keitaro.

Крок 1: Аналіз API документації

Відкрийте документацію ПП. Нас цікавить метод для отримання конверсій (зазвичай називається `get_conversions`, `get_leads` або схожим чином). Зверніть увагу на обов'язкові параметри:

  • api_key — ваш ключ авторизації.
  • date_from / date_to — діапазон дат для вибірки.
  • subid_param — параметр, в якому ПП зберігає мітку вашого трекера (clickid). Це найважливіший зв'язок між системами.
  • status — параметр, що дозволяє фільтрувати ліди за статусом (pending, approved, rejected).

Перевірте готові рішення!

Перш ніж писати код, зайдіть в налаштування Оффера в Keitaro/Binom. Там часто є кнопка "API Integration". Ви просто вставляєте API Key партнерки, і трекер сам все робить. Пишіть свій скрипт тільки якщо готової інтеграції немає.

Крок 2: Створення PHP-скрипта

Створимо на нашому VPS файл для скрипта. Наприклад, `pp_sync.php`.


nano /var/www/pp_sync.php

Вставте у нього наступний код, замінивши заглушки на ваші реальні дані.


<?php
// --- CONFIGURATION ---
$pp_api_key = 'YOUR_PARTNER_PROGRAM_API_KEY';
$pp_api_url = 'https://api.partnerka.com/v2/conversions.get';

$keitaro_api_key = 'YOUR_KEITARO_ADMIN_API_KEY';
$keitaro_api_url = 'https://your_keitaro_domain.com/admin_api/v1/conversions/log';

// --- SCRIPT LOGIC ---

// 1. Формуємо запит до API партнерки, щоб отримати конверсії за останню добу
$date_from = date('Y-m-d', strtotime('-1 day'));
$date_to = date('Y-m-d');

$request_params = [
    'api_key' => $pp_api_key,
    'date_from' => $date_from,
    'date_to' => $date_to,
    'limit' => 1000 // Забираємо до 1000 конверсій за раз
];

$url = $pp_api_url . '?' . http_build_query($request_params);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$conversions = json_decode($response, true);

if (empty($conversions['data'])) {
    echo "No new conversions found. Exiting.\n";
    exit;
}

// 2. Проходимо по кожній конверсії та готуємо дані для оновлення в трекері
foreach ($conversions['data'] as $conv) {
    // Важливо: назви полів 'subid', 'status', 'payout' можуть відрізнятись. Дивіться документацію вашої ПП!
    $subid = $conv['subid'];
    $status = strtolower($conv['status']); // Приводимо до нижнього регістру
    $payout = (float)$conv['payout'];

    // Мапінг статусів ПП на статуси Keitaro
    $keitaro_status = 'pending'; // За замовчуванням
    if ($status === 'approved' || $status === 'confirmed') {
        $keitaro_status = 'sale';
    } elseif ($status === 'rejected' || $status === 'trash') {
        $keitaro_status = 'rejected';
    }

    // Готуємо запит на оновлення в Keitaro
    $keitaro_update_data = [
        'sub_id' => $subid,
        'status' => $keitaro_status,
        'payout' => $payout
    ];

    $ch_keitaro = curl_init($keitaro_api_url);
    curl_setopt($ch_keitaro, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch_keitaro, CURLOPT_POST, true);
    curl_setopt($ch_keitaro, CURLOPT_POSTFIELDS, json_encode($keitaro_update_data));
    curl_setopt($ch_keitaro, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Api-Key: ' . $keitaro_api_key
    ]);

    $keitaro_response = curl_exec($ch_keitaro);
    curl_close($ch_keitaro);

    echo "Updating subid {$subid}: Status -> {$keitaro_status}, Payout -> {$payout}. Response: {$keitaro_response}\n";
    sleep(1); // Робимо невелику затримку, щоб не заспамити API
}

echo "Sync completed.\n";
?>

Важливо: встановіть правильні права на цей файл, щоб ніхто, крім вас, не міг його прочитати, адже він містить API-ключі.


chmod 600 /var/www/pp_sync.php

Крок 3: Автоматизація запуску через Cron

Щоб скрипт працював автоматично, додамо завдання в Cron. Cron — це планувальник завдань в Linux.


crontab -e

В кінець файлу, що відкрився, додайте наступний рядок. Він буде запускати наш скрипт кожні 15 хвилин.


*/15 * * * * /usr/bin/php /var/www/pp_sync.php >> /var/log/pp_sync.log 2>&1

Ця команда:

  • */15 * * * * — запускає завдання кожні 15 хвилин.
  • /usr/bin/php /var/www/pp_sync.php — виконує наш скрипт.
  • >> /var/log/pp_sync.log 2>&1 — перенаправляє весь вивід (і помилки) в лог-файл для подальшого аналізу.

Підводні камені та часті помилки новачків

1. API Rate Limiting (ліміти запитів)

Більшість API мають обмеження на кількість запитів за хвилину/годину. Якщо ваш скрипт робить занадто багато запитів, ваш IP тимчасово заблокують. Рішення: Завжди використовуйте `sleep(1);` всередині циклів обробки даних, щоб створити паузу між запитами. Забирайте дані більшими "пачками" (batch), а не по одній конверсії.

2. Різні часові пояси (Timezones)

Ваш сервер, сервер трекера та сервер ПП можуть знаходитись в різних часових поясах. Це призводить до того, що ви запитуєте дані за "вчора", а отримуєте неповну вибірку. Рішення: Завжди уточнюйте в документації API, в якому часовому поясі (зазвичай UTC) працює партнерка. Приводьте всі дати до єдиного стандарту.

3. Некоректне передавання SubID

Якщо ваш трекер передає clickid в параметрі `s1`, а ПП очікує його в `sub_id`, дані ніколи не зв'яжуться. Це найпоширеніша і найдурніша помилка. Рішення: Двічі перевірте налаштування кампанії в трекері та документацію ПП. Переконайтесь, що параметр, в який ви кладете `{subid}` трекера, відповідає тому, який повертає API партнерки.

4. Ігнорування версіонування API

API оновлюються. Метод, який працював сьогодні (`/v1/leads`), завтра може стати застарілим і переїхати на адресу `/v2/leads`. Рішення: Періодично переглядайте документацію API. Підпишіться на розсилку для розробників від вашої ПП, якщо така є.

​Втрата ClickID: Найчастіша причина провалу.

Коли користувач клікає по рекламі, трекер присвоює йому унікальний subid (наприклад, z5d9s8f7). Якщо цей код не дійде до CRM партнерки, ви ніколи не дізнаєтесь, хто саме зробив депозит.

  • Перевірка: Зробіть тестовий лід і переконайтеся, що в кабінеті ПП у колонці sub_id (або click_id) відображається той самий код, що і в логах трекера.

Що далі?

Коли ви налаштували автоматичну синхронізацію статусів, ви отримуєте реальну картину ефективності. Тепер ви можете створювати в трекері звіти на основі чистого прибутку, а не кількості лідів. Це дозволяє точніше оптимізувати рекламні кампанії в Business Manager, відключати неефективні плейсменти, і бачити, який Pixel event приносить найбільше грошей.

Автоматизація аналітики звільняє ваш найцінніший ресурс — час. Замість того, щоб копіювати цифри з однієї таблиці в іншу, ви можете зосередитись на головному: пошуку нових зв'язок за допомогою спай-сервісів, підготовці якісних акаунтів через фармінг та генерації унікальних креативів, наприклад, за допомогою нейромереж типу Midjourney для зображень та ElevenLabs для озвучки. В сучасному арбітражі перемагає не той, хто більше працює руками, а той, хто краще автоматизує рутину.