WebEffector.ru REST API

Наш API использует REST подход, в основе которого лежит идея сущностей и операций над ними.

Токен

Все операции над сущностями должны производиться только авторизованным пользователем. Для этого вам необходимо получить токен и передавать его при каждом обращении к сервису как часть URL. Если вы забудете передать токен, то сервис вернет HTTP статус 403 Forbidden.

Например, для получения списка кампаний URL должен быть следующим: http://api.webeffector.ru/seo?token=d41d8cd98f00b204e9800998ecf8427e

Баллы

Для уменьшения нагрузки на сервер и защиты от атак введено использование бальной системы. Каждый день вам начисляется определённое количество баллов, оно зависит от вашего дневного расхода и времени пользования системой. При выполнении различных операций с вашего виртуального счета снимаются баллы. Количество снимаемых баллов зависит от того, какая операция была запрошена. В случае исчерпания доступных баллов сервис будет возвращать HTTP статус 402 Payment Required на все запросы. В этом случае вы можете дождаться следующего дня, либо приобрести платные баллы. Оставшиеся баллы можно получить в заголовках X-Day-Points и X-Balance-Points отдаваемых при любом запросе.

Пользовательские идентификаторы

В целях вашего удобства сервис не назначает идентификаторов для объектов. Вы сами должны передать любой удобный для вас идентификатор.

Идентификатор должен быть уникальным в рамках вашего пользователя. Удалённые идентификаторы недоступны для повторного использования.

Ошибки

Ошибка 400 — ваш запрос содержит неверные данные. Если отправленные вами данные не прошли проверку валидации, то сервис возвращает эти данные и добавляет к ним поле errors с описанием ошибок.
Ошибка 402 — у вас недостаточно баллов для запросов к API, вам необходимо сделать паузу до следующего дня или приобрести платные баллы.
Ошибка 403 — вы указали неверный токен или пытаетесь поставить в очередь слишком много задач.
Ошибка 404 — вы указали неверные идентификаторы объектов в URL запроса.
Ошибка 5xx — скорее всего, мы выполняем сервисные работы на сервере, и вам нужно просто попробовать выполнить запрос ещё раз через 1 минуту. Мы старались сделать API максимально STATELESS, так что у вас не должно возникнуть никаких проблем.

При отправке невалидных данных сервис также списывает с вас баллы.

Начало работы

Для получения тестового доступа к API необходимо письмо с темой "Доступ к АПИ для пользователя username" на help (at) webeffector.ru. Обычно активация доступа к API занимает несколько рабочих дней. Так же можно активировать доступ и задать интересующие вопросы в jabber конференции по адресу conference.jabber.webeffector.ru.

Аутентификация в системе

Получение токена

Для получения токена необходимо послать POST запрос на URL http://api.webeffector.ru/token, в теле которого передать логин и пароль.

Пример запроса:

{
        "login" : "user",
        "password" : "test"
}

Возвращаемое значение

{
        "token": "afcb768dbac99sanasdn9as8das8das",
        "access": "rwd"
}

Ошибки

При неправильном логине или пароле возвращается HTTP статус 400 Bad Request
Если логин или пароль не указаны, то возвращается HTTP статус 403 Forbidden

Управление кампаниями и продвижениями

Получение списка кампаний

GET http://api.webeffector.ru/seo

[{
    "id": "E1",
    "region": "Москва",
    "name": "Продвижение сайта webeffector.ru",
    "url": "http://webeffector.ru/",
    "mode": "DEFAULT",
    "pos": ["yandex_ru", "google_ru"],
    "top": ["yandex_ru"],
    "comment": "123",
    "day_cost": 112,
    "budget": 3500
}]

Получение информации по кампании

GET http://api.webeffector.ru/seo/E1

{
    "id": "E1",
    "region": "Москва",
    "name": "Продвижение сайта webeffector.ru",
    "url": "http://www.webeffector.ru/",
    "mode": "DEFAULT",
    "pos": ["yandex_ru", "google_ru"],
    "top": ["yandex_ru"],
    "day_cost": 4,
    "budget": 5.0,
    "comment": "123",
    "success": {
        "yandex_ru": 1.0
    }
    "promos": [{
        "day_cost": 4.01,
        "positions": {
            "yandex_ru": 1,
            "google_ru": 4
        },
        "yesterday_positions": {
            "yandex_ru": 2,
            "google_ru": 4
        },
        "searcher_url": {
            "yandex_ru": "http://www.webeffector.ru/",
            "google_ru": "http://www.webeffector.ru/"
        }
        "id": "P1",
        "hits":1,
        "links_bought": 1,
        "word": "продвижение сайта",
        "url": "http://www.webeffector.ru/",
        "recommended_budget": 10,
        "yandex_geo": "UNKNOWN",
        "position": 5,
        "state": "WORK",
        "budget": 5.0
    }, {
        "day_cost": 0.0,
        "positions": {
            "yandex_ru": 3,
            "google_ru": 7
        },
        "searcher_url": {
            "yandex_ru": "http://www.webeffector.ru/pages/promo",
            "google_ru": "http://www.webeffector.ru/pages/promo"
        },
        "yesterday_positions": {
            "yandex_ru": 3,
            "google_ru": 7
        },
        "id": "P2",
        "hits":1,
        "links_bought": 0,
        "word": "реферальная программа",
        "url": "http://www.webeffector.ru/pages/promo",
        "position": 3,
        "state": "SLEEP",
        "budget": 10.0
    }]
}

Получение информации по продвижению

GET http://api.webeffector.ru/seo/E1/P1

{
    "id": "P1",
    "word": "деревянные окна",
    "url": "http://okna.ru/",
    "position": 5,
    "budget": 5.0,
    "state": "WORK",
    "day_cost": 4.01,
    "hits": 1,
    "recommended_budget": 10,
    "yandex_geo": "UNKNOWN",
    "positions": {
        "yandex_ru": 1,
        "google_ru": 4
    },
    "yesterday_positions": {
        "yandex_ru": 2,
        "google_ru": 4
    },
    "searcher_url": {
        "yandex_ru": "http://www.webeffector.ru/pages/promo",
        "google_ru": "http://www.webeffector.ru/pages/promo"
    },
    "anchors": [{
        "text": "#a#продвижение сайта#/a#.",
        "count": 1
    }],
    "links": [{
        "id": 1,
        "date": "2012-02-01",
        "url": "http://donor.ru/1.html",
        "text": "#a#продвижение сайта#/a#.",
        "price": 4.01
    }],
    "trends": {
        "yandex_ru": {
            "2012-04-01": 8,
            "2012-04-02": 17,
            "2012-04-03": 4
        },
        "google_ru": {
            "2012-04-01": 13,
            "2012-04-02": 14,
            "2012-04-03": 1
        }
    }
}

Поле anchors может быть пустым сразу после создания продвижения, т.к. генератор анкоров запускается раз в минуту.

Создание или обновление кампании

POST http://api.webeffector.ru/seo/E1

{

    "name": "№1 webeffector.ru",
    "id": "1",
    "url": "http://www.webeffector.ru/",
    "region": "Смоленск",
    "pos": ["yandex_ru", "google_ru"],
    "top": ["yandex_ru"],
    "promos": [{
        "id": "1",
        "state": "WORK",
        "url": "http://www.webeffector.ru/",
        "word": "сео для домохозяек",
        "budget": 100.0,
        "position": 3,
        "anchors": [{"text": "сео для домохозяек","count": 1 }]
    }]
}

Если у продвижения отсутствует поле anchors, то анкоры будут сгенерированы автоматически.

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

Создание или обновление продвижения

POST http://api.webeffector.ru/seo/E1/1

{
    "id": "1",
    "state": "WORK",
    "url": "http://www.webeffector.ru/",
    "word": "сео для домохозяек",
    "budget": 100.0,
    "position": 3,
    "anchors": [{"text": "сео для домохозяек","count": 1 }],
    "daily_limit": 1
}

Поле daily_limit количество ссылок закупаемых в день на данное продвижение, не учавствует в общем лимите для домена. Если значение отрицательное, то ссылки закупаются с обычной скоростью. Значение 0 используется для остановки закупок. Значение -1 для возврата продвижения к обычной закупке.

Если у продвижения отсутствует поле anchors, то анкоры будут сгенерированы автоматически.

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

DELETE http://api.webeffector.ru/seo/E1

Удаление продвижения

DELETE http://api.webeffector.ru/seo/E1/1

Удаление ссылок

Для удаления ссылки (ссылок) отправьте DELETE запрос на URL http://api.webeffector.ru/seo/{projectId}/{promotionId}/{linkIds}, где projectId это идентификатор проекта, promotionId идентификатор продвижения, а linkIds один или более идентификаторов ссылок, разделенных запятыми.

При удалении ссылки могут быть также добавлены в глобальный или проектный черный список. Для этого необходимо передать аргумент gbl или bl в URL. Например:

http://api.webeffector.ru/seo/{projectId}/{promotionId}/{linkIds}?bl=true&gbl=true

Поддерживаемые поисковые системы

["yandex_ru", "google_by", "google_ru","google_com", "google_ua"]

Поддерживаемые состояния продвижений

["WORK","SLEEP"]

Поддерживаемые регионы

regions.js

Ошибки

Ошибка 400 — вы указали неверные данные, каждый объект будет дополнен полем errors.
Ошибка 404 — вы указали неверные идентификаторы объектов в URL запроса.

Создание медиаплана

Создание медиаплана происходит следующим образом:

пользователь создаёт заявку. Заявке присваивается статус NEW
сервер начинает создание плана. Заявке присваивается статус RUNNING
после создания плана статус заявки устанавливается в FINISHED
пользователь запрашивает информацию о заявке, в которой содержится информация о медиаплане (поле result)

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

Создание заявки

Для создания заявки необходимо послать POST запрос на URL http://api.webeffector.ru/plans/{id} (вместо {id} подставьте любой уникальный идентификатор). В теле запроса необходимо передать:

URL сайта или страницы
название региона

Пример запроса:

{
        "url" : "http://example.org",
        "region" : "Москва",
}

Одновременно каждый пользователь может иметь не более 2 активных заявок. Иными словами, если у вас есть две заявки в статусе NEW или RUNNING, вы не сможете добавить ещё одну до тех пор, пока количество заявок в очереди не станет меньше разрешенного лимита.

Возвращаемое значение

Возвращает идентификатор заявки (тот же самый, что был передан пользователем). Код состояния HTTP при этом равен 202 Accepted.

Ошибки

Если переданные данные не прошли валидацию, то код состояния HTTP устанавливается в 400 Bad Request и возвращается JSON-объект с запросом и соответствующими ошибками:

{
        "id" : "2",
        "region" : "Антарктика",
        "url" : "http://example.org",
        "errors" : {
                "id" : [
                        {
                                "message" : "Id already in use",
                                "code" : "ValidPlanId"
                        }
                ],
                "region" : [
                        {
                                "message" : "Invalid region name",
                                "code" : "ValidRegionName"
                        }
                ]
        }
}

Если количество активных заявок превышает допустимый лимит ответ будет другим:

{
        "code" : "ACCESS_01",
        "message" : "Exceeded max allowed tasks in queue"
}

Просмотр заявок

Для просмотра заявок необходимо послать GET запрос на URL http://api.webeffector.ru/plans

[
        {
                "result" : [
                        {
                                "phrase" : "тест пример",
                                "page" : "/index.php",
                                "need_position" : 0,
                                "transitions_prediction" : 7,
                                "budget" : 100.0,
                                "period" : "3.98",
                                "deleted" : 0,
                                "relevancy_error" : 0
                        },
                        {
                                "phrase" : "example",
                                "page" : "/index.php",
                                "need_position" : 0,
                                "transitions_prediction" : 7,
                                "budget" : 100.0,
                                "period" : "3.98",
                                "deleted" : 0,
                                "relevancy_error" : 0
                        }
                ],
                "status" : "FINISHED",
                "id" : "2",
                "region" : "Москва",
                "url" : "http://example.org"
        }
]

Обратите внимание на массив объектов result, каждый из которых содержит следующие поля:

phrase: ключевое слово
page: релевантная страница (относительная)
need_position: требуемая позиция
transitions_prediction: прогнозируемое количество переходов
budget: бюджет на продвижение
period: период продвижения
deleted: признак удаления страницы (нет страницы, transitions_prediction = 0 или ещё какие-либо причины)
relevancy_error: во время попытки определить страницу произошла ошибка, но слово оставляем

Просмотр информации о заявке

Для просмотра информации о заявке необходимо послать GET запрос на URL http://api.webeffector.ru/plans/{id} (вместо {id} подставьте идентификатор заявки). Формат вывода такой же как и при просмотре всех заявок, с тем лишь исключением, что отображается только одна заявка.

Ошибки

При запросе несуществующей заявки возвращается 404 Not Found

Расчет бюджета

Расчет бюджета происходит следующим образом:

пользователь создаёт заявку. Заявке присваивается статус NEW
сервер начинает расчет бюджета. Заявке присваивается статус RUNNING
после вычисления бюджета статус заявки устанавливается в FINISHED
пользователь запрашивает информацию о заявке, в которой содержится результат расчетов (поле result)

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

Создание заявки

Для создания заявки необходимо послать POST запрос на URL http://api.webeffector.ru/budgets/{id} (вместо {id} подставьте любой уникальный идентификатор). В теле запроса необходимо передать:

название домена
название региона
массив с запросами для расчета бюджета (URL, фраза, желаемая позиция)

Пример запроса:

{
        "domain" : "example.org",
        "region" : "Москва",
        "queries": [
                {
                        "url" : "http://example.org",
                        "position" : 5,
                        "phrase" : "тест"
                }
        ]
}

Одна заявка может содержать до 50 запросов.

Возвращаемое значение

Ошибки

{
        "id" : "33",
                "domain" : "example.org",
                "queries" : [
                {
                        "position" : 0,
                        "url" : "",
                        "errors" : {
                                "position" : [
                                {
                                        "message" : "must be between 1 and 10",
                                        "code" : "Range"
                                }
                                ],
                                        "phrase" : [
                                        {
                                                "message" : "may not be empty",
                                                "code" : "NotBlank"
                                        }
                                ],
                                        "url" : [
                                        {
                                                "message" : "may not be empty",
                                                "code" : "NotBlank"
                                        }
                                ]
                        },
                        "phrase" : ""
                }
        ],
                "region" : "Антарктика",
                "errors" : {
                        "region" : [
                        {
                                "message" : "Invalid region name",
                                "code" : "ValidRegionName"
                        }
                        ],
                                "id" : [
                                {
                                        "message" : "Id already in use",
                                        "code" : "ValidBudgetId"
                                }
                        ]
                }
}

Если количество активных заявок превышает допустимый лимит ответ будет другим:

{
        "code" : "ACCESS_01",
        "message" : "Exceeded max allowed tasks in queue"
}

Просмотр заявок

Для просмотра заявок необходимо послать GET запрос на URL http://api.webeffector.ru/budgets

[
        {
                "id": "1",
                "domain": "example.org",
                "result": [
                        {
                                "phrase": "тест",
                                "cost": 500.0,
                                "current_position_number": 50.0,
                                "current_position_more_than_number": true,
                                "is_geo_dependent": false,
                                "promotion_term": 3.96,
                                "transitions_prediction": 2477
                        }
                ],
                "status": "FINISHED",
                "queries": [
                        {
                                "position": 1,
                                "url": "http://example.org",
                                "phrase": "тест"
                        }
                ],
                "region": "Новосибирск"
        }
]

Обратите внимание на массив объектов result, каждый из которых содержит следующие поля:

phrase: ключевое слово
cost: прогнозируемая стоимость продвижения, в рублях
current_position_number: текущая позиция продвигаемой страницы
current_position_more_than_number: признак того, что точная позиция получена не была, в этом случае текущая позиция продвигаемой страницы в выдаче будет больше, чем current_position_number. Например, если в системе установлено ограничение на проверку топ-50 позиций, а позиция страницы 5, то current_position_number = 5, current_position_more_than_number = false. Если позиция 55, то current_position_number = 50, current_position_more_than_number = true (т.к. значение > 50)
is_geo_dependent: флаг геозависимости запроса
promotion_term: прогнозируемый срок продвижения, в месяцах
transitions_prediction: прогнозируемое количество переходов

Просмотр информации о заявке

Для просмотра информации о заявке необходимо послать GET запрос на URL http://api.webeffector.ru/budgets/{id} (вместо {id} подставьте идентификатор заявки). Формат вывода такой же как и при просмотре всех заявок, с тем лишь исключением, что отображается только одна заявка.

Ошибки

При запросе несуществующей заявки возвращается 404 Not Found

Удаление заявки

Для удаления заявки необходимо послать DELETE запрос на URL http://api.webeffector.ru/budgets/{id} (вместо {id} подставьте идентификатор заявки).

Ошибки

При запросе несуществующей заявки возвращается 404 Not Found
При попытке удаления заявки в статусе RUNNING возвращается 403 Forbidden

Работа с черным списком

Черный список состоит из доменов на которых запрещено размещать ссылки. Обычно он наполняется вручную пользователем через веб-интерфейс, либо при удалении ссылок через вызовы API.

Существует два списка: глобальный, распространяющийся на все проекты пользователя, и локальный — для каждого конкретного проекта.

Просмотр глобального черного списка

Отправьте GET запрос на URL http://api.webeffector.ru/blacklist.

Просмотр черного списка проекта

Отправьте GET запрос на URL http://api.webeffector.ru/blacklist/{id} (вместо {id} подставьте идентификатор проекта).

Просмотр информации о пользователе

Отправьте GET запрос на URL http://api.webeffector.ru/user, чтобы получить информацию о текущем пользователе.

Возвращаемое значение

Пример:

{
        "id" : 1,
        "username" : "user",
        "email" : "user@example.org",
        "balance" : 110956.06,
        "accessible_balance" : 2622.44
}

Поля balance и accessible_balance представляют весь ваш баланс и доступный баланс (без зарезервированных средств).

План работ

Пополнение аккаунта
Доп. информация для продвижений (была ли заморозка и были ли заказаны вечные ссылки)