Admin API: офферы

На странице 22 метода для работы с офферами. Все они требуют токен с доступом Полный доступ (full). Авторизация описана на странице Admin API: обзор и авторизация, формат запросов и общие коды ошибок — на странице Формат запросов, ответов и ошибок.

Объект оффера

Методы списка, чтения, создания, изменения и копирования возвращают оффер в одном виде.

Значения типов доставки, моделей выплаты и статусов разобраны на странице Офферы, лимит и резервный оффер — на странице Суточный лимит продаж и резервный оффер, php_network — на странице PHP в локальных страницах и доступ в сеть.

Если оффера с указанным id нет, любой метод с {id} в адресе отвечает 404 с кодом not_found. На id не в формате UUID ответ — 400 с кодом bad_request.

Офферы

Список офферов

GET /api/v1/offers

Возвращает массив офферов, новые первыми. Параметров и постраничности нет. Удалённые офферы в список не входят. Ответ — код 200.

Получить оффер

GET /api/v1/offers/{id}

Возвращает один оффер. Ответ — код 200.

Создать оффер

POST /api/v1/offers

Создаёт оффер. Владельцем становится пользователь, создавший токен.

Остальные поля из раздела Объект оффера, кроме id, seq и owner_id, передаются по желанию. Пропущенные получают значения по умолчанию.

curl -X POST https://panel.example.com/api/v1/offers \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Offer PL","url":"https://offer.example.com/?sub={subid}","payout":12.5,"country":"PL","daily_cap":50,"cap_timezone":"Europe/Warsaw"}'

Ответ — код 201 и созданный оффер.

Ошибки с кодом 422 и validation:

Изменить оффер

PUT /api/v1/offers/{id}

Меняет переданные поля. Поля, которых нет в теле, сохраняют текущие значения. Переданный null очищает country, daily_cap, network_id и overflow_offer_id. Группа снимается пустой строкой в group_name, значения — пустым массивом в values. Пустая строка в storage, delivery_type, payout_type, payout_param, currency и state оставляет прежнее значение, в cap_timezone — возвращает UTC.

Поля и ошибки те же, что при создании. Проверки применяются к итоговому офферу. Ответ — код 200 и обновлённый оффер.

Удалить оффер

DELETE /api/v1/offers/{id}

Перемещает оффер и его файлы в корзину. Ответ — код 204 без тела. Восстановление — на странице Admin API: корзина.

Копии и доступ

Клонировать оффер

POST /api/v1/offers/{id}/clone

Создаёт копию оффера. К названию добавляется « (копия)». У локального оффера копируются и файлы.

Ответ — код 201 и новый оффер.

Раздать копии сотрудникам

POST /api/v1/offers/{id}/share-clone

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

Ответ — код 200 и объект с массивом results. В каждом элементе — user_id, login и offer_id новой копии. Если копию создать не удалось, вместо offer_id приходит error: «пользователь не найден», «не удалось клонировать» или «не удалось скопировать файлы».

Пустой список даёт 422 с сообщением «не выбран ни один сотрудник».

Кому открыт оффер

GET /api/v1/offers/{id}/shares

Возвращает объект с массивом user_ids — пользователи, которым оффер открыт для просмотра. Ответ — код 200.

Открыть оффер пользователям

POST /api/v1/offers/{id}/shares

Заменяет список целиком. Пустой массив закрывает доступ всем.

Ответ — код 204 без тела.

Группы офферов

Группа — это значение поля group_name. Чтобы добавить оффер в группу, передайте название в group_name при создании или изменении оффера. Отдельные методы переименовывают и удаляют группу сразу у всех её офферов.

Переименовать группу

PUT /api/v1/offer-groups?name=<текущее название>

curl -X PUT "https://panel.example.com/api/v1/offer-groups?name=Nutra" \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Nutra PL"}'

Ответ — код 200 и {"updated": 4}, где число — сколько офферов изменено.

Удалить группу

DELETE /api/v1/offer-groups?name=<название>

Снимает группу с офферов. Сами офферы остаются. Тело не нужно. Ответ — код 200 и {"updated": N}.

Ошибки обоих методов — 422 с кодом validation: «name обязателен», если нет параметра в адресе. У переименования ещё две: «некорректное тело запроса», если тело не JSON-объект, и «новое имя группы обязательно», если в теле пустое название.

Файлы локального оффера

Пути файлов указываются относительно папки оффера, через /, например css/style.css. После первой загрузки архива, файла или сохранения файла оффер переходит в storage: local. Как трекер отдаёт такие страницы — на странице Локальный хостинг.

Загрузить архив

POST /api/v1/offers/{id}/upload

Принимает ZIP в формате multipart/form-data и заменяет им все файлы оффера. Журнал лидов оффера при этом сохраняется.

curl -X POST https://panel.example.com/api/v1/offers/7c9e6679-7425-40de-944b-e07fc1f90ae7/upload \
  -H "Api-Key: <токен>" \
  -F "[email protected]"

Если у оффера уже были файлы, перед заменой они сохраняются как версия.

Ответ — код 200 и объект с массивом files. Элемент списка: path — путь, size — размер в байтах, dir — всегда false. Список отсортирован по пути, папки отдельными строками не выводятся.

Если архив не принят, прежние файлы оффера остаются на месте. Лимиты и ошибки — в разделе Лимиты и ошибки загрузки.

Список файлов

GET /api/v1/offers/{id}/files

Возвращает объект с массивом files в том же виде. У оффера без файлов массив пустой. Ответ — код 200.

Догрузить файлы

POST /api/v1/offers/{id}/files

Добавляет файлы к уже загруженным, формат — multipart/form-data. Файл с тем же путём заменяется, остальные не затрагиваются.

Ответ — код 200 и объект: files — полный список файлов, saved — пути сохранённых, storage — local.

Прочитать файл

GET /api/v1/offers/{id}/file?path=<путь>

Возвращает содержимое файла размером до 5 МБ.

Ответ — код 200 и объект: path, content — содержимое строкой, utf8 — false, если файл не текст в UTF-8.

Сохранить файл

PUT /api/v1/offers/{id}/file

Создаёт или перезаписывает текстовый файл. Тело — JSON.

Ответ — код 200 и {"ok": true, "storage": "local"}.

Удалить файл

DELETE /api/v1/offers/{id}/file?path=<путь>

Удаляет один файл. Ответ — код 204 без тела.

Переименовать файл

POST /api/v1/offers/{id}/rename

Переименовывает файл или переносит его в другую папку. Файл, который уже есть по новому пути, не перезаписывается. Журнал лидов leads.php и имена с точкой в начале не переименовываются: ответ — 400.

Ответ — код 200 и {"ok": true}. Без одного из полей — 400 с сообщением «нужны исходный и новый путь».

Ошибки методов с файлами

Версии и архив

Версия — сохранённая копия файлов оффера. Трекер хранит 10 последних версий оффера, более старые удаляются при сохранении новой. Журнал лидов и файлы с точкой в начале имени в версии и в архив не попадают. Сохранение версии и скачивание архива рассчитаны на оффер, у которого есть файлы. Работа с версиями в панели — на странице Редактор файлов, версии и экспорт.

Список версий

GET /api/v1/offers/{id}/versions

Возвращает массив версий, новые первыми. Поля: id, created_at — время создания в UTC, size — размер в байтах. Если версий нет, массив пустой. Ответ — код 200.

Сохранить версию

POST /api/v1/offers/{id}/versions

Сохраняет текущие файлы как новую версию. Тело не нужно. Ответ — код 201 и объект версии.

Восстановить версию

POST /api/v1/offers/{id}/versions/{version}/restore

Заменяет файлы оффера файлами версии. В {version} подставьте id из списка версий. Перед заменой текущие файлы сохраняются как новая версия. Журнал лидов остаётся на месте. Тело не нужно. Ответ — код 200 и {"ok": true}.

Скачать архив

GET /api/v1/offers/{id}/archive

Отдаёт текущие файлы оффера одним ZIP-файлом page.zip. Ответ — код 200 с типом application/zip.

curl https://panel.example.com/api/v1/offers/7c9e6679-7425-40de-944b-e07fc1f90ae7/archive \
  -H "Api-Key: <токен>" \
  -o page.zip

Сохранение версии и скачивание архива отвечают 413, если в оффере больше 10 000 файлов или больше 1 ГБ.

Лимиты и ошибки загрузки

Требования к архиву — на странице Локальный хостинг.