API-интерфейс

API фильтров и трекера позволяют работать с проверкой визитов, трафиком и статистикой. Чтобы получить API-токен, зайдите на страницу своего профиля в системе. Взаимодействие с сервисом осуществляется по протоколу HTTP, статус ответа всегда 200. Стандартный формат запроса - GET или "чистый" POST (form-urlencoded). При отправке в JSON не забывайте заголовок Content-type: application/json. Формат результата - JSON. Ограничений на количество запросов нет.

Далее по тексту важные параметры указаны в фигурных скобках:

• {token} - ваш API-ключ из личного кабинета, например 123-abdce.
• {flow} - символьный идентификатор потока из списка, например ef1c.
• {click} - символьный идентификатор клика из трекера, например ca1337.

Важно! При использовании ссылок и данных фигурные скобки указывать не нужно, только сами значения!

Фильтрация

Функции фильтрации позволяют вам максимально быстро проверять визиты на ваши сайты. Они вынесены в отдельный интерфейс, который имеет минимальное время ответа и максимальную производительность.

Проверка визита

URL: https://www.altercpa.one/fltr/{user}-{key}-{id}

В адресе функции вместо {user} и {key} укажите API ID и ключ из профиля, вместо {id} указывается идентификатор добавленного вами фильтр-сайта. Конкретный URL вы можете получить, нажав на кнопку "Инструкция" соответствующего сайта в вашем личном кабинете.

Чтобы проверить свой визит, вам необходимо отправить POST-запрос на указанный выше URL. В качестве тела запроса передайте поля своего массива $_SERVER - мы проанализируем их и покажем ответ в формате JSON. Успешный ответ включает в себя поля status, action и url. Поле status всегда содержит значение ok. Поле action ответа будет содержать allow или deny в зависимости от результатов проверки, поле url будет содержать соответствующий URL-адрес. В ошибочном ответе поле status будет содержать error, код ошибки будет указан в поле error.

POST-часть запроса должна быть в формате x-www-form-urlencoded, формат JSON не поддерживается. Мы анализируем следующие поля из массива $_SERVER:

HTTP_USER_AGENT, HTTP_ACCEPT, HTTP_ACCEPT_CHARSET, HTTP_ACCEPT_ENCODING, HTTP_ACCEPT_LANGUAGE, HTTP_AUTHORIZATION, HTTP_CACHE_CONTROL, HTTP_CONNECTION, HTTP_CONTENT_DISPOSITION, HTTP_DATE, HTTP_EXPECT, HTTP_FROM, HTTP_HOST, HTTP_IF_MATCH, HTTP_IF_MODIFIED_SINCE, HTTP_IF_NONE_MATCH, HTTP_IF_RANGE, HTTP_IF_UNMODIFIED_SINCE, HTTP_MAX_FORWARDS, HTTP_PRAGMA, HTTP_PROXY_AUTHORIZATION, HTTP_RANGE, HTTP_REFERER, HTTP_TE, HTTP_TRAILER, HTTP_TRANSFER_ENCODING, HTTP_UPGRADE, HTTP_VIA, HTTP_X_FORWARDED_FOR, REMOTE_ADDR, REMOTE_PORT, REQUEST_METHOD, REQUEST_URI, QUERY_STRING, HTTP_CF_CONNECTING_IP, HTTP_CLIENT_IP, HTTP_X_REAL_IP, HTTP_X_PURPOSE, HTTP_X_FB_HTTP_ENGINE

Результатом выполнения функции является ассоциативный массив:

Пример реализации отправки запроса:

$curl = curl_init( 'https://www.altercpa.one/fltr/123-abcd-45' );
curl_setopt( $curl, CURLOPT_POST, true );
curl_setopt( $curl, CURLOPT_POSTFIELDS, $_SERVER );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
$result = curl_exec( $curl );
curl_close( $curl );
$result = $result ? json_decode( $result, true ) : [];
if ( isset( $result['action'] && $result['action'] == 'allow' ) {
    include( 'target-index.php' );
} else include( 'dummy-index.php' );

Пример успешного ответа сервера:

{
    "status": "ok",
    "action": "allow",
    "url": "http://black.site/url"
}

Пример ошибочного ответа сервера:

{
    "status": "error",
    "error": "access-denied"
}

Настройка кампании

URL: https://www.altercpa.one/api/filter/set.json?id={token}&domain={host}

Функция изменяет параметры кампании фильтрации или создаёт новую кампанию. Если передан идентификатор кампании в поле uid, функция будет изменять существующую кампанию по этому идентификатору. Если идентификатор не передан, но передан домен кампании в поле domain, функция попытается найти кампанию с указанным доменом, а если её нет - создаст новую.

Функция может принимать на вход следующие параметры:

Результатом выполнения функции является ассоциативный массив:

Пример успешного ответа сервера:

{
    "status": "ok",
    "id": 4567,
    "api": "https://www.altercpa.one/fltr/123-654b807372f614e64b9-4567"
}

Пример ошибочного ответа сервера:

{
    "status": "error",
    "error": "no-domain"
}

Список кампаний

URL: https://www.altercpa.one/api/filter/list.json?id={token}

Функция возвращает список кампаний, которые созданы в разделе фильтрации трафика. Функция не имеет дополнительных параметров.

Результатом выполнения функции является список ассоциативных массивов со следующими полями:

Пример успешного ответа сервера:

[
    {
        "id": 4567,
        "api": "https://www.altercpa.one/fltr/123-654b807372f614e64b9-4567",
        "domain": "pretty-domain.com",
        "mode": 0,
        "stats": {
            "click": 180,
            "black": 123,
            "white": 57,
            "leads": 11,
            "approve": 6,
            "cancel": 1,
            "cash": 387.44,
            "cr": 8.94,
            "epc": 3.15,
            "appr": 54.55
        }
    },
    ...
]

Получение данных кампании

URL: https://www.altercpa.one/api/filter/get.json?id={token}&domain={host}

Функция возвращает данные кампании фильтрации. Если передан идентификатор кампании в поле uid, функция будет извлекать кампанию по этому идентификатору. Если передан домен кампании в поле domain, функция будет пытаться отыскать кампанию с указанным доменом.

Функция может принимать на вход следующие параметры:

Результатом выполнения функции является ассоциативный массив со следующими полями:

Пример успешного ответа сервера:

{
    "id": 4567,
    "api": "https://www.altercpa.one/fltr/123-654b807372f614e64b9-4567",
    "domain": "pretty-domain.com",
    "mode": 0,
    "geo": [ "ru", "ua", "by" ],
    "mblack": 1,
    "black": "https://my-main-page.com/",
    "mwhite": 0,
    "white": "http://natribu.org/",
    "trash": 0,
    "proto": 0,
    "mobile": 0,
    "os": [],
    "browser": [],
    "ignore": false,
    "ipmain": false,
    "lang": false,
    "adid": false,
    "list": [],
    "langs": [],
    "nogeo": [],
    "uwl": [],
    "ubl": [],
    "wl": [],
    "stats": {
        "click": 180,
        "black": 123,
        "white": 57,
        "leads": 11,
        "approve": 6,
        "cancel": 1,
        "cash": 387.44,
        "cr": 8.94,
        "epc": 3.15,
        "appr": 54.55
    },
    "postback": {
        "new": "https://www.altercpa.one/api/filter/postback.json?id=123-654b807372f614e64b9&uid=11&status=new",
        "approve": "https://www.altercpa.one/api/filter/postback.json?id=123-654b807372f614e64b9&uid=11&status=approve",
        "paid": "https://www.altercpa.one/api/filter/postback.json?id=123-654b807372f614e64b9&uid=11&status=approve&payout={payout}",
        "cancel": "https://www.altercpa.one/api/filter/postback.json?id=123-654b807372f614e64b9&uid=11&status=cancel"
    }
}

Пример ошибочного ответа сервера:

{
    "status": "error",
    "error": "no-site"
}

Удаление кампании

URL: https://www.altercpa.one/api/filter/del.json?id={token}&domain={host}

Функция удаляет кампанию фильтрации. Если передан идентификатор кампании в поле uid, функция будет удалять кампанию по этому идентификатору. Если передан домен кампании в поле domain, функция будет пытаться отыскать кампанию с указанным доменом.

Функция может принимать на вход следующие параметры:

Результатом выполнения функции является ассоциативный массив:

Пример успешного ответа сервера:

{
    "status": "ok",
    "id": 4567
}

Пример ошибочного ответа сервера:

{
    "status": "error",
    "error": "no-site"
}

Скачать файл фильтрации

URL: https://www.altercpa.one/api/filter/make.json?id={token}&domain={host}

Функция скачивает готовый файл для кампании фильтрации. Если передан идентификатор кампании в поле uid, функция будет извлекать кампанию по этому идентификатору. Если передан домен кампании в поле domain, функция будет пытаться отыскать кампанию с указанным доменом. Ответом функции является файл index.php.

Функция может принимать на вход следующие параметры:

Результатом выполнения функции является файл index.php в случае успеха или ассоциативный массив в случае ошибки:

Заблокировать IP-адрес или заголовок

URL: https://www.altercpa.one/api/filter/block.json?id={token}&list={list}&ip={ip}

Функция добавляет данные в выбранный персональный чёрный список. Может блокировать как IP-адреса и диапазоны, так и заголовки. Содержимое полей и используемые идентификаторы описаны в документации по чёрным спискам.

Функция может принимать на вход следующие параметры:

Результатом выполнения функции является ассоциативный массив:

Пример успешного ответа сервера:

{
    "status": "ok",
    "id": 1234567
}

Пример ошибочного ответа сервера:

{
    "status": "error",
    "error": "bad-list"
}

Отправить постбек в мини-трекер

URL: https://www.altercpa.one/api/filter/postback.json?id={token}&uid={uid}&status={status}

Функция отвечает за обслуживание встроеного мини-трекера. Она увеличивает счётчик лидов в статусе ожидание, аппрув и отмена, а также наращивает сумму заработка. Не поддерживает какую-либо дедупликацию событий.

Функция может принимать на вход следующие параметры:

Результатом выполнения функции является ассоциативный массив:

Пример успешного ответа сервера:

{
    "status": "ok"
}

Пример ошибочного ответа сервера:

{
    "status": "error",
    "error": "bad-status"
}

Интеграция с трекером

Функции интеграции отвечают за подключение сторонних сервисов и передачу данных о конверсиях.

Постбек

URL: https://www.altercpa.one/api/tracker/postback.json?id={token}&click={click}

Самая главная функция взаимодействия с трекером. Создаёт новый или изменяет существующий лид по отправленным ID клика или потока. Вы можете использовать два варианта вызова:

• Стандартный вариант работы: с параметром click. Данные для лида берутся из ID клика. Используется по умолчанию, рекомендуется применять именно такой подход.
• Резервный вариант работы: с параметрами flow и subid. Данные для лида берутся из ID потока, уникальность запроса определяется по параметру subid. Подходит для случаев, где нет понятия клика и перехода по ссылке, например для интеграции приложений.

Функция может принимать на вход следующие параметры:

Результатом выполнения функции является ассоциативный массив:

Пример успешного ответа сервера:

{
    "status": "ok",
    "id": 1337,
    "create": true,
    "stage": "new"
}

Пример ответа сервера с ошибкой:

{
    "status": "error",
    "error": "no-changes"
}

Импорт расходов

URL: https://www.altercpa.one/api/tracker/spend.json?id={token}

Функция задаёт цену клика для трафика по указанным условиям. Позволяет использовать функционал расчёта ROI. Данные могут передаваться как в GET, так и в POST-запросе. В запросе обязательно должны присутствовать параметры cpc или cost и хотя бы одно условие (даты, поток, UTM-метки).

Функция может принимать на вход следующие параметры:

Вы также можете одновременно обновлять несколько ценников одним запросом, для этого объедините все запросы в массив batch и отправьте его через POST, например:

{
    "batch": [
        {
            "flow": "face",
            "cost": 1984,
            "currency": "usd"
        },
        {
            "from": "2020-04-04 00:00:00",
            "to": "2020-04-07 23:59:59",
            "cpc": 1.337,
            "currency": "eur"
        }
    ]
}

Результатом выполнения функции является ассоциативный массив:

Пример успешного ответа сервера:

{
    "status": "ok",
    "ok": 1,
    "bad": 0
}

Пример ответа сервера с ошибкой:

{
    "status": "error",
    "error": "empty"
}

Статистика трекера

Функции статистики предоставляют доступ к отчётам по лидам и кликам.

Список лидов

URL: https://www.altercpa.one/api/tracker/leads.json?id={token}

Функция извлекает список лидов и выдаёт его в виде ассоциативного массива в поле leads. У функции нет формальных лимитов на количество выводимых лидов, но не рекомендуется выгружать больше тысячи лидов за раз. Если вы получили ошибку 500, значит на ваш запрос не хватило памяти, нужно уменьшить период запроса.

Функция может принимать на вход следующие GET-параметры фильтрации:

Результатом выполнения функции является ассоциативный массив:

Внутри поля leads лиды представлены ассоциативным массивом с полями:

Пример успешного ответа сервера:

{
    "status": "ok",
    "leads": [
        {
            "id": 1,
            "time": 1691303223,
            "click": "ac13",
            "uid": "c1vvkg272m16",
            "flow": "ecb4",
            "way": 123,
            "site": 42,
            "siteurl": "https://meow.pro/c8/cfb72fe561f0/",
            "filter": 0,
            "status": "approve",
            "custom": "Confirmed",
            "goal": "paid",
            "price": 18,
            "currency": "usd",
            "ip": "12.34.56.78",
            "geo": "de",
            "name": "Hans",
            "phone": "+49 (30) 226-511-83",
            "email": "[email protected]",
            "comment": "Confirmed on sunday",
            "meta": {
                "foo": "bar",
                "bar": "foo"
            },
            "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Safari\605.1.15",
            "referer": "https://meow.pro/c8/cfb72fe561f0/?subid=purr",
            "adid": "bf9d4aa8-4979-11ee-94c6-005056aec456",
            "data1": "wj80b89eit8epaarikhe2oge",
            "data2": false,
            "utm_source": "fb",
            "utm_campaign": "1013444211662",
            "utm_content": "432211555332166",
            "utm_term": false,
            "utm_medium": false,
            "domain": "meow.pro",
            "subid": "purr"
        },
        ...
    ]
}

Пример ответа сервера с ошибкой:

{
    "status": "error",
    "error": "payment-required"
}

Статистика по кликам

URL: https://www.altercpa.one/api/tracker/stats.json?id={token}

Функция собирает общую статистику по количеству кликов и лидов с разбивкой по целям за выбранный период по указанному критерию.

Функция может принимать на вход следующие GET-параметры фильтрации:

Результатом выполнения функции является ассоциативный массив:

Массив stats и поле total представляют собой ассоциативный массив:

Пример успешного ответа сервера:

{
    "status": "ok",
    "stats": {
        "20230805": {
            "id": 20230805,
            "name": "2023-08-05",
            "click": 44,
            "unique": 22,
            "total": 6,
            "cv": 4,
            "cn": 1,
            "ch": 1,
            "ca": 2,
            "cc": 0,
            "ct": 2,
            "mh": 20.0,
            "ma": 135.0,
            "mt": 155.0,
            "cr": 18.2,
            "epc": 6.75,
            "appr": 66.7,
            "app": 33.3
        },
        ...
    },
    "total": {
        "click": 175,
        "unique": 58,
        "total": 25,
        "cv": 23,
        "cn": 11,
        "ch": 8,
        "ca": 9,
        "cc": 0,
        "ct": 2,
        "mh": 160.0,
        "ma": 1200.0,
        "mt": 1360.0,
        "cr": 5.17,
        "epc": 12.3,
        "appr": 46.7,
        "app": 31.0
    }
}

Пример ответа сервера с ошибкой:

{
    "status": "error",
    "error": "no-item"
}