Adset.ProAdset.ProKnowledge base
RUEN
To app
Home/Публічне HTTP API/Потоки

Потоки

Потік — конкретне посилання офера, на яке трекер відправляє відвідувача: зовнішній URL партнерки, внутрішній лендинг або Telegram-канал через бота. Один офер може мати кілька потоків (різні лендинги, гео, PWA). У кампанії потоки збираються в набори sets[].flows[]. У кабінеті це розділ Трекер → Посилання на офер (див. Посилання на офер).

Отримання токена, загальний формат відповідей, параметри списків і помилки — в головній статті розділу.

Скоупи

Скоуп Доступ В дефолті PAT
api:flows читання: список і картка потоку так
api:flows:write створення і редагування ні

Ендпойнти

Метод Шлях Скоуп RBAC-право
GET /api/flows api:flows flow:list
POST /api/flows api:flows:write flow:create
GET /api/flows/{id} api:flows flow:read
PATCH /api/flows/{id} api:flows:write flow:update

Усі права є у всіх ролей. Видимість: ADMIN — всі потоки, TEAM_OWNER/TEAM_LEAD/TECH — потоки команди, BUYER — свої і доступні за налаштуваннями доступу. Чужий потік → 404.

Параметри списку GET /api/flows

Поля
Фільтри filter[...] _id, cpa, offer, team, user, name, hostingType, url, isActive, created, updated, tags
Сортування sort name, hostingType, url, isActive, created, updated
Populate за замовчуванням user (name, email, avatar), team (name), cpa (name), offer (name, country), tags 
# всі активні зовнішні потоки офера
curl -G 'https://adset.pro/api/flows' \
  -H 'Authorization: Bearer pat_…' \
  --data-urlencode 'pageSize=100' \
  --data-urlencode 'filter[offer]=6650f0e1d2c3b4a5f6e7d8c8' \
  --data-urlencode 'filter[hostingType]=external' \
  --data-urlencode 'filter[isActive]=true'

# знайти потоки за доменом в URL
curl -G 'https://adset.pro/api/flows' \
  -H 'Authorization: Bearer pat_…' \
  --data-urlencode 'filter[url][contains]=partner.example'

Об'єкт потоку

Поле Тип Опис
id string ObjectId
name string назва (обов'язково при створенні)
description string опис
isActive boolean за замовчуванням true
cpa id | { id, name } партнерська мережа (обов'язково при створенні)
offer id | { id, name, country } офер (обов'язково при створенні)
hostingType external | internal | telegram куди веде потік: зовнішнє посилання; внутрішній лендинг з конструктора; Telegram-канал з атрибуцією через бота. За замовчуванням external
url string цільовий URL. Обов'язковий і має бути валідним для external; для internal і telegram може бути порожнім. Макроси — в фігурних дужках, наприклад {click_id}
landing id | null лендинг для hostingType = internal
refference id | об'єкт | null батьківський потік, з якого береться маппінг click_id (для пов'язаних потоків)
telegram об'єкт налаштування Telegram-атрибуції: { bot, channelId, welcomeMessage, attributionWindowDays, inviteLink }; attributionWindowDays — 1–7, за замовчуванням 2
user, team id | об'єкт власник і команда
tags[] id[] | об'єкти теги
created, updated date тільки для читання

Об'єкт telegram присутній у відповіді завжди, навіть у зовнішніх потоках — з порожніми значеннями за замовчуванням.

POST /api/flows — створити потік

Обов'язкові поля: name, cpa, offer. Мережа і офер повинні бути доступні власнику токена (інакше 404). Команда і власник за замовчуванням успадковуються від CPA-мережі.

// POST /api/flows
{
  "name": "DE — landing v1",
  "cpa": "65f0a1b2c3d4e5f6a7b8c9d0",
  "offer": "6650f0e1d2c3b4a5f6e7d8c8",
  "hostingType": "external",
  "url": "https://partner.example/offer?aff=123&sub1={click_id}",
  "description": "",
  "isActive": true,
  "tags": []
}

Призначення власника:

Роль токена Що враховується
ADMIN user і team з тіла, якщо передані обидва; інакше — власник і команда CPA-мережі
TEAM_OWNER, TEAM_LEAD, TECH user з тіла (команда — від CPA-мережі)
BUYER завжди стає власником сам

Відповідь — 201 Created, заголовок Location: /flows/{id}, тіло — об'єкт потоку в конверті { data, traceId }.

Для hostingType = internal передайте landing (id лендингу); для telegram — об'єкт telegram з bot і channelId, посилання-запрошення генерується ботом (див. Атрибуція трафіку в Telegram-канали).

PATCH /api/flows/{id} — змінити потік

Усі поля необов'язкові; передавайте тільки те, що змінюєте — решта зберігається.

// PATCH /api/flows/6650f0e1d2c3b4a5f6e7d8c9
{
  "name": "DE — landing v2",
  "url": "https://partner.example/offer?aff=123&sub1={click_id}&sub2={campaign_id}",
  "isActive": false,
  "hostingType": "external",
  "tags": ["66a0…"]
}

Інші змінювані поля: description, refference (id батьківського потоку або null), landing, telegram{…}, user (зміна власника — тільки на користувача, доступного власнику токена).

Відповідь 200 OK:

{
  "data": {
    "id": "6650f0e1d2c3b4a5f6e7d8c9",
    "name": "DE — landing v2",
    "description": "",
    "isActive": false,
    "url": "https://partner.example/offer?aff=123&sub1={click_id}&sub2={campaign_id}",
    "hostingType": "external",
    "refference": null,
    "landing": null,
    "telegram": { "bot": null, "channelId": null, "welcomeMessage": "", "attributionWindowDays": 2, "inviteLink": null },
    "cpa": "65f0a1b2c3d4e5f6a7b8c9d0",
    "offer": "6650f0e1d2c3b4a5f6e7d8c8",
    "user": "64a0…",
    "team": "64b0…",
    "tags": ["66a0…"],
    "created": "2026-09-20T10:00:00.000Z",
    "updated": "2026-10-13T10:05:00.000Z"
  },
  "traceId": "01HX…"
}

Масова заміна домену в URL потоків і зміна мережі з підстановкою шаблону параметрів робляться іншими способами: перше — тільки в кабінеті, друге — через PATCH /api/cpa/{id}?changeAllUrl=true.

Помилки

HTTP Коли
403 forbidden + Insufficient OAuth scope. Required: api:flows:write PAT з дефолтними read-скоупами викликає POST/PATCH
404 notFound потоку немає або він чужий; cpa/offer/user недоступні власнику токена
422 validationError немає name, cpa або offer; hostingType поза списком; невалідний url у потоку external (Flow Url not valid в details[]); attributionWindowDays поза 1–7

Пов'язані статті