Публичный API и API-ключи

Публичный API нужен, когда стандартных интеграций мало: своя CRM, сайт, мобильное приложение или 1С. Через него можно создавать лиды и двигать их по статусам программно.

API-ключи

• Ключи выпускаются на уровне компании в настройках.
• Запросы авторизуются ключом; на ключи действует ограничение частоты (rate-limit), чтобы защитить систему от перегрузки.
• Ключ — это секрет: храните его на стороне сервера, не публикуйте в браузере или мобильном приложении.

Что умеет API

• Создавать лиды (с привязкой к офферу/партнёру по правилам атрибуции).
• Двигать лиды по статусам воронки.
• Регистрировать оплаты клиентов — по ним партнёру начисляется вознаграждение, если в оффере включены регулярные начисления.

Этого достаточно, чтобы «прокинуть» заявки с вашего сайта или из внешней системы прямо в кабинет.

Оплаты клиентов и защита от задвоения

Если вы платите партнёрам за повторные оплаты, ваш биллинг должен присылать каждую оплату в ручку POST /public/leads/{id}/payments.

Обязательно передавайте externalId — ваш собственный номер платежа (номер счёта, id транзакции). Это ключ защиты от задвоения: если вебхук доставится повторно, система вернёт уже существующую оплату и не начислит партнёру второй раз. Без externalId каждый ретрай будет считаться новой оплатой.

Возврат денег клиенту — DELETE /public/leads/{id}/payments/{paymentId}: начисление снимается с баланса партнёра.

Документация (Swagger)

Полное описание ручек, параметров и примеров — в публичном Swagger:

• Публичная документация API: /public/docs

Там же можно посмотреть схемы запросов/ответов и коды ошибок.

Типовой сценарий

1. Выпустите API-ключ в настройках.
2. Откройте /public/docs, найдите ручку создания лида.
3. Отправьте запрос с ключом — лид появится в разделе «Лиды».
4. При смене статуса в вашей системе вызывайте ручку движения статуса.

Единый формат ошибок и коды (VALIDATION_ERROR, UNAUTHORIZED, RATE_LIMITED и др.) описаны в Swagger — ориентируйтесь на поле error.code для обработки на своей стороне.