api-docs.apib

FORMAT: 1A
HOST: http://analitics.catkitcms.ru/api
VERSION: 1.4

# Аналитика

### Аутентификация

Для авторизации приложения используется механизм JWT токенов. При каждом
запросе к API должен передаваться HTTP-заголовок `User-Token`, содержащий
JWT токен.


Пример запроса к сервису:


```

curl -H 'User-Token: SOME-KEY' http://analitics.catkitcms.ru/api/

```

### REST

* GET - получение информации

* POST - создание новой записи

* PUT - обновление существующей записи

* DELETE - удаление записи

### Формат ответа


Успешный ответ будет возвращен как JSON-объект с одним из следующих
параметров:

- `data`: основные данные, возвращаемые при успешном создании запроса.

- `errors`: массив возвращаемых ошибок


Объекты `data` и` errors` не могут быть возвращены в одном запросе.


**Объект ответа**

Для одного объекта:

```json

{
    request: {
        query: {},
        body: {}
    },
    data: {
        id: 1,
        caption: 'First item'
    }
}

```

Для списка:

```json

{
    request: {
        query: {},
        body: {}
    },
    data: [
        {
            id: 1,
            caption: 'First item'
        }, {
            id: 2,
            caption: 'Second item'
        }
    ]
}

```

### История изменений

`2.0`

* Добавлен раздел `Источники трафика`;
* В раздел сайтов добавлен метод получения всех источников трафика для отдельного сайта;
* Из раздела сайтов удален метод получения всех кампаний сайта;
* Из кампаний удалено поле `site_id`, теперь кампании связаны с сайтами через источники трафика;
* Удален метод добавления новой кампании, теперь это происходит автоматически при синхронизации источников трафика;
* В методы получения информации о кампании добавлено поле `source_id`;
* Метод добавления расходов перенесет из раздела `Сайты` в раздел `Источники трафика` и добавлен способ добавления расхода на период;

`1.9`

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

`1.8`

* Добавлены методы для получения статистики всех объектов.

`1.7`

* Добавлено поле order для сайтов, позволяющее сортировать список произвольним образов,
а так же метод обновления информации сайта. Поле order используется для сортировки по умолчанию.
* Добавлена пагинация списка кампаний сайта.
* Для всех запросов с пагинацией добавлен заголовок RecordsCount с общим количеством найденных записей.

`1.6`

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

`1.5`

* Добавлены методы удаления настроек биддера для кампаний, групп объявлений и ключевых фраз.

`1.4`

* Изменены методы получения и установки настроек биддера для [кампаний](#кампании-get-4), [групп объявлений](#группы-объявлений-get-3) и [ключевых фраз](#ключевые-фразы-get-2).

`1.3`

* Добавлены методы получения статистики для [группы объявлений](#группы-объявлений-get-4) и [ключевой фразы](#ключевые-фразы-get-3)

`1.2`

* Добавлен метод задания [UTM меток для всех кампаний сайта](#сайты-put-1)
* Добавлена возможность сортировки списка сайтов проекта и общего списка сайтов
* Заявки проекта теперь могут [отображаться постранично](#проекты-get-6)
* Добавлен [календарь стоимости заказов проекта по датам](#проекты-get-7)
* Добавлен [временной таргетинг настроек биддера для кампании](#кампании-get-4)
* В [статистику кампании](#кампании-get-2) добавлено количество заявок
* В [настройки биддера кампании](#кампании-get-4) добавлена онформация о дочерних элементах с отдельными настройками.
* Настройки биддера и информация о запуске перенсены из общих настроек в [отдельный раздел управления биддером](#биддер)
* В [настройки биддера кампании](#кампании-get-4) добавлен показатель попадания кампании при последнем срабатывании биддера.

`1.1.1`

* В состояние биддера кампании добавлен [показатель попадания ставки](#кампании-get-4)

`1.1`

* Добавлена группа [настроек](#настройки)
* Изменен [метод добавления новой кампании](#кампании-post)
* Добавлен метод получения [групп объявлений кампании](кампании-get-7)
* Добавлен раздел [ключевых фраз](#ключевые-фразы)
* Добавлен метод [ключевых фраз кампании](#кампании-get-5)
* Добавлен метод [ключевых фраз группы объявлений](#группы-объявлений-get-1)



# Data Structures

## Project Statistics
+ Include Campaign Statistics
+ orders (number) - Кол-во заказов с сайтов проекта.

## Site Statistics
+ Include Campaign Statistics
+ orders (number) - Кол-во заказов с сайта

## Account
+ id: 0 (number) - ID

## Source
+ id: 0 (number) - ID
+ site_id: 0 (number) - ID свзанного сайта
+ type (string) -  Тип
+ caption (string) - Название
+ sriteria (string) - Строка для определения принадлежности заявки источнику трафика

## Campaign Statistics
+ cost: 0 (number) - Потраченная сумма(руб.).
+ views: 0 (number) - Кол-во просмотров рекламных объявлений за период.
+ clicks: 0 (number) - Кол-во кликов по рекламе за период.
+ calls: 0 (number) - Кол-во звонков
+ emails: 0 (number) - Кол-во писем

## Ad Group Statistics
+ cost: 0 (number) - Потраченная сумма(руб.).
+ views: 0 (number) - Кол-во просмотров за период.
+ clicks: 0 (number) - Кол-во кликов по рекламе за период.
+ calls: 0 (number) - Кол-во звонков с указанным utm_term, принадлежащим этой группе объявлений
+ emails: 0 (number) - Кол-во писем с указанным utm_term, принадлежащим этой группе объявлений

## Keyword Statistics
+ cost: 0 (number) - Потраченная сумма(руб.).
+ views: 0 (number) - Кол-во просмотров за период.
+ clicks: 0 (number) - Кол-во кликов по рекламе за период.
+ calls: 0 (number) - Кол-во звонков с указанным utm_term для данного ключевого слова
+ emails: 0 (number) - Кол-во писем с указанным utm_term для данного ключевого слова



## Project Statistics Details
+ data: 'string' (array,fixed)
    + (object)
        + time (string) - Время, за которое предоставляется стастистика (в формате UTC).
        + statistics (object) - Объект со статистикой за указанное время
            + Include Project Statistics

## Site Statistics Details
+ data: 'string' (array,fixed)
    + (object)
        + time (string) - Время, за которое предоставляется стастистика (в формате UTC).
        + statistics (object) - Объект со статистикой за указанное время
            + Include Site Statistics

## Campaign Statistics Details
+ data: 'string' (array,fixed)
    + (object)
        + time (string) - Время, за которое предоставляется стастистика (в формате UTC).
        + statistics (object) - Объект со статистикой за указанное время
            + Include Campaign Statistics

## Ad Group Statistics Details
+ data: 'string' (array,fixed)
    + (object)
        + time (string) - Время, за которое предоставляется стастистика (в формате UTC).
        + statistics (object) - Объект со статистикой за указанное время
            + Include Ad Group Statistics

## Keyword Statistics Details
+ data: 'string' (array,fixed)
    + (object)
        + time (string) - Время, за которое предоставляется стастистика (в формате UTC).
        + statistics (object) - Объект со статистикой за указанное время
            + Include Keyword Statistics



## Project
+ id: 0 (number) - ID проекта
+ caption: 0 (number) - Заголовок
+ icon (string) - Иконка

## Site
+ id: 0 (number) - ID сайта
+ domain (string) - Доменное имя сайта

## Campaign
+ id: 0 (number) - ID кампании
+ site_id: 0 (number) - ID сайта, к которому привязана кампания
+ caption (string) - Заголовок кампании

## Keyword
+ id: 0 (number) - ID ключевой фразы
+ keyword (string) - Ключевая фраза

## Ad
+ id: 0 (number) - ID объявления

## AdGroup
+ id: 0 (number) - ID группы
+ caption (string) - Заголовок группы

## Lead
+ site_id: 0 (number) - ID сайта
+ type (enum[string]) - Тип заявки
    + Members
        + email - Письмо с сайта
        + call - Звонок
+ source (string) - Источник заявки
+ campaign (string) - Кампания
+ keyword (string) - Ключевое слово
+ place (string) - Место показа
+ time (string) - Время заявки


## Bid Option
+ max: 0 (number) - Максимальная ставка
+ position (enum[string]) - Позиция, строка по формуле Pnm, где n - , m -
    + Members
        + P11
        + P12
        + P13
        + P14
        + P21
        + P22
+ increment: 0 (number) - Процент завышения ставки
+ active (boolean) - Статус (включено/выключено)
+ day_num: 0 (number,required) - Порядковый номер дня недели от 0 (понедельник) до 6, для которого должны применяться настройки
+ hour_num: 0 (number,required) - Порядковый номер часа от 0 до 23, для которого должны применяться настройки

## Bid Options

## Ordering
+ order (string, optional) - Поле для сортировки
+ reverse (boolean, optional) - Сортировка в обратном порядке
+ page: '2,50' (string,optional) - Номер страницы списка (начиная от 1) и количество результатов на странице, разделенные запятыми













## Проекты [/projects]

### Список проектов [GET]

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (Project)

### Детали проекта [GET/projects/{id}]

+ Parameters
    + id: 0 (number, required) - ID проекта

+ Response 200 (application/json)
    + Attributes
        + Include Project

### Создать новый проект [POST/projects]

+ Request
    + Attributes
        + caption (string,required) - Название источника
        + caption (string) - Иконка

+ Response 200 (application/json)
    + Attributes
        + data
            + id: 0 (number) - ID добавленного проекта

### Обновить данные проекта [PUT/projects]

+ Request
    + Attributes
        + caption (string,required) - Название источника
        + caption (string) - Иконка

+ Response 200 (application/json)
    + Attributes
        + data

### Список сайтов [GET/projects/{id}/sites?{order}=&{reverse}=&{page}=]

+ Parameters
    + id: 0 (number, required) - ID проекта

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (Site)

### Список кампаний [GET/projects/{id}/campaigns?{order}=&{reverse}=&{page}=]]

+ Parameters
    + id: 0 (number, required) - ID проекта
    + order (string, optional) - Поле для сортировки
    + reverse (boolean, optional) - Сортировка в обратном порядке
    + page: '2,50' (string,optional) - Номер страницы списка (начиная от 1) и количество результатов на странице, разделенные запятыми

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (Campaign)

### Общая статистика проекта [GET/projects/{id}/statistics/summary?{from}=&{to}=]
Возвращает объект с суммой статистик по кампаниям проекта за указанный период.

+ Parameters
    + id: 0 (number, required) - ID проекта
    + from (string, required) - Дата начала периода в формате `YYYY-mm-dd`.
    + to (string, optional) - Дата окончания периода (опционально для периода больше 1 дня).

+ Response 200 (application/json)
    + Attributes (Project Statistics)


### Подробная статистика проекта [GET/projects/{id}/statistics/details?{from}=&{to}=]

Возвращает массив объектов с суммой почасовых статистик по всем кампаниям проекта за указанный период.

+ Parameters
    + id: 0 (number, required) - ID проекта
    + from (string, required) - Дата начала периода в формате `YYYY-mm-dd`.
    + to (string, optional) - Дата окончания периода (опционально для периода больше 1 дня).

+ Response 200 (application/json)
    + Attributes (Project Statistics Details)

### Список заявок [GET/projects/{id}/leads?{from}=&{to}=&{order}=&{reverse}=&{page}]

+ Parameters
    + id: 0 (number, required) - ID проекта
    + from (string, required) - Дата начала периода в формате `YYYY-mm-dd`.
    + to (string, optional) - Дата окончания периода (опционально для периода больше 1 дня).
    + order (string, optional) - Поле для сортировки
    + reverse (boolean, optional) - Сортировка в обратном порядке
    + page: '2,50' (string,optional) - Номер страницы списка (начиная от 1) и количество результатов на странице, разделенные запятыми

+ Response 200 (application/json)
    + Attributes
        + data: 'string' (array,fixed)
            + (Lead)
                + phone (string) - Номер телефона
                + unique: 0 (number) - (опционально для звонков) Флаг уникальности звонка
                + duration: 0 (number) - (опционально для звонков) Длительность звонка

### Календарь стоимости заказа [GET/projects/{id}/orders/cost?{from}=&{to}=]

Возвращает среднюю стоимость заказа за день по всем кампаниям проекта. Для расчета учитывается количество заказов и сумма расходов по всем кампаниям, полученная из статистики.

+ Parameters
    + id: 0 (number, required) - ID проекта
    + from (string, required) - Дата начала периода в формате `YYYY-mm-dd`.
    + to (string, optional) - Дата окончания периода (опционально для периода больше 1 дня).

+ Response 200 (application/json)
    + Attributes
        + data: 'string' (array,fixed)
            + (object)
                + date (string) - Дата
                + cost: 0 (number) - Стоимость клика















## Аккаунты [/accounts]

### Список доступных типов и настроек [GET/accounts/types]

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (object)
                + type: 0 (number) - Ключ для типа аккаунта
                + human (string) - Название типа
                + options (array,fixed)
                    + name (string) - Поле для настройки
                    + caption (string) - Название поля

### Список аккаунтов [GET/accounts]

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (Account)


### Подробная информация и настройки [GET/accounts/{id}]

+ Parameters
    + id: 0 (number, required) - ID аккаунта

+ Response 200 (application/json)
    + Attributes
        + Include Source
        + type (string) - Тип аккаунта
        + human (string) - Название типа аккаунта
        + caption (string) - Название
        + options (array,fixed)
            + name (string) - Настройка
            + value (string) - Значение

### Добавить новый аккаунт [POST]

+ Request
    + Attributes
        + type (string, required) - Тип аккаунта
        + caption (string,required) - Название аккаунта
        + options (object) - Массив настроек аккаунта в виде name-value
            + `name - value`

+ Response 200 (application/json)
    + Attributes
        + data
            + id: 0 (number) - ID добавленного аккаунта

### Редактировать аккаунт [PUT]

+ Request
    + Attributes
        + caption (string,required) - Новое название аккаунта
        + options (object) - Массив настроек аккаунта в виде name-value
            + `name - value`

+ Response 200 (application/json)
    + Attributes
        + data
            + id: 0 (number) - ID аккаунта

### Удалить аккаунт [DELETE/accounts/{id}]

+ Parameters
    + id: 0 (number) - ID аккаунта

+ Response 200 (application/json)

### Список локальных кампаний аккаунта [GET/accounts/{id}/campaigns]

Возвращает список добавленных кампаний, принадлежащих аккаунту.

+ Parameters
    + id: 0 (number) - ID аккаунта

+ Response 200 (application/json)
    + Attributes
        + data
            + id: 0 (number)
            + rel_id: 0 (number)
            + caption

### Загрузить список кампаний аккаунта [GET/accounts/{id}/campaigns/load]

Загружает с соответствующего аккаунту сервера список кампаний.

+ Parameters
    + id: 0 (number) - ID аккаунта

+ Response 200 (application/json)
    + Attributes
        + data
            + id: 0 (number)
            + caption










## Сайты [/sites]

### Добавить новый сайт [POST]

+ Request
    + Attributes
        + project_id: 0 (number, required) - ID проекта, к которому относится сайт.
        + domain (string, required) - Доменное имя сайта.

+ Response 200 (application/json)
    + Attributes
        + data
            + id: 0 (number) - ID добавленного сайта

### Детали сайта [GET/sites/{id}]

+ Parameters
    + id: 0 (number) - ID сайта.

+ Response 200 (application/json)
    + Attributes (Site)
        + project_id: 0 (number) - ID проекта, которому принадлежит сайт

### Удалить сайт [DELETE/sites/{id}]

Отмечает сайт, а так же все его источники трафика и кампании, удаленными.

+ Parameters
    + id: 0 (number) - ID сайта.

+ Response 200 (application/json)

### Список источников трафика [GET/sites/{id}/sources?{order}=&{reverse}=]

+ Parameters
    + id: 0 (number) - ID сайта.
    + order (string, optional) - Поле для сортировки
    + reverse (boolean, optional) - Сортировка в обратном порядке

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (Source)

### Добавление заказа [POST/sites/{id}/orders]

+ Parameters
    + id: 0 (number) - ID сайта.

+ Request
    + Attributes
        + count (number, optional) - Количество заказов (позволяет создать заказ с количеством более 1).
        + comment (string, optional) - Комментарий к заказу.
        + time (string, optional) - Время заказа в формате `Y-m-d H:i:s` (по умолчанию будет установлено текущее время).

+ Response 200 (application/json)
    + Attributes
        + id: 0 (number) - ID добавленного заказа

### Общая статистика сайта [GET/sites/{id}/statistics/summary?{from}=&{to}=]

Возвращает объект с суммой статистик по всем кампаниям, принадлежащим сайту, за указанный период.

+ Parameters
    + id: 0 (number, required) - ID сайта
    + from (string, required) - Дата начала периода в формате `YYYY-mm-dd`.
    + to (string, optional) - Дата окончания периода (опционально для периода больше 1 дня).

+ Response 200 (application/json)
    + Attributes (Site Statistics)

### Подробная статистика сайта [GET/sites/{id}/statistics/details?{from}=&{to}=]

Возвращает массив объектов с суммой почасовых статистик по всем кампаниям проекта за указанный период.

+ Parameters
    + id: 0 (number, required) - ID сайта
    + from (string, required) - Дата начала периода в формате `YYYY-mm-dd`.
    + to (string, optional) - Дата окончания периода (опционально для периода больше 1 дня).

+ Response 200 (application/json)
    + Attributes (Site Statistics Details)

### Обновление статистики сайта [PUT/sites/{id}/statistics?{date}]

+ Parameters
    + id: 0 (number, required) - ID сайта
    + date (string, required) - Дата для изменения статистики

+ Request
    + Attributes
        + orders: 0 (number) - Количество заказов за указанный в date день

+ Response 200 (application/json)

### Обновление UTM меток [PUT/sites/{id}/utm?{method}]

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

+ Parameters
    + id: 0 (number, required) - ID сайта
    + method (enum[string], optional) - Способ задания меток
        + Default
            all
        + Members
            + only - Установить только заданные метки, остальные удалить
            + replace - Обновить заданные метки, остальные не изменять. Выбран по умолчанию
            + all - Обновить заданные метки, остальные очистить

+ Request
    + Attributes
        + utm_source (string, optional)
        + utm_medium (string, optional)
        + utm_campaign (string, optional)
        + utm_content (string, optional)
        + utm_term (string, optional)

+ Response 200 (application/json)

### Обновление данных сайта [PUT/sites/{id}]

Обновление информации сайта.

+ Parameters
    + id: 0 (number, required) - ID сайта

+ Request
    + Attributes
        + domain (string) - Доменное имя
        + order: 0 (number) - Значение для сортировки по умолчанию

+ Response 200 (application/json)









## Источники трафика [/sources]

### Подробная информация и настройки [GET/sources/{id}]

+ Parameters
    + id: 0 (number, required) - ID источника трафика

+ Response 200 (application/json)
    + Attributes
        + Include Source

### Добавить новый источник трафика [POST]

+ Request
    + Attributes
        + site_id: 0 (number, required) - ID сайта, к которому относится источник
        + type (string, required) - Ключ типа источника
        + caption (string,required) - Название источника
        + criteria (string,required) - Строка для определения принадлежности заявки источнику трафика

+ Response 200 (application/json)
    + Attributes
        + data
            + id: 0 (number) - ID добавленного источника

### Редактировать источник трафика [PUT]

+ Request
    + Attributes
        + site_id: 0 (number, required) - ID сайта, к которому относится источник
        + caption (string,required) - Название источника
        + criteria (string,required) - Строка для определения принадлежности заявки источнику трафика

+ Response 200 (application/json)
    + Attributes
        + data
            + id: 0 (number) - ID источника

### Удалить источник [DELETE/sources/{id}]

Отмечает источник трафика, а так же все его кампании, удаленными.

+ Parameters
    + id: 0 (number) - ID источника

+ Response 200 (application/json)


### Список кампаний источника трафика [GET/sources/{id}/campaigns]

+ Parameters
    + id: 0 (number) - ID аккаунта

+ Response 200 (application/json)
    + Attributes
        + data
            + id: 0 (number)
            + rel_id: 0 (number)
            + caption

### Добавление произвольного расхода [POST/sources/{id}/costs]

+ Parameters
    + id: 0 (number) - ID источника трафика.

+ Request
    + Attributes
        + cost (number, required) - Сумма расхода.
        + comment (string, optional) - Комментарий к расходу.
        + date (object, optional) - Период расхода в виде интервала; если не указано, будет установлено текущее время
            + from (string) - Дата в формате `Y-m-d`
            + to (string) - Дата в формате `Y-m-d`

+ Response 200 (application/json)
    + Attributes
        + data






## Кампании [/campaigns]

### Список кампаний [GET]

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (Campaign)
                + site_id: 0 (number) - ID сайта, которому принадлежит кампания

### Детали кампании [GET/campaigns/{id}]

+ Parameters
    + id: 0 (number) - ID кампании

+ Response 200 (application/json)
    + Attributes (Campaign)
        + site_id: 0 (number) - ID сайта, которому принадлежит кампания
        + type (string) - Тип кампании
        + num: 0 (number) - Номер кампании в системе статистики
        + bids: 'string' (array,fixed) - Настройки биддера для кампании
            + (object)
                + current: 'string' (array,fixed) - Настройки для текущего времени
                    + (object)
                        + max: 0 (number)
                        + position (string)

### Удалить кампанию [DELETE/campaigns/{id}]

+ Parameters
    + id: 0 (number) - ID кампании

+ Response 200 (application/json)

### Общая статистика кампании [GET/campaigns/{id}/statistics/summary?{from}=&{to}=]

Возвращает объект с суммой статистик кампании за указанный период.

+ Parameters
    + id: 0 (number, required) - ID кампании
    + from (string, required) - Дата начала периода в формате `YYYY-mm-dd`.
    + to (string, optional) - Дата окончания периода (опционально для периода больше 1 дня).

+ Response 200 (application/json)
    + Attributes (Campaign Statistics)

### Подробная статистика кампании [GET/campaigns/{id}/statistics/details?{from}=&{to}=]

Возвращает массив объектов с суммой почасовых статистик кампании за указанный период.

+ Parameters
    + id: 0 (number, required) - ID кампании
    + from (string, required) - Дата начала периода в формате `YYYY-mm-dd`.
    + to (string, optional) - Дата окончания периода (опционально для периода больше 1 дня).

+ Response 200 (application/json)
    + Attributes (Campaign Statistics Details)

### Текущие настройки биддера [GET/campaigns/{id}/bids]

Возвращает список настроек биддера для кампании, а так же информацию о дочерних элементах с индивидуальными настройками биддера. Каждая настройка представляет собой параметры для одного часа (опция `hour_num`) определенного дня недели (опция `day_num`), и биддер будет запущен только в это время, в остальные, не указанные, диапазоны биддер выполняться не будет.

+ Parameters
    + id: 0 (number, required) - ID кампании

+ Response 200 (application/json)
    + Attributes
        + data
            + options (array, fixed)
                + (Bid Option)
                    + hit: 0 (number) - Показатель попадания ставки в процентах за указанный час. Отражает количество ставок, процент завышения которых не превышал максимальное значение, к общему количеству ставок по кампании. В расчет принимаются только ставки, сделанные по этой группе настроек, - если настройки биддера для кампании были переопределены настройками группы объявлений и/или ключевой фразы, они не учитываются. Значение для группы настроек обновляется при каждом ее использовании биддером.
            + overrides (object) - список ID дочерних элементов, которые переопределяют настройки кампании
                + ag_groups: 'string' (array, fixed) - Группы объявлений кампании, для которых указаны другие настройки биддера
                     + (object)
                        + id: 0 (number) - ID группы объявлений
                        + name (string) - Название группы объявлений
                + keywords: 'string' (array, fixed) - Ключевые фразы кампании, для которых указаны другие настройки биддера
                    + (object)
                        + id: 0 (number) - ID ключевой фразы
                        + ad_group_id: 0 (number) - ID группы объявлений, к которой принадлежит ключевая фраза
                        + keyword (string) - Текст ключевой фразы
            + hit: 0 (number) - Показатель попадания ставки в процентах, рассчитанный при последнем срабатывании биддера для этой кампании.

### Обновить настройки биддера [PUT/campaigns/{id}/bids]

Устанавливает новый набор настроек биддера для кампании. Все прежние диапазоны настроек будут удалены.

+ Parameters
    + id: 0 (number, required) - ID кампании

+ Request
    + Attributes
        + data (array,fixed)
            + (Bid Option)

+ Response 200 (application/json)

### Список ключевых фраз [GET/campaigns/{id}/keywords?{mask}=&{page}=&]

Возвращает нужное кол-во ключевых фраз, принадлежащих кампании.

+ Parameters
    + id: 0 (number, required) - ID кампании
    + mask (string, optional) - Маска для подбора ключевых фраз. Если маска не указана, ключевые фразы не будут фильтроваться.
    + page: '2,50' (string,optional) - Номер страницы списка (начиная от 1) и количество результатов на странице, разделенные запятыми

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (Keyword)

### Список групп объявлений [GET/campaigns/{id}/ad_groups?{page}=&]

+ Parameters
    + id: 0 (number, required) - ID кампании
    + page: '2,50' (string,optional) - Номер страницы списка (начиная от 1) и количество результатов на странице, разделенные запятыми

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (AdGroup)

### Обновить содержимое кампании [GET/campaigns/{id}/sync]

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

+ Parameters
    + id: 0 (number, required) - ID кампании

+ Response 200 (application/json)

### Удалить настройки биддера [DELETE/campaigns/{id}/bids]

+ Parameters
    + id: 0 (number, required) - ID кампании

+ Response 200 (application/json)













## Группы объявлений [/ad_groups]

### Список групп [GET]

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (AdGroup)

### Детали группы [GET/ad_groups/{id}]

+ Parameters
    + id: 0 (number, required) - ID фразы

+ Response 200 (application/json)
    + Attributes
        + Include AdGroup
        + bids (array,fixed) - Настройки биддера для группы
            + (object)
                + current: 'string' (array,fixed) - Настройки для текущего времени
                    + (object)
                        + max: 0 (number)
                        + position (string)

### Список ключевых фраз [GET/ad_groups/{id}/keywords?{mask}=&{page}=&]

Возвращает нужное кол-во ключевых фраз, принадлежащих группе объявлений.

+ Parameters
    + id: 0 (number, required) - ID группы объявлений
    + mask (string, optional) - Маска для подбора ключевых фраз. Если маска не указана, ключевые фразы не будут фильтроваться.
    + page: '2,50' (string,optional) - Номер страницы списка (начиная от 1) и количество результатов на странице, разделенные запятыми

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (Keyword)

### Текущие настройки биддера [GET/ad_groups/{id}/bids]

+ Parameters
    + id: 0 (number, required) - ID группы объявлений

+ Response 200 (application/json)
    + Attributes
        + data
            + options: 'string' (array, fixed)
                + (Bid Option)
            + overrides (object) - список ID дочерних элементов, которые переопределяют настройки кампании
                + keywords: 'string' (array, fixed) - Ключевые фразы кампании, для которых указаны другие настройки биддера
                    + (object)
                        + id: 0 (number) - ID ключевой фразы
                        + keyword (string) - Текст ключевой фразы

### Обновить настройки биддера [PUT/ad_groups/{id}/bids]

+ Parameters
    + id: 0 (number, required) - ID группы объявлений

+ Request
    + Attributes (Bid Option)

+ Response 200 (application/json)

### Общая статистика группы объявлений [GET/ad_groups/{id}/statistics/summary?{from}=&{to}=]
Возвращает объект с суммой статистик всех ключевых фраз, принадлежащих группе объявлений, за указанный период.

+ Parameters
    + id: 0 (number, required) - ID группы объявлений
    + from (string, required) - Дата начала периода в формате `YYYY-mm-dd`.
    + to (string, optional) - Дата окончания периода (опционально для периода больше 1 дня).

+ Response 200 (application/json)
    + Attributes
        + data (Ad Group Statistics)

### Удалить настройки биддера [DELETE/ad_groups/{id}/bids]

+ Parameters
    + id: 0 (number, required) - ID группы объявлений

+ Response 200 (application/json)










## Ключевые фразы [/keywords]

Из-за большого количества записей нет возможности их динамической подгрузки из ресурсов поисковых систем.  В связи с этим, все методы, возвращающие список ключевых фраз, предоставляют только их снимок, который автоматически синхронизируется в течение некоторого времени. Так же при необходимости можно запустить синхронизацию немедленно, вызвав метод [campaigns::sync](#кампании-get-8)

### Детали ключевой фразы [GET/keywords/{id}]

+ Parameters
    + id: 0 (number, required) - ID фразы

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (Keyword)
                + campaign_id: 0 (number) - ID кампании, которой принадлежит фраза
                + ad_group_id: 0 (number) - ID группы объявлений, которой принадлежит фраза
                + bids: 'string' (array,fixed) - Настройки биддера для фразы
                    + (object)
                        + current: 'string' (array,fixed) - Настройки для текущего времени
                            + (object)
                                + max: 0 (number)
                                + position (string)


### Поиск фразы [GET/keywords/seach?{mask}=&{count}=]

Возвращает заданное количетсво ключевых фраз, подходящих по маске.
Метод медленный, рекомендуется к использованию только в случае, когда неизвестны ID кампании и/или группы объявлений.

+ Parameters
    + mask (string, required) - Маска для подбора ключевых фраз
    + count: 5 (number, optional) - Кол-во результатов

+ Response 200 (application/json)
    + Attributes
        + data (array,fixed)
            + (Keyword)
                + campaign_id: 0 (number) - ID кампании, которой принадлежит фраза
                + ad_group_id: 0 (number) - ID группы объявлений, которой принадлежит фраза


### Текущие настройки биддера [GET/keywords/{id}/bids]

+ Parameters
    + id: 0 (number, required) - ID ключевой фразы

+ Response 200 (application/json)
    + Attributes
        + data
            + options: 'string' (array, fixed)
                + (Bid Option)

### Обновить настройки биддера [PUT/keywords/{id}/bids]

+ Parameters
    + id: 0 (number, required) - ID ключевой фразы

+ Attributes (Bid Option)

+ Response 200 (application/json)

### Общая статистика ключевой фразы [GET/keywords/{id}/statistics/summary?{from}=&{to}=]
Возвращает объект с суммой статистик для ключевой фразы за указанный период.

+ Parameters
    + id: 0 (number, required) - ID ключевой фразы
    + from (string, required) - Дата начала периода в формате `YYYY-mm-dd`.
    + to (string, optional) - Дата окончания периода (опционально для периода больше 1 дня).

+ Response 200 (application/json)
    + Attributes
        + data (Keyword Statistics)

### Удалить настройки биддера [DELETE/keywords/{id}/bids]

+ Parameters
    + id: 0 (number, required) - ID ключевой фразы

+ Response 200 (application/json)






## Биддер [/bidder]

### Получить информацию о запуске биддера [GET/bidder/info]

+ Response 200 (application/json)
    + Attributes
        + data
            + period: 0 (number) - Интервал запуска биддера в минутах
            + last_run (string) - Время последнего запуска

### Обновить настройки запуска биддера [PUT/bidder/period]

+ Request
    + Attributes
        + period: 0 (number) - Интервал запуска биддера в минутах

+ Response 200 (application/json)








## Звонки [/calls]

### Добавление информации о новом звонке [GET/calls/push]

+ Request
    + Attributes
        + unique
        + site
        + callerphone
        + duration
        + reclink
        + timestamp
        + utm_source
        + utm_medium
        + utm_campaign
        + utm_content
        + utm_term

+ Response 200 (application/json)


## Сервис общей статистики [/statistics]

Сервис предоставляет предварительно кэшированную статистику для всех ресурсов с возможностью сортировки и пагинации.

* Каждый ресурс принимает параметры `from` и `to` для определения диапазона, за который необходимо получить статистику. При указании только параметра `from` будет отображена статистика только за 1 день.

* Каждый ресурс принимает дополнительные параметры `page=page,count`, `order=field`, `reverse=1` и возвращает заголовок `RecordsCount` с общим количеством найденных результатов.

* Все уточняющие параметры взаимно дополняют друг-друга.

### Статистика ключевых фраз [GET/statistics/keywords?{campaign_id}=&{ad_group_id}=&{keyword_ids}=]

+ Parameters
    + campaign_id: 0 (number) - ID кампании для подбора ключевых фраз
    + ad_group_id: 0 (number) - ID группы объявлений для подбора ключевых фраз
    + keyword_ids: 'string' (array) - список ID ключевых фраз (массив, или разделенные запятой значения)

+ Response 200 (application/json)
    + Attributes
        + data (Keyword Statistics)
            + ctr: 0 (number) - CTR
            + lead_perc: 0 (number) - Суммарное число заявок/клики
            + lead_cost: 0 (number) - Суммарное число заявок/расход
            + order_perc: 0 (number) - Заказы/суммарное число заявок
            + order_cost: 0 (number) - Заказы/расход
            + orders: 0 (number) - Кол-во заказов.

### Статистика групп объявлений [GET/statistics/ad_groups?{campaign_id}=&{ad_group_ids}=]

+ Parameters
    + campaign_id: 0 (number) - ID кампании для подбора групп объявлений
    + ad_group_ids: 'string' (array) - список ID групп объявлений (массив, или разделенные запятой значения)

+ Response 200 (application/json)
    + Attributes
        + data (Ad Group Statistics)
            + ctr: 0 (number) - CTR
            + lead_perc: 0 (number) - Суммарное число заявок/клики
            + lead_cost: 0 (number) - Суммарное число заявок/расход
            + order_perc: 0 (number) - Заказы/суммарное число заявок
            + order_cost: 0 (number) - Заказы/расход
            + orders: 0 (number) - Кол-во заказов.

### Статистика кампаний [GET/statistics/campaigns?{site_id}=&{campaign_ids}=]

+ Parameters
    + site_id: 0 (number) - ID сайта для подбора кампаний
    + campaign_ids: 'string' (array) - список ID кампаний (массив, или разделенные запятой значения)

+ Response 200 (application/json)
    + Attributes
        + data (Campaign Statistics)
            + ctr: 0 (number) - CTR
            + lead_perc: 0 (number) - Суммарное число заявок/клики
            + lead_cost: 0 (number) - Суммарное число заявок/расход
            + order_perc: 0 (number) - Заказы/суммарное число заявок
            + order_cost: 0 (number) - Заказы/расход
            + orders: 0 (number) - Кол-во заказов.

### Статистика сайтов [GET/statistics/campaigns?{project_id}=&{site_ids}=]

+ Parameters
    + project_id: 0 (number) - ID проекта для подбора сайтов
    + site_ids: 'string' (array) - список ID сайтов (массив, или разделенные запятой значения)

+ Response 200 (application/json)
    + Attributes
        + data (Site Statistics)
            + orders: 0 (number) - Кол-во заказов.

### Статистика проектов [GET/statistics/projects?{project_id}=]

+ Parameters
    + project_id: 0 (number) - ID проекта для получения статистики

+ Response 200 (application/json)
    + Attributes
        + data (Site Statistics)
            + ctr: 0 (number) - CTR
            + lead_perc: 0 (number) - Суммарное число заявок/клики
            + lead_cost: 0 (number) - Суммарное число заявок/расход
            + order_perc: 0 (number) - Заказы/суммарное число заявок
            + order_cost: 0 (number) - Заказы/расход
            + orders: 0 (number) - Кол-во заказов.