Вебмайстри: створення токена та підключення лендінга

Вебмайстер — це партнер або джерело трафіку, яке має власний токен і може створювати заявки в X10 CRM через публічний API. Кожна заявка автоматично підписується цим вебмайстром: видно джерело, працює облік і виплати. Ця сторінка проводить весь шлях — від створення токена до робочої форми на лендінгу.

Навіщо це потрібно з точки зору процесу — на сторінці CRM для товарного бізнесу: звідки беруться заявки, як рахується конверсія кожного джерела й за що ви платите партнеру.

#Крок 1. Створити вебмайстра й отримати токен

1. 01

   Відкрийте розділ «Вебмайстри»

   У бічному меню CRM оберіть Вебмайстри. Тут список усіх партнерів, їхні токени, сума виплати й статус активності.

2. 02

   Натисніть «Додати вебмайстра»

   Вкажіть ім'я (воно ж стане джерелом заявки в картці — пишіть зрозуміло: Instagram Ads, Партнер Іванов, Landing shop-example) і суму виплати за заявку. Суму можна змінити пізніше.

3. 03

   Скопіюйте токен

   Токен генерується автоматично — це випадковий рядок на 43 символи. У таблиці поруч із ним одразу показано готову адресу API. Копіюйте кнопкою, а не виділенням мишкою: зайвий пробіл на кінці зламає авторизацію.

#Крок 2. Адреса API

Заявка створюється одним POST-запитом. Токен передається прямо в шляху — окремих заголовків авторизації не потрібно.

• crm.your-domain.com — замініть на адресу вашої CRM (та сама, на яку ви заходите в систему).
• {TOKEN} — токен вебмайстра з попереднього кроку.
• Слеш у кінці адреси обов'язковий.
• Метод — тільки POST. GET поверне 405.

#Крок 3. Перший тестовий запит

Перш ніж чіпати лендінг, переконайтеся, що токен робочий. Виконайте запит із термінала — заявка має з'явитися в CRM за кілька секунд.

curl -X POST "https://crm.your-domain.com/api/webmasters/YOUR_TOKEN/leads/create/" \
  -H "Content-Type: application/json" \
  -d '{"phone": "380681234567", "fullname": "Тест з документації"}'

Успішна відповідь виглядає так — lead_id це номер створеної заявки:

{"ok": true, "lead_id": 10241}

#Формат запиту

#Поля заявки

Обов'язкове поле лише одне — phone. Решта опційні, але чим більше ви передасте, тим менше оператор дозаповнює руками.

#Що CRM проставляє сама

#Крок 4. Підключити лендінг

Є три робочі способи. Найнадійніший — перший: токен залишається на сервері, а ви бачите результат кожного запиту.

<?php
// send-lead.php — форма лендінга шле сюди, а вже цей файл — у CRM.
// Токен лишається на сервері й не потрапляє в код сторінки.

$token = getenv('X10_WM_TOKEN');
$url   = "https://crm.your-domain.com/api/webmasters/{$token}/leads/create/";

$payload = [
    'phone'        => $_POST['phone']    ?? '',
    'fullname'     => $_POST['name']     ?? '',
    'comment'      => $_POST['comment']  ?? '',
    'landing'      => $_SERVER['HTTP_HOST'] ?? '',
    'city'         => $_POST['city']     ?? '',
    'np_department'=> $_POST['np']       ?? '',
    'utm_source'   => $_POST['utm_source']   ?? '',
    'utm_medium'   => $_POST['utm_medium']   ?? '',
    'utm_campaign' => $_POST['utm_campaign'] ?? '',
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status === 200) {
    header('Location: /thank-you');
    exit;
}

error_log("X10 CRM: заявку не створено. HTTP {$status} {$response}");
header('Location: /?error=1');

#Відповіді та помилки

#Безпека токена

• Токен дозволяє тільки створювати заявки. Він не дає доступу до бази, дзвінків чи налаштувань.
• У браузерному варіанті токен видно в коді сторінки. Це прийнятний ризик (максимум — спам-заявки), але якщо джерело трафіку сумнівне, краще проксіювати запит через свій бекенд.
• Скомпрометований токен міняється за пів хвилини: Вебмайстри → редагувати → Згенерувати новий токен. Старий перестає працювати миттєво — не забудьте оновити всі лендінги.
• Щоб тимчасово відключити партнера, зніміть галочку Активний: API одразу почне віддавати 403, а історія заявок збережеться.

#Якщо щось не працює

#Чек-лист перед запуском трафіку

• Вебмайстра створено, вказано суму виплати, перемикач «Активний» увімкнено
• Тестовий запит через cURL повернув {"ok": true} і заявка видима в CRM
• Поле phone приходить у міжнародному форматі
• Передається landing — щоб розділяти сайти
• Передаються UTM-мітки з адреси сторінки
• Якщо відправка йде з браузера — домен лендінга додано в дозволені джерела CRM
• У CRM є статус із кодом new
• Кнопка відправки блокується на час запиту
• Після успішної відправки користувач бачить сторінку подяки