Документация по API

Запросы к API осуществляются по протоколу HTTPS. Базовый адрес функции — https://cpaw.cat/api/cpaw/<функция>.json. Расширение формата обязательно (.json).

Параметры можно передавать в GET или в POST. Ответ всегда выдаётся в формате JSON в кодировке UTF-8, HTTP-статус ответа всегда 200.

В тексте параметры-плейсхолдеры показаны в фигурных скобках: {id} — строка авторизации, {offer} — идентификатор оффера, {network} — идентификатор сети. В реальных запросах фигурные скобки не используются — только сами значения.

Авторизация

Ключ передаётся в параметре id в виде <идентификатор>-<ключ>:

• <идентификатор> — числовой ID вашего пользователя;
• <ключ> — ваш персональный API-ключ.

Успешный ответ содержит поле status: ok и данные в поле data:

{
    "status": "ok",
    "data": { "...": "..." }
}

Функция offers дополнительно возвращает рядом блок навигации nav — его состав описан в её разделе. Остальные функции отдают всё разом, без постраничной разбивки.

При ошибке ответ содержит status: error и поле error с кодом ошибки:

{
    "status": "error",
    "error": "auth"
}

Общие коды ошибок:

• auth — API-ключ не подходит;
• ban — пользователь заблокирован;
• access — доступ к выбранному ресурсу закрыт;
• request — некорректный запрос (например, не указано расширение формата);
• not-found — запрошенный объект не найден.

Каждая функция может возвращать и свои собственные коды ошибок, описанные в её разделе.

Идентификаторы типов событий применяются в запросах и ответах функций feed и offer:

Возвращает события ленты за указанный период. Максимум 1000 событий в ответе, отсортированы от самого свежего (по убыванию id).

Параметры

Ответ

Поле data содержит массив событий (лента упорядочена по времени). Поля каждого события:

{
    "status": "ok",
    "data": [
        {
            "id": 35400, "time": 1573291851, "tid": 4,
            "nid": 16, "oid": 6113, "gid": 19304,
            "date": "2019-11-09 09:30:51", "type": "Новая цель",
            "network": "Admitad", "offer": "Едадил [CPI, Android] RU",
            "goal": "Install on Android",
            "value": false, "old": false,
            "url": "https://cpaw.cat/offer/6113", "my": false
        }
    ]
}

Показывает список доступных для работы сетей. Входящих параметров нет. data — объект, ключ — идентификатор сети, значение — объект с полями:

{
    "status": "ok",
    "data": {
        "2": {
            "id": 2, "name": "Admitad", "domain": "www.admitad.com",
            "offer": true, "fav": true, "prio": 100,
            "geo": { "ru": "Россия", "de": "Германия" },
            "auths": [ "user", "key" ],
            "subscribed": true, "level": 2
        }
    }
}

Показывает списки офферов: общий каталог, приватные офферы, подписки. Поиск по URL, названию или похожим офферам.

Параметры

Ответ

Поле data содержит объект офферов (ключ — ID оффера), а рядом — блок навигации nav с постраничной разбивкой:

Поля оффера:

{
    "status": "ok",
    "data": {
        "2861": {
            "id": 2861, "active": true, "name": "Пояс AB Gymnic",
            "info": "https://cpaw.cat/offer/2861", "nid": 6, "network": "M1 Shop",
            "url": "http://m1-shop.ru/myoffers/add/453", "add": true,
            "time": 1571411245, "date": "2019-10-18 15:07:25", "first": 1571411245,
            "sub": true, "now": false, "goal": 3, "goals": 5,
            "geo": { "ru": "Россия", "ua": "Украина" },
            "private": false
        }
    },
    "nav": { "total": 100, "page": 1, "pages": 1, "show": 500, "offset": 0 }
}

Показывает все сведения об одном оффере. Найти оффер можно тремя способами:

• по offer — идентификатору оффера на стороне WatchCat (единственный способ для приватного оффера);
• по url — адресу оффера в партнёрской сети (только публичные);
• по network + uid — идентификатору сети и оффера на её стороне (только публичные).

Параметры

Если оффер не найден — ошибка not-found. При успехе data содержит поля оффера (те же, что в offers), а также:

Поля цели (goal):

Поля изменения (change): id, time, tid, gid, date, type, goal, value, old (см. feed).

{
    "status": "ok",
    "data": {
        "id": 2874, "active": true, "name": "Detoxic - средство от паразитов",
        "info": "https://cpaw.cat/offer/2874", "nid": 6, "network": "M1 Shop",
        "url": "http://m1-shop.ru/myoffers/add/897", "add": true,
        "time": 1571432786, "date": "2019-10-18 21:06:26", "first": 1571429261,
        "sub": true, "now": false,
        "private": false, "goals": 1, "goalactive": 1,
        "geo": { "tj": "Таджикистан" },
        "goal": {
            "11419": {
                "id": 11419, "active": true, "name": "Таджикистан", "type": "CPS",
                "code": "tj", "geo": "tj", "price": 200, "cash": 350,
                "up": 0, "cross": 0, "percent": 0, "currency": "rub"
            }
        },
        "change": [
            { "id": 24201, "time": 1571432786, "tid": 4, "gid": 11419,
              "date": "2019-10-18 21:06:26", "type": "Новая цель",
              "goal": "Таджикистан", "value": false, "old": false }
        ]
    }
}

Агрегаты по каждой публичной сети. Входящих параметров нет. data содержит:

• nets — массив сетей с полями id, name, url (каталог, отфильтрованный по сети), nomy (сеть не поддерживает добавление своих офферов), domain, offer (офферов), goal (целей), change (изменений);
• total — суммарные счётчики: networks, offers, goals, changes.

{
    "status": "ok",
    "data": {
        "nets": [
            {
                "id": 2, "name": "Admitad",
                "url": "https://cpaw.cat/offers?n=2", "nomy": true,
                "domain": "www.admitad.com", "offer": 5820, "goal": 14310, "change": 92034
            }
        ],
        "total": { "networks": 48, "offers": 99358, "goals": 229257, "changes": 3293186 }
    }
}

Глобальные счётчики. Входящих параметров нет. data:

{
    "status": "ok",
    "data": {
        "net": 48, "nets": 47,
        "offer": 99358, "offers": 42,
        "goal": 229257, "goals": 118,
        "change": 3293186, "changes": 1204
    }
}

Создаёт приватный оффер и включает его проверку раз в сутки. Источник оффера задаётся одним из трёх способов.

Параметры

При успехе data содержит id добавленного оффера (пригодится для edit / del).

Коды ошибок: not-found — оффер/сеть не найдены; no-private — сеть не поддерживает свои офферы; bad-auth — сеть отклонила данные авторизации; error — ошибка сохранения.

{ "status": "ok", "data": { "id": 1234 } }

Изменяет данные авторизации и частоту проверки. Отправляйте только те поля, которые хотите изменить; обязателен лишь offer.

Параметры

При успехе data содержит id и changed — список реально изменённых полей (пустой, если поле уже имело нужное значение).

Коды ошибок: bad-id — не указан offer; access — оффер не ваш; edit — ошибка сохранения.

{ "status": "ok", "data": { "id": 1234, "changed": [ "api" ] } }

Удаляет ранее добавленный приватный оффер и всю историю его проверки.

Параметры

Коды ошибок: bad-id — не указан offer; access — оффер не ваш.

{ "status": "ok", "data": { "id": 1234 } }

Добавляет подписку на публичный оффер. Функция идемпотентна: повторный вызов не создаёт дубль, но позволяет переключить флаг мгновенного уведомления.

Параметры

При успехе data содержит id и актуальное значение флага now.

Коды ошибок: bad-id — не указан offer; access — оффер приватный или сеть недоступна.

{ "status": "ok", "data": { "id": 1234, "now": 1 } }

Удаляет подписку на публичный оффер.

Параметры

Коды ошибок: bad-id — не указан offer; access — оффер приватный или сеть недоступна.

{ "status": "ok", "data": { "id": 1234 } }

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

Параметры

При успехе data содержит id сети и актуальный level.

Коды ошибок: bad-id — не указан network; access — сеть недоступна (приватная сеть для не-VIP).

{ "status": "ok", "data": { "id": 2, "level": 2 } }

Удаляет подписку на сеть. Разрешена всегда (в том числе если сеть стала приватной).

Параметры

Коды ошибок: bad-id — не указан network.

{ "status": "ok", "data": { "id": 2 } }