Admin API: конверсии и постбек

Через API доступны те же действия, что и в панели: типы конверсий, импорт конверсий из CSV и журнал доставки событий. Авторизация описана на странице Admin API: обзор и авторизация, формат запросов, ответов и ошибок — на странице Формат запросов, ответов и ошибок.

Методы группы

Если {id} в адресе — не UUID, ответ — 400 с кодом bad_request. При неактивной лицензии все методы группы отвечают 402 — см. Истёкшая лицензия.

Журнал принятых конверсий кампании отдаёт GET /api/v1/campaigns/{id}/conversions — см. Admin API: кампании.

Приём постбеков и лидов

Адреса /api/v1/postback, /api/v1/lead и /api/v1/lead-file принимают данные без токена, заголовок Api-Key им не нужен. Параметры постбека, статусы, выплата, txid и секрет источника описаны на странице Входящий постбек, повторы и корректировки — на странице ID транзакции, дубли и корректировки, приём данных из форм — на странице Приём лидов из форм.

Типы конверсий

Тип сопоставляет значение status из постбека партнёрской сети со статусом трекера. Правила сопоставления — на странице Типы конверсий.

Объект типа:

Список типов

GET /api/v1/conversion-types

Возвращает все типы команды в порядке создания. Права токена: full или reports:read. Параметров нет.

Ответ — код 200 и массив объектов типа. Если типов нет — пустой массив [].

Создать тип

POST /api/v1/conversion-types

Создаёт тип конверсии. Права токена: full.

Ответ — код 201 и объект созданного типа.

curl -X POST https://panel.example.com/api/v1/conversion-types \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Депозит","status":"sale","params":"deposit,ftd","send_postback":true}'

Ошибки: 422, код validation, сообщение name is required — нет поля name или тело не является JSON-объектом.

Изменить тип

PUT /api/v1/conversion-types/{id}

Заменяет настройки типа. Права токена: full.

Поля тела те же, что при создании, name обязателен. Передавайте объект целиком:

• пропущенные count_conv, count_revenue и send_postback становятся false;
• пропущенные params и color становятся пустой строкой;
• пропущенный или пустой status не меняется.

Ответ — код 200 и объект типа после изменения.

Ошибки:

Удалить тип

DELETE /api/v1/conversion-types/{id}

Удаляет тип. Права токена: full. Тела запроса нет.

Ответ — код 204 без тела. Если типа с таким ID нет — 404, код not_found. Что происходит с уже принятыми конверсиями — в разделе Удаление и изменение.

Импорт конверсий из CSV

Импорт идёт в два запроса: проверка возвращает token, импорт принимает те же данные вместе с этим token. Формат файла и правила для каждой колонки — на странице Импорт конверсий из CSV.

Тело обоих запросов:

Ответ обоих запросов — код 200:

Проверить CSV

POST /api/v1/conversion-import/preview

Проверяет файл и ничего не записывает. Права токена: full.

Если valid равен false, исправьте строки с полем error и повторите проверку. Тексты ошибок строк разобраны в разделе Если не получилось.

curl -X POST https://panel.example.com/api/v1/conversion-import/preview \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"csv":"sub_id,payout,tid,status\n1a2b3c4d5e6f,25.5,order-1001,sale\n","currency":"USD","notify":false}'

{
  "rows": [
    {"line": 2, "click_id": "1a2b3c4d5e6f", "payout": "25.5", "tid": "order-1001", "status": "sale"}
  ],
  "valid": true,
  "token": "1791021600.9f2c…",
  "applied": false,
  "notify": false
}

Ошибки:

Импортировать CSV

POST /api/v1/conversion-import/apply

Записывает конверсии из проверенного файла. Права токена: full.

Отправьте те же csv, currency и notify, что в проверке, и добавьте token. Он действует 15 минут и подходит только к этим данным и только пользователю, чей API-токен выполнил проверку. Изменили хотя бы одно поле — проверьте файл заново.

Строки обрабатываются по тем же правилам, что и входящий постбек. При applied: true у каждой строки есть итог:

• result со значением Принято (точный повтор не создаёт дубль) — конверсия принята;
• error со значением Не принято: HTTP <код>. Проверьте журнал postback; строку можно повторить с тем же tid. — строка не записана, остальные строки на это не влияют.

Если при импорте valid равен false, ничего не записано: applied равен false.

Ошибки — те же, что у проверки, и ещё две:

Доставки

Задача доставки — запись принятой конверсии в статистику, исходящий S2S-постбек или событие Facebook Conversions API. Что означают состояния и результаты и когда повтор безопасен — на странице Журнал доставки событий.

Объект задачи:

Последние доставки

GET /api/v1/deliveries

Возвращает последние 200 задач команды, новые первыми. Права токена: full. Параметров нет.

Ответ — код 200 и массив объектов задачи.

Поиск доставок

GET /api/v1/deliveries/search

Ищет задачи по клику, периоду и фильтрам. Права токена: full.

Период — не длиннее 93 дней. Если передан click_id без from и to, поиск идёт за всё время.

Ответ — код 200:

curl "https://panel.example.com/api/v1/deliveries/search?state=failed&kind=s2s&from=2026-10-01T00:00:00Z&to=2026-10-04T00:00:00Z&limit=50" \
  -H "Api-Key: <токен>"

{
  "items": [
    {
      "held_for_license": false,
      "id": "0b7e4c19-6a2d-4f85-b3c1-8d9e0f1a2b3c",
      "campaign_id": "c41a9e07-52bd-4f13-8a60-9d7e6f5a4b3c",
      "click_id": "1a2b3c4d5e6f",
      "kind": "s2s",
      "destination": "source",
      "state": "failed",
      "attempts": 1,
      "result_code": "http_404",
      "created_at": "2026-10-03T14:22:05.418332Z",
      "updated_at": "2026-10-03T14:22:06.102778Z",
      "next_attempt_at": "2026-10-03T14:22:05.418332Z"
    }
  ],
  "next_cursor": ""
}

Ошибки — код 400, code равен validation.

Повторить доставку

POST /api/v1/deliveries/{id}/retry

Возвращает задачу в очередь: state становится pending, отправка идёт сразу и в прежнем виде. Права токена: full. В адресе — id задачи, тела запроса нет.

Повторить можно только задачу в состоянии failed. Задачи с result_code, равным invalid_url, blocked_address, invalid_payload или invalid_kind, не повторяются.

Ответ — код 200:

{"ok": true}

Ошибки: 404, код not_found — задачи с таким ID нет, она не в состоянии failed или её нельзя повторить.